API Guidelines

Downstream API clients

The Skurio Alerts and Results API can be used to create ‘downstream’ client applications which ingest data from the Skurio platform to carry out additional notifications, enrichments, alerting or automation.

Example use cases could be:

  • Bringing targeted threat intelligence from the Skurio DRP platform into a SIEM platform
  • Triggering automated Security playbooks in a SOAR platform
  • Raising a ticket in your security system
  • Integrating results into a dashboard or other reporting / notification platform.

‘Upstream’ client applications can also be used to create alert monitors in the Skurio platform from an existing data source.

Upstream API clients

Example upstream use cases could be:

  • Automatically creating email and domain monitors for all your customers, based on data in one of your other platforms
  • Synchronising an asset list of public IP addresses to be monitored

All API calls will require two API keys to authenticate. Both are provided in the headers.

Authorization : the app API key you obtain from api.skurio.com - this is 80 characters, with no hyphens X-Auth-Skurio-Key : the API token you obtain from [email protected] which authorises you against your Skurio DRP account. This is a 40 character UUID format, including hyphens

The basic structure of a downlink client should be:

  • Use the GET /alerts endpoint to retrieve a list of Alert Monitors within your account.
  • Optionally filter this list to select a subset of alertIDs to be synchronised. You could filter based on the folder name/ID, or the alert name/ID

For example, you may have some very noisy threat intelligence alerts which generate a large number of results - you may not want to bring those into your downstream client.

You may want to consider a simple UI allowing your users to select which Folders and/or Alerts are included or excluded in the connected data. You can optionally use the GET /folders resource to build a list of folders.

Polling for new results

You should poll the Skurio API for new results no more frequently than every 30 minutes.

You will need to iterate through all alertIds you wish to retrieve results for, and call the POST /alerts/{alertId}/results endpoint to get a filtered list of new results since the last polling time for that alert.

Using the type=detailed parameter will include all the key data parameters for up to 50 results in a single call, which is sufficient for the majority of applications. However, this method does not return the complete text content for the entire message due to size limitations - if this is needed, it must be retrieved for each individual result using the GET /alerts/{alertId}/results/{resultId} resource.

For reliability, your client should maintain an individual dateFrom timestamp for each alertID, rather than using a single dateFrom timestamp (“give me all results for this alert since I last asked you for all results from this alertID”). This will avoid any results being missed due to processing time as you iterate through the alerts.

Alternatively, you can store the dateTime of the latest resultID previously received from that alertId, and use that as a starting point for each call to that alert (“give me all results for this alert since the last result I succesfully retrieved from this alert”). This will provide increased resilience in the event that your API client is interrupted, and will avoid losing any data.

  1. Generate a list of alertIDs, using the GET /alerts and optionally the GET / folders endpoints to allow the user to select alerts or folders to be included or excluded.
  2. For each {alertId} in {alertIdList}, get new results using
    • POST /alerts/{alertId}/results?type=detailed?size=50?page=0
    • In the Body of the API call, set the dateFrom parameter to the dateTimeGMT when the last polling request was made to that Alert.
  3. If more than 50 results are returned, you will need to paginate through the results. The TotalCount parameter in each API result will indicate whether additional pages of results exist.
  4. For each {resultId} in the list of results, the POST /alerts/{alertId}/results API includes the following information :
  5. “Content” - truncated plaintext content snippet for each post which can be displayed to provide content
  6. “resultID” - unique ID for this result in this alert, which can be used for deduplication
  7. “sourceURL” - link to the original data from the dump site / dark web - use caution if exposing this link in your application
  8. “matches” - array of matching search terms from your original alert definition
  9. “appUrl” - link to this result in the Skurio platform
  10. “created” - dateTime when this result was delivered into the Skurio alert system
  11. “published” - if available, dateTime when the message was originally posted or detected. Note that for datadumps this is the more reliable timestamp to use