DefenseStorm ThreatMatch API

Using the DefenseStorm ThreatMatch API

DefenseStorm allows you to  programmatically script queries into ThreatMatch to access subscribed ThreatMatch threat feeds via a REST API.

To begin utilizing the ThreatMatch API, you must first copy or generate an API token through the DefenseStorm UI for authentication and authorization purposes. Once authenticated, the API can be used to submit an IP address, hostname, or signature to find out if it's active in a subscribed feed at any given time. The output describes the host, if there was a match, the feed(s) the host was found in, and a rating.

While one API Token may be sufficient for your network, we recommend creating an API Token for each system you have querying us. This allows for increased organization and data analysis. For example, you could create an API Token for your Firewall, custom thread analysis tool, etc. 

How to use the ThreatMatch API

  1. Login to the DefenseStorm GRID (https://console.defensestorm.com)
  2. Go to Settings > Input Token
  3. If you have an API Token already generated, copy it, skip to step 5.
  4. Within Settings > Input Token, select Get API Token
  5. Use API with the URL (https://api.defensestorm.com/threat/host/) and passing in a threat query parameter.

Example Query

curl -X GET  “https://api.defensestorm.com/threat/host/?threat=1.2.3.4” -H 'cookie: AK=omitted; AS=omitted'

Query Parameter: 1.2.3.4

Output:  "threat" the potential threat to be analyzed
                “threat_matched” determines if the threat was found in our collection of known threats. 

Possible values: true or false

Sources indicates what feed the host was found in from the subscribed feeds. 

Rating: Any user ratings of that threat indicator. 

Possible values: NA, harmless, low, medium, or high

Example Threat Found

{"threat": "1.2.3.4",
  "threat_matched": true,
  "sources": ["DHS AIS", "InfraGard"]
  "rating": "medium"}

Example Threat Not Found

{"threat": "1.2.3.4",
  "threat_matched": false,
  "sources": []
  "rating": “NA”}


Status Codes

200 - Request was good 
{"threat": String,
  "threat_matched": Boolean,
  "sources": String Array
  "rating": String}
401 - Not Authorized 
Unauthorized

403 - Incorrect Token Type 
Forbidden

429 - Throttled Response 
{"message": “Too many requests”}

500 - Server Error 
{"Status":500,
  "error":"Server Error",
  "Error_id":"error_id_value_here"}