Security Automation with Cisco XDR APIs

Introduction

Imagine a spear-phishing email lands in an employee's inbox at 2:47 AM. The user clicks a link, a drive-by compromise downloads a suspicious binary, and within minutes a rogue process begins lateral movement across the network. By the time a human analyst reviews the alert queue six hours later, the attacker has already exfiltrated sensitive data. This scenario plays out in organizations every day, and the only reliable defense is security automation — the ability to detect, investigate, and respond to threats at machine speed. At the center of that capability for Cisco environments sits the XDR API, a rich set of programmatic interfaces that let you tie together dozens of security products, extract indicators of compromise from raw text, enrich observables with threat intelligence, and trigger response actions across your entire security stack without ever logging into a GUI.

In this article, we will take a deep technical tour of Cisco XDR and its APIs. We will examine the integration architecture that allows XDR to communicate with both Cisco and third-party products, walk through every major API category — Inspect, Enrich, Respond, Private Intelligence, Automate, and Proxy — and explore real-world automation outcomes such as investigation, response, and combined investigate-and-respond workflows. Whether you are a network security engineer looking to streamline your SOC operations or a developer building custom integrations, this guide will give you the knowledge you need to start developing with Cisco XDR.

What Is Cisco XDR and Why Does It Matter for Security Automation?

Cisco XDR is an extended detection and response platform that aggregates telemetry from a wide range of sources across an organization's infrastructure. These telemetry sources span endpoints, firewalls, cloud analytics, email security, malware analytics, identity services, and more. The platform ingests data from on-premises networks, remote workers, public cloud environments, and data centers to provide a unified view of threats.

Telemetry Sources

XDR collects data from multiple network layers and security products:

Telemetry Source	Data Type	Location
Cisco Firewall	Flow logs	Campus/Branch, Data Center
Meraki and Catalyst	Flow logs	Campus/Branch
Cisco Telemetry Broker	Syslog, NetFlow/IPFIX, Mirror/SPAN	On-premises
Endpoint (NVM)	Endpoint data	Remote Workers, Campus
ISE	Identity and posture data	On-premises
Third-party integrations	Varies (e.g., Amazon GuardDuty, Microsoft Defender for Endpoint)	Public Cloud, Hybrid

The platform correlates these diverse data streams to detect advanced threats like ransomware that span multiple attack stages. A typical attack chain might follow a sequence like this:

Spear phishing (T1566): A well-tailored email causes a user to click a malicious link.
Drive-by compromise (T1189): The link redirects to a questionable website that delivers a payload.
Process injection (T1055): A strange process is created locally on the user's device.
Account discovery (T1087): The injected process discovers domain accounts.
Lateral tool transfer (T1570): The attacker moves tools to other machines.
Network connections discovery (T1048): The process connects to external command-and-control infrastructure or directly to data stores.

Without XDR, each step in this chain might be visible to a different vendor's product — endpoint detection sees the process injection, the firewall sees the suspicious outbound connection, email security flags the phishing attempt — but no single system connects the dots. Cisco XDR bridges those gaps, and its XDR API layer makes it possible to automate every stage of the detection-investigation-response lifecycle programmatically.

How Do Cisco XDR Integrations Work?

Integrations are the foundation of Cisco XDR's power. They allow XDR to communicate with other products, both Cisco and third-party, and represent data using the Cisco Threat Intelligence Model (CTIM). XDR has over 90 integrations built in, covering a broad ecosystem of security tools.

Ways to Set Up Integrations

There are three primary ways to add integrations to XDR:

Configure in XDR — Use the built-in configuration interface to enable one of the 90+ available integrations.
Browse Cisco's GitHub — Find integration code in the CiscoSecurity GitHub repository, though some of the code there may be outdated.
Write your own — Develop custom integrations using the Relay API, though not all XDR capabilities are supported in custom integrations.

Pro Tip: When evaluating whether to write a custom integration or use an existing one, keep in mind that certain capabilities — specifically Devices, Users, and Telemetry — cannot be added to a custom integration. These are reserved for built-in integrations only.

Integration Capabilities

Each integration can expose one or more of the following capabilities to XDR:

