SecureX API Integration

Cisco SecureX is built upon a collection of APIs which can be used to integrate your Cisco and third-party security products, automate the incident response process, and manage threat intelligence and security context data in a single location. With SecureX, you can:

For more information using the SecureX APIs, see Cisco DevNet.

See SecureX Developer Documentation for information on the SecureX API changes.

If you experience any API errors, you can open a case with Cisco Support. For details, see Contact Support. Visit the Cisco SecureX Developer Community for additional community-based developer support.

API Clients

Users can generate API Client credentials, which can be used to access the SecureX APIs programmatically. For information on configuring API clients, see API Clients.

Using API Client Credentials to Get Access Token

You cannot access the API directly using the Client ID and Client Password because SecureX requires the use of an access token. You can request a token from the OAuth2 token API.

Example using Bash with a curl command:

            client_id="[clientid]"
client_password="[client-password]"
curl -X POST \
     -u "$client_id:$client_password" \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --header 'Accept: application/json' \
     -d 'grant_type=client_credentials' \
     'https://visibility.amp.cisco.com/iroh/oauth2/token'
        

Response:

            {
  "access_token":"eyJhbGciO...",
  "token_type":"bearer",
  "expires_in":600,
  "scope":"enrich:read casebook inspect:read"
}
        
  • The access_token value is what you pass in the authorization. header.

  • The token_type value indicates it should be presented as a bearer token.

  • The expires_in indicates how many seconds this token is valid. You will need to request a new one after it expires, using the same API call.

  • The scope value contains a list of scopes that were granted to this token. It may not include all of the scopes for which the client was authorized if your user identity has lost privileges since the API Client was created.

Once you have an access token, you can call the APIs you granted the API Client permissions to access.

Using OAuth Code Client Credentials to Get Access Token

For instructions about how to retrieve the access token from an OAuth Code Client, see the Integration Developer Documentation.

SecureX APIs

Authentication

All SecureX APIs use an access token for authentication. This is an opaque value which is passed in as an HTTP header: Authorization: Bearer <Access Token>.

Example request using cUrl:

            ACCESS_TOKEN="eyJhbGciO..."
curl -X POST \
     --header "Authorization: Bearer $ACCESS_TOKEN" \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json' \
     -d '{"content":"cisco.com"}' \
     'https://visibility.amp.cisco.com/iroh/iroh-inspect/inspect'
[{"value":"cisco.com","type":"domain"}]
        

Access tokens are short-lived, and can be requested or refreshed from the OAuth2 token API.

Rate Limits

In order to protect our infrastructure, we apply rate limits to API requests which apply to all API Clients within a single organization. The current limit is 8000 requests per hour. This is calculated as a rolling 60 minute window, not coordinated with clock time. This also means that other users in your organization are sharing the same pool of requests that you are using — one runaway script or integration can impact other users in your organization.

When you make a request, the X-Ratelimit-Org-Limit header will tell you the rate limit being applied. This does not change as you make requests, but is the fixed value per hour for all requests from your organization.

Example Successful Response with rate limit header:

            HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Date: Wed, 31 Oct 2018 14:05:30 GMT
Server: Jetty(9.4.z-SNAPSHOT)
Strict-Transport-Security: max-age=31536000; includeSubdomains
Vary: Accept-Encoding, User-Agent
X-Ctim-Version: 1.0.6
X-Iroh-Config: b9b3477528d9616ed85221f2827bf1da443e8f00
X-Iroh-Version: 70323eb3b72da558e7f056e418533402f65d335a
X-Ratelimit-Org-Limit: 8000
        

If you go over your rate limit, you will get a 429 Too Many Requests response code. The response will also have a Retry-After header, which tells you how many seconds you need to wait before you can make another request.

Example Rate Limited:

            HTTP/1.1 429 Too Many Requests
Content-Length: 30
Content-Type: application/json
Date: Wed, 31 Oct 2018 14:05:30 GMT
Retry-After: 3557
Server: Jetty(9.4.z-SNAPSHOT)
Strict-Transport-Security: max-age=31536000; includeSubdomains
X-Ctim-Version: 1.0.6
X-Iroh-Config: b9b3477528d9616ed85221f2827bf1da443e8f00
X-Iroh-Version: 70323eb3b72da558e7f056e418533402f65d335a
        

API Documentation

The following list includes the available APIs and their associated scopes:

inspect

enrich

response

oauth

global-intel

private-intel

Note: Clients cannot have the full oauth and full global-intel scope. You should use oauth:read and global-intel:read scopes instead, which grant access to read-only routes.

Linking into an Investigation

You can perform an investigation by passing a search string to the q parameter that comes after the /investigate part of the URL. Multiple search items should be separated with a space. Be sure to properly URL encode the argument.

  • https://visibility.amp.cisco.com/investigate?q=domain.com
  • https://visibility.amp.cisco.com/investigate?q=internetbadguys.com%20A6732417baa49b873d72747c0ef46f8d1

Find Sample Code and Scripts

The CiscoSecurity repository on GitHub has several scripts to get you started.

Some examples:

Access sample SecureX scripts in Python here.

See Threat Response SDK for the SecureX API Python module.