Enrich API Docs

The Enrich API allows developers to gather additional threat intel, correlated events, and security context for a set of observables or a single observable. This is an important step in automating an incident investigation or threat hunt. The Enrich API takes observables as input in the following JSON format (same format as the Inspect API output):

[
  {
    "type": "domain",
    "value": "ilo.brenz.pl"
  },
  {
    "type": "email",
    "value": "no-reply@internetbadguys.com"
  },
  {
    "type": "sha256",
    "value": "8fda14f91e27afec5c1b1f71d708775c9b6e2af31e8331bbf26751bc0583dc7e"
  }
]

Use Cases

Deliberate APIs - Quickly get Verdicts from all your integrations. Use these APIs at the start of any investigation to quickly determine if something is bad in your modules.
Observe APIs - Get in depth investigation data about a threat. Use these APIs at the start of any investigation to get the full picture and know if something has been seen in your environment.
Refer APIs - Get relevant reference links and quickly pivot and investigate a specific product interface.

How to use the API Docs

Use the interactive documentation to explore the Enrich API endpoints. Each request will have a complete description of all the required parameters and it also allow you to instantly try it out in the online console. Code templates are also provided for you to quickly build scripts.

In the interactive explorer, the Client ID and Client Secret has been pre-filled and will allow you to make read-only API requests. These credentials will allow you to get an Access Token, which will be stored for subsequent API requests and regenerated when it expires.

Note: The interactive documentation uses read-only credentials and the try it out feature will only work with GET and selected POSTrequests.

To try other Enrich API requests, go to https://visibility.amp.cisco.com/iroh/iroh-enrich/index.html

Generate an Access Token

In the interactive API explorer, the Access Token is automatically generated using the pre-filled Client ID and Client Secret so you do not need to generate it yourself.

If you want to understand how the Access Token is generated from the Client ID and Client Secret credentials, take a look at the Authentication page.

For detailed instructions on how to use the interactive API documentation (or your own Python script), see the Getting Started page.

Download the Enrich OpenAPI Specification

Download the Enrich OpenAPI specification (OAS) file here.

Sample Code

Below is an example of how to use the Enrich API, without the Python SDK. Please check the Getting Started for instructions using the SDK.

import json
import requests

# create headers for API request (See the OAuth2 overview page for sample code to generate an access token)
access_token = 'eyJhbGciO....bPito5n5Q' # truncated example, generate JWT token separately
bearer_token = 'Bearer ' + access_token

# retrieve the related Threat Context
url = 'https://visibility.amp.cisco.com/iroh/iroh-enrich/observe/observables'

headers = {
            'Authorization': bearer_token,
            'Content-Type':'application/json',
            'Accept':'application/json'
}

payload = [{
            'type': 'domain',
            'value': 'cisco.com'
}]

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.text)

if response.status_code == 200:
    # convert the response to a dict object
    response_json = json.loads(response.text)

    # get the list of related Threat Context
    threat_contexts = response_json['data']

    # iterate through the list of Threat Contexts
    for threat_context in threat_contexts:
        # get the values from a Threat Context (remainder values are accessed in the same way)
        module = threat_context['module']
        data = threat_context['data']
        verdicts = data['verdicts']
        judgements = data['judgements']

Download OpenAPI Document