Capability	Description
Dashboard	Tiles with data that can be displayed on your XDR dashboards
Deliberate	Provides verdicts with a disposition (clean, suspicious, malicious, unknown)
Observe (Observables)	Provides a summary of sightings for an observable
Observe (Targets)	Provides a summary of data for targets related to an observable
Refer	Provides links to other resources or tools in the pivot menu
Respond	Allows users to take actions in the integrated product from the pivot menu
Devices	Information about assets and their management and/or security posture
Users	Information about users from an identity manager
Telemetry	Raw data used to generate detections and correlations

The last three capabilities in the table — Devices, Users, and Telemetry — are the ones that you cannot add to a custom integration. These remain exclusive to Cisco-built integration modules.

What Is a Pivot Menu?

The pivot menu is a central interaction point in the XDR interface. When an analyst is investigating an observable — such as an IP address, domain, file hash, or email address — the pivot menu appears to provide contextual actions. It surfaces two key types of actions from integrations:

Refer actions: Links to external resources or tools that can provide more information about the observable.
Respond actions: Direct actions that can be taken against the observable through an integrated product, such as blocking a domain on a firewall or isolating an endpoint.

The pivot menu is what transforms XDR from a passive visibility tool into an active response platform, and the APIs we will discuss later can trigger the same actions programmatically.

Understanding the XDR API Integration Architecture

The integration architecture of Cisco XDR follows a modular design that sits between the XDR platform and the various products it connects to.

Architecture Components

The architecture consists of several layers:

Cisco XDR — The core platform that provides enrichment, investigation, response playbooks, and automation.
Integration Module — A middleware component that translates between XDR and the product's native API.
Relay API — The HTTP-based API that handles the translation of data between Cisco XDR and other products.
Product API — The native API of the integrated product (e.g., Microsoft Graph API).
Proxy — An optional layer that forwards HTTP requests to integrated products, abstracting connection information such as host and credentials.

The Relay API is particularly important for developers building custom integrations. It is an HTTP-based API with very few requirements, making it relatively straightforward to implement. Here is a simplified view of the data flow:

Cisco XDR sends a request (e.g., /enrich) with JSON formatted according to CTIM.
The Relay API translates this into the product's native API format (e.g., a Microsoft Graph /runHuntingQuery call).
The product returns its native JSON response.
The Relay API translates the response back into CTIM-formatted JSON for XDR.

This architecture supports all the major Cisco products — Endpoint, Cloud Analytics, Firewall, Email, Malware Analytics — as well as third-party tools like Microsoft Defender for Endpoint.

What Are the Cisco XDR API Categories?

Cisco XDR exposes multiple different APIs, each providing unique functionality. These APIs either provide direct platform features or serve as a conduit to integrations and their data. All XDR APIs require an API key generated in XDR with the appropriate scopes for the APIs you want to use.

Complete XDR API Map

API Category	Purpose	Key Functions
Automate	Workflow management	Trigger workflows, get workflow run info, manage targets and account keys
Inspect	Content analysis	Extract observables from arbitrary text
Enrich	Threat intelligence	Observe, Deliberate, Refer (uses CTIM)
Respond	Response actions	Execute actions through integrated products
Private Intelligence	Intelligence management	Feeds, Incidents, Indicators, Judgements, Sightings, Verdicts
Proxy	Request forwarding	Forward HTTP requests to integrated products

Let us examine each of these in detail.

How Does the XDR API Inspect Capability Work?

The Inspect API takes an arbitrary block of text and extracts observables from it. This is one of the simplest yet most powerful capabilities in the XDR API toolkit.

Use Cases for Inspect

The Inspect API provides a simple and easy way to extract things to investigate from content such as:

Emails — Paste a suspicious email body and extract all URLs, IP addresses, and file hashes.
Blog posts — Extract indicators of compromise from threat intelligence blog posts.
Threat intel websites — Pull observables from published threat advisories and research reports.
Any arbitrary text — Any content that might contain IP addresses, domains, hashes, or other observable types.

How Inspect Fits into Automation

In an automated workflow, the Inspect API typically serves as the first step. You feed it raw threat intelligence content, and it returns structured observables that can then be passed to the Enrich or Respond APIs for further action. This eliminates the tedious manual work of reading through threat reports and manually copying indicators into investigation tools.

