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:
-
Enrich an IP address, file hash, or any observable types.
-
Load threat intelligence into your Private Intel Store
-
Manage your casebooks and investigation snapshots
-
Automate response actions
-
Provide a link for users to click and Investigate an alert or observable
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:
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:
-
Threat Response - Enrich - Example scripts for the Threat Response Enrich API.
-
Threat Response - Response - Example scripts for the Threat Response Response API.
-
Threat Response - Authentication - Example scripts for authenticating to the Threat Response APIs.
-
Threat Response – Get Dispositions - Get the disposition for an observable.
Access sample SecureX scripts in Python here.
See Threat Response SDK for the SecureX API Python module.