Findings Query API Docs

The Findings Query API allows developers to programmatically search, filter, and retrieve detection findings stored in the Cisco XDR data warehouse. This API provides access to a wealth of security data, enabling automated analysis and integration with other security tools.

Use Cases

Automated Threat Detection: schedule and automate queries to identify new or unresolved findings, integrating with SIEMs or alerting systems.
Compliance Auditing: generate reports of detection findings over specific time frames to support compliance requirements and internal audits.

How to use the API Docs

Use the interactive documentation to explore the Findings Query API endpoints. Each request will have a complete description of all the required parameters and it also allows 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 are pre-filled, allowing you to make read-only API requests. These credentials allow you to obtain an Access Token, which is stored for subsequent requests and automatically regenerated when it expires.

Note: The interactive documentation uses read-only credentials, and the try it out feature only works with GET and selected POST requests. To try other Findings Query API requests, go to https://queryservice.us.security.cisco.com/swagger-ui#/.

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 `Findings Query` OpenAPI Specification

Download the Findings Query OpenAPI specification (OAS) file here.

Sample Code

Below is an example of how to use the Findings Query API.

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
detection_id = 'detection-xxxxxxx-88fc-46a8-9d62-b58dbc9a47b6'

# search incidents in the private-intel
url = f'https://queryservice.us.security.cisco.com/api/v1/query/findings?finding_uid={detection_id}&format=ocsf1.4'

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

response = requests.get(url, headers=headers)
print(response.text)

Version: 1.0.0