# Example workflow using Inspect
# Step 1: POST to /inspect with raw text
# Step 2: Receive structured observables (IPs, domains, hashes)
# Step 3: Pass observables to /enrich for disposition
# Step 4: Act on malicious observables via /respond

Pro Tip: The Inspect API is particularly valuable when combined with scheduled automation workflows. You can set up a workflow that periodically fetches content from threat intelligence feeds, runs it through Inspect to extract observables, and then automatically enriches and investigates them — all without human intervention.

How Does Enrichment Work with the XDR API?

The Enrich API uses the Cisco Threat Intelligence Model (CTIM) and is the heart of XDR's investigative power. Enrichment is the process of consulting all integrations to find out what any of them know about one or more observables.

Enrichment Sub-APIs

The Enrich API encompasses three sub-capabilities:

Observe — Ask each XDR integration whether a given observable was seen in the environment. This queries across all configured integrations simultaneously.
Deliberate — Get dispositions for observables. Each integration that supports deliberation returns one of four possible verdicts:
- Clean — The observable is known to be safe.
- Unknown — There is not enough information to make a determination.
- Suspicious — The observable shows characteristics that warrant further investigation.
- Malicious — The observable is confirmed as a threat.
Refer — Collect links to external resources and tools from all integrations that support the Refer capability.

The Enrichment Flow

When enrichment is triggered — whether by an analyst in the UI or programmatically via the XDR API — the following process occurs:

XDR receives one or more observables (IP addresses, domains, file hashes, etc.).
The platform fans out the request to all configured integrations simultaneously.
Each integration checks its own data sources: IP reputation, domain reputation, file analysis, email reputation, and more.
Results are collected and normalized into CTIM format.
The aggregated intelligence is returned to the caller.

This fan-out architecture means that a single API call can query intelligence sources, IP reputation engines, domain reputation services, file analysis sandboxes, email reputation databases, and any other integrated products — all at once.

Enrichment Source	What It Checks
Intelligence	Known threat indicators and campaigns
IP Reputation	Historical behavior and threat associations of IP addresses
Domain Reputation	Domain age, hosting patterns, known malicious associations
File Analysis	Sandbox results, static analysis, behavioral indicators
Email Reputation	Sender reputation, phishing indicators, spam classification

The enrichment capability extends across all integrated Cisco products (Endpoint, Cloud Analytics, Firewall, Email, Malware Analytics) and third-party tools like Microsoft Defender for Endpoint.

How Does the XDR API Respond Capability Enable Automated Response?

The Respond API exposes response actions made available by integrated products. It also includes some automation workflows. Actions provided through the Respond API are specific to one or more observable types, meaning that the available response actions depend on whether you are acting on an IP address, a domain, a file hash, or another type of observable.

What Can You Do with Respond?

Through the Respond API, you can act against an observable through any XDR integration module that supports the Respond capability. This includes:

Blocking malicious domains or IP addresses on firewalls.
Isolating compromised endpoints.
Quarantining suspicious emails.
Triggering automation workflows that coordinate multiple response actions across products.

The power of the Respond API lies in its ability to combine multiple products in a single action. Instead of logging into your firewall to block an IP, then logging into your endpoint solution to isolate a host, then logging into your email gateway to quarantine related messages, you can orchestrate all of these actions through a single API-driven workflow.

Pro Tip: When building automated response workflows, always consider implementing a human approval step for high-impact actions like endpoint isolation. The XDR automation engine supports approval tasks as a workflow trigger, giving you the safety net of human oversight while still automating the heavy lifting.

What Is the Private Intelligence API in Cisco XDR?

The Private Intelligence API uses the Cisco Threat Intelligence Model (CTIM) and provides a way to manage your organization's own threat intelligence within XDR. This is where you store and manage intelligence data that is specific to your environment.

Private Intelligence Data Types

The Private Intelligence API provides endpoints for managing the following CTIM entities:

Entity	Description
Feeds	Collections of threat intelligence data from specific sources
Incidents	Security events that require investigation and response
Indicators	Patterns or signatures that identify potential threats
Judgements	Dispositions assigned to specific observables
Sightings	Records of when and where an observable was seen
Verdicts	Final determinations about the nature of an observable

