Heimdal Security allows you to easily access statistics about your endpoints, detections found and applications deployed via our software.
To obtain all that, we provide API keys that you can customise and use them in the software preferred by your organization to extract and manage the data already available in our portal.
Currently, we have 2 different API types: old and new.
The Old API will remain functional as there are still clients using it but it extracts data in bulk, without the possibility to change the filters and can be accessed directly from URL.
The New API is split into modules, to filter for individual results and the Key, which previously was inserted at the end of the URL, will be added in the Authentication header as OAUTH2 or Bearer authentication type.
When you expand the API Authentication menu a short description with an example of how an authorized request that includes the API Key should be created.
These are the 6 API requests that can be used:
- For Customers Details (parameter: customers) – to retrieve information about a specific customer or for all customers of a reseller (if you are reseller/admin/super admin)
- For Dark Layer Guard Statistics (parameter: darklayerguard) – to retrieve information about a customer’s DLG statistics
- For Microsoft Updates Statistics (parameter: microsoftupdates) – to retrieve information about a customer’s Microsoft updates
- For Third Party Statistics (parameter: thirdparty) – to retrieve information about a customer’s Third Party statistics
- For VectorN Statistics (parameter: vectorn) – to retrieve information about a customer’s VectorN statistics
- For Vigilance Detections Statistics (parameter: vigilancedetections) – to retrieve information about a customer’s Vigilance Detections statistics
The Old API filters the request based on Day-Month-Year with the time automatically set at the start to 12:00:00 AM and at the end to 1:59:59 PM.
The New API offers the possibility, along Day-Month-Year, to input the Hour-Minutes as well. If no value is selected for the dates, it will give the first day at start date and the current day for end date and if there is no time inserted, it will automatically set the start and end at 12:00 AM.
Except for Customers and DarkLayer Guard, all the other API requests have an additional parameter which can take different values. To check what values are available for a parameter you have to click on Show … Optional Parameter Helper that will expand the area.
How to configure the API URL:
The URL that will make the request will have the following form:
- dashboard_environment: the environment for the desired dashboard: dashboard or rc-dashboard
- heimdal_module: one of the 6 API requests that can be interrogated
- customerId: the ID of the customer for which you want to extract data about
- start_date: the start date since when the data will be retrieved
- end_date: the end date when the data will stop being retrieved
- optional_parameter: the optional parameter that some modules have which allows filtering the retrieved data (the optional parameters are presented on Dashboard on the new API tab for each module API request format)
- value_for_optional_parameter: the value that must be inserted for the optional parameter specific for each module
The date format for START DATE and END DATE parameter is: YYYY-mm-DDTHH:MM
- YYYY – the year (ex: 2018)
- mm – the month (ex: 02 for February)
- DD – the day (ex: 15)
- T – character required if the date will contain HOUR and MINUTES
- HH – the hour (ex: 18)
- MM – the minute (ex: 08)
The customer ID can be found after selecting the desired client in the Dashboard under Guide – API, in the API Authentication example as you expand it.
How to configure SPLUNK:
After you installed the application, from the Splunk main page click on Explore Splunk Enterprise and go to Splunk Apps, which will open a new window with all the apps and extensions available for installation.
In this new page you have to search for REST API Modular Input (found also on this page https://splunkbase.splunk.com/app/1546/)
After you have installed REST you can configure it with the API keys to be able to extract data. These are the steps to follow and fields that need to be completed.
Go to Settings -> Data – Data inputs -> REST -> + Add new
The following fields must be completed:
- REST API Input Name: The name you want for the job
- Activation Key: Follow the link under the text field to obtain an activation key (http://www.baboonbones.com/#activation) or use a key that you already have
- Endpoint URL: Insert the path to the API request (ex: https://dashboard.heimdalsecurity.com/api/heimdalapi/thirdparty )
- HTTP Method: Select GET
- Authentication Type: Select OAuth2
- OAUTH 2 Token Type (OPTIONAL): Type "Bearer" in case the authentication does not work
- OAUTH 2 Access Token: Your Personal API KEY from the Dashboard -> Guide -> HS API KEY -> New API/Old API
- URL Arguments: Here you have to insert the parameters for the API Requests. The required parameters are customerId, startDate and endDate (ex: customerId=197818,startDate=2016-01-03T12:54,endDate=2019-02-03T12:56). You can also type additional parameters, that are found under each API Statistics when you click on Show … Optional Parameter Helper in Dashboard -> Guide -> Your HS API Key – New API
*Make sure that the arguments are followed by the sign “,” (comma), as shown in the Splunk examples and not with the sign “&” (ampersand) as the examples from the Dashboard because this will lead to the error message "User is not authorized to fulfill the operation." when executing the job.
- Response Type: Select json
- Set sourcetype: Select Manual
- Source type: Type _json
These are required fields to configure Splunk to retrieve the data from Heimdal Security API requests. The other ones are optional and the Splunk help section can provide more details.
After you have completed all the fields you have to click on Next at the top of the page.
To check all the jobs created and manage them, go to Settings -> Data – Data inputs and click on REST.
To view the results, you have to click on the logo named Search & Reporting or go to the Search tab and type into the input field under source of the API request you want to check, like the following example: source="rest://API Test" where API Test is the REST API Input Name from above, more exactly the name of the job you created. Then press on the search button from the right to search for results.
In this new page you will have all the data extracted from our database as specified in the request and you can manage it as desired.