Why Private Intelligence Matters

One of the most valuable use cases for the Private Intelligence API is pushing intelligence from custom sources into your private intelligence store so it can be used by XDR during investigations. For example, if your threat research team discovers indicators of compromise specific to your industry or organization, you can programmatically push those indicators into XDR so they are automatically considered during every enrichment operation.

This capability also enables incident synchronization between XDR and other ticketing platforms. If your organization uses a separate ITSM or ticketing system, you can use the Private Intelligence API to keep incidents synchronized bidirectionally, ensuring that your SOC analysts have a consistent view regardless of which tool they are working in.

How Does the XDR API Proxy Work?

The Proxy API forwards HTTP requests to integrated products that support the proxy capability. It abstracts connection information such as the host and credentials, which are automatically added at runtime.

Key Benefits of the Proxy API

The Proxy API provides several architectural advantages:

Credential abstraction — Your automation code does not need to store or manage credentials for each integrated product. XDR handles authentication automatically.
Simplified connectivity — You send requests to the XDR proxy endpoint, and XDR forwards them to the appropriate product. This eliminates the need for direct network connectivity between your automation platform and every security product.
Consistent interface — Regardless of the underlying product's API format, you interact with a single, consistent proxy endpoint.

The Proxy API is used by multiple XDR features internally and can also be used directly via the API. This makes it an excellent choice when you need to interact with a specific integrated product's capabilities but want to leverage XDR's existing connection infrastructure rather than setting up separate API integrations.

What Are the XDR API Automation Capabilities?

The Automate API provides programmatic access to XDR's workflow automation engine. It covers several key areas of functionality.

Automate API Functions

Triggering a workflow — Start any XDR automation workflow programmatically from external systems.
Getting information about workflows and workflow runs — Query the status of running or completed workflows.
Creating and managing targets — Define the endpoints and systems that workflows interact with.
Creating and managing account keys — Manage the credentials that workflows use to authenticate with targets.

Workflow Triggers

XDR automation workflows can be triggered by a variety of events and mechanisms:

Trigger Type	Description
API request	Programmatic trigger from external systems
Approval task	Human approval step in a workflow chain
Automation rules	Rule-based triggers within XDR
Email	Incoming email triggers
Incident	Creation or update of an XDR incident
Pivot menu	Manual trigger from the XDR investigation UI
Response playbook	Trigger as part of a structured response plan
"Run" button	Manual execution from the workflow editor
Schedule	Time-based recurring execution
Webhook	HTTP callback from external systems

Workflow Architecture

Each workflow follows a structured flow:

Input Variables — Data passed into the workflow at trigger time.
Triggers — The event or mechanism that starts the workflow.
Activities — Individual steps in the workflow, which can include atomic actions (single operations on a target).
Targets — The systems and APIs that the workflow interacts with (mailbox, API, terminal, etc.).
Credentials — Authentication data provided by account keys.
Output Variables — Data produced by the workflow for consumption by other systems or subsequent workflows.

Pro Tip: The API request trigger is particularly powerful for ITSM integration. You can execute an XDR automation workflow directly from your ITSM platform, enabling your service desk to trigger security investigations and responses without leaving their familiar tools.

Automation Outcomes: Investigation, Response, and Beyond

The true value of Cisco XDR's API and automation capabilities emerges when you consider the outcomes they enable. These outcomes fall into four primary categories.

Investigate

Automation reduces the time to investigate by automating data collection and incident generation. The investigation workflow typically follows this pattern:

Fetch IOCs — Indicators of compromise can be gathered from any number of sources including threat research websites, blogs, RSS feeds, and other intelligence sources.
Investigate — Once you have IOCs, you use XDR via workflows or APIs to investigate using integrated products. The Enrich API fans out queries to every configured integration.
Notify — If sightings are found in the environment, analysts are notified that the threat has been seen and remediation is required.

Simplify

Automation eliminates repetitive tasks that waste valuable analyst time. SOC analysts often spend significant portions of their day on routine, predictable tasks: checking reputation scores, looking up indicators, cross-referencing multiple tools. By automating these tasks, analysts can focus on the complex, judgment-intensive work that actually requires human expertise.

Respond

Automated or one-click responses combine multiple products in one action. The response workflow follows this process:

Identify — Determine which observables to act against and which action to take.
Act — Take the specified action, leveraging products integrated with XDR as control points.

Response actions can span multiple products simultaneously, turning what would be a multi-step, multi-tool manual process into a single automated action.

Integrate

Automation brings products and services together in new ways to address emerging threats. This is where the full power of the XDR API ecosystem comes together — using the APIs to create novel combinations of detection, investigation, and response that were not possible when each product operated in isolation.

Combined Investigate and Respond

The most powerful automation workflows combine investigation and response into a single automated pipeline:

Fetch IOCs — Gather indicators from threat intelligence sources.
Investigate — Use XDR to query all integrated products for sightings of those indicators.
Respond — If threats are confirmed, automatically take response actions through integrated products serving as control points.

This end-to-end automation dramatically reduces the mean time to respond (MTTR) and ensures that threats are addressed consistently, regardless of when they are detected or which analyst is on duty.

Practical Use Cases for XDR API Development

Based on the capabilities we have covered, here are the key practical scenarios where XDR API development delivers immediate value:

1. ITSM Integration

Execute an XDR automation workflow from your ITSM platform. When a security incident is created in your ticketing system, the ITSM platform can call the Automate API to trigger an investigation workflow in XDR, automatically enriching the relevant indicators and returning results to the ticket.

2. Cross-Platform Response Orchestration

Execute response actions through integrated products. A single API call to the Respond endpoint can trigger blocking actions across firewalls, endpoint protection, email gateways, and cloud security controls simultaneously.

3. Custom Intelligence Ingestion

Push intelligence from custom sources into your private intelligence store so it can be used by XDR during investigations. This is ideal for organizations that maintain proprietary threat feeds, industry-specific ISACs, or internal threat research teams.

4. Incident Synchronization

Synchronize incidents between XDR and other ticketing platforms. The Private Intelligence API's incident management endpoints enable bidirectional sync, ensuring consistency across your operational tools.

5. Unified Dashboard

Fetch dashboard tile data for inclusion in your "single pane of glass." If your organization has a central operations dashboard, you can pull XDR dashboard tile data via the API and embed it alongside data from other operational systems.

6. Automated Threat Intelligence Processing

Combine the Inspect API with the Enrich and Respond APIs to build a fully automated threat intelligence processing pipeline. Feed in raw reports, extract observables, check them against all integrated intelligence sources, and take action on confirmed threats — all without human intervention.

Developer Resources for Cisco XDR API Integration

For developers looking to build integrations and automation with Cisco XDR, there are several key resources available.

GitHub Repository

The CiscoSecurity GitHub repository (github.com/CiscoSecurity/) contains integration code, examples, and reference implementations. Be aware that some of the integration code in GitHub may be outdated, so always verify against the current API documentation.

Module Maker

The Module Maker tool, available at ciscosecurity.github.io, helps developers scaffold new integration modules more quickly. This tool generates the boilerplate code needed for a Relay API integration, letting you focus on the product-specific translation logic.

API Key Management

All XDR APIs require an API key generated within the XDR platform. When creating your API key, you need to select the appropriate scopes based on which APIs you plan to use. Follow the principle of least privilege — only grant the scopes that your integration or automation actually needs.

Working with CTIM

The Cisco Threat Intelligence Model (CTIM) is the data format that ties the entire XDR ecosystem together. Both the Enrich API and the Private Intelligence API use CTIM to represent threat intelligence data. Understanding CTIM's entity types — judgements, sightings, indicators, verdicts, feeds, and incidents — is essential for any developer working with XDR APIs.

Pro Tip: Start your XDR API development journey with the Inspect API. It has the simplest interface, requires minimal setup, and gives you immediate, visible results. Once you are comfortable with authentication and the basic request/response pattern, move on to the Enrich API to start querying your integrated products.

Frequently Asked Questions

What API key scopes do I need to use Cisco XDR APIs?

Cisco XDR APIs require an API key generated in the XDR platform with the appropriate scopes for the APIs you want to use. Each API category (Automate, Inspect, Enrich, Respond, Private Intelligence, Proxy) has its own scope. You should follow the principle of least privilege and only enable the scopes your integration or automation requires. The API key is generated directly within the XDR administration interface.

Can I build custom integrations for Cisco XDR?

Yes, you can write your own integrations using the Relay API, which is an HTTP-based API with very few requirements. However, there are limitations: not all XDR capabilities are supported in custom integrations. Specifically, the Devices, Users, and Telemetry capabilities cannot be added to a custom integration — these are reserved for Cisco-built integrations only. Custom integrations can support Dashboard, Deliberate, Observe (Observables and Targets), Refer, and Respond capabilities.

What is the difference between the Enrich API and the Private Intelligence API?

The Enrich API queries all configured integrations to gather intelligence about observables — it fans out requests to IP reputation, domain reputation, file analysis, email reputation, and other intelligence sources across your integrated products. The Private Intelligence API, on the other hand, manages your organization's own threat intelligence store within XDR. It provides endpoints for managing feeds, incidents, indicators, judgements, sightings, and verdicts. You use the Private Intelligence API to push custom intelligence into XDR so it can be leveraged during enrichment operations.

How can I trigger an XDR automation workflow from an external system?

XDR automation workflows support multiple trigger types including API request, webhook, email, schedule, incident, automation rules, approval task, pivot menu, response playbook, and manual "Run" button. To trigger a workflow from an external system, use either the API request trigger (via the Automate API) or a webhook trigger. The API request trigger is the most common choice for ITSM integrations, where a service desk ticket creation event calls the XDR Automate API to start an investigation or response workflow.

What observable types does XDR support?

XDR works with a wide range of observable types across its APIs. These include IP addresses, domain names, file hashes (MD5, SHA-1, SHA-256), email addresses, URLs, and other indicator types. The Inspect API can extract these observables from arbitrary text, the Enrich API can query integrations for intelligence about them, and the Respond API can take actions against them. The available response actions depend on the observable type — for example, domain blocking actions are available for domain observables but not for file hash observables.

What is the Cisco Threat Intelligence Model (CTIM)?

CTIM is the standardized data model that Cisco XDR uses to represent threat intelligence data across all integrations. It defines entity types such as judgements (dispositions assigned to observables), sightings (records of when observables were seen), indicators (patterns identifying threats), verdicts (final determinations), feeds (intelligence data collections), and incidents (security events requiring response). Both the Enrich API and the Private Intelligence API use CTIM, and the Relay API translates between CTIM and product-native data formats. Understanding CTIM is essential for anyone developing custom integrations or working with the Private Intelligence API.

Conclusion

Cisco XDR and its comprehensive API ecosystem represent a fundamental shift in how security operations can be conducted. Rather than treating each security product as an isolated tool requiring manual interaction, XDR APIs enable you to build automated pipelines that detect, investigate, and respond to threats across your entire infrastructure in seconds rather than hours.

The key takeaways from this deep dive are:

XDR integrations provide the foundation, with over 90 built-in integrations and the ability to create custom ones via the Relay API, though custom integrations cannot support Devices, Users, or Telemetry capabilities.
The Inspect API extracts observables from arbitrary text, making it the ideal starting point for automated threat intelligence processing.
The Enrich API fans out queries to all integrated products simultaneously, providing dispositions (clean, unknown, suspicious, malicious) and sightings data.
The Respond API enables cross-product response actions from a single API call, with actions specific to observable types.
The Private Intelligence API lets you manage your own threat intelligence store, including feeds, incidents, indicators, judgements, sightings, and verdicts.
The Automate API provides programmatic access to workflows with support for ten different trigger types, from API requests and webhooks to schedules and incident creation.
The Proxy API abstracts connection details and credentials, simplifying how your automation code interacts with integrated products.

Security automation is no longer optional for organizations facing modern threats. The speed and sophistication of attacks like the multi-stage ransomware scenario we opened with demand automated detection and response. Cisco XDR APIs give you the building blocks to make that a reality.

To deepen your skills in security automation and API-driven network operations, explore the automation and security courses available on NHPREP. Hands-on practice with these technologies is the fastest path from understanding the concepts to deploying production-ready automation in your environment.