Cortex XSOAR Integration Guide

Overview

The Cortex XSOAR integration allows your NINA workflows to connect with Palo Alto Networks Cortex XSOAR (Extended Security Orchestration, Automation, and Response) platform. This integration enables automated incident management, war room collaboration, and investigation workflow orchestration directly from your automation platform.

Status

The integration supports comprehensive Cortex XSOAR incident management operations:

Incident Management: Create, retrieve, search, update, and close incidents
Bulk Operations: Create, update, and close multiple incidents sequentially in single operations
War Room Collaboration: Retrieve war room entries, add notes, mark entries as notes or evidence, and search evidence
Evidence Management: Mark war room entries as evidence with descriptions, tags, and timestamps
Flexible Search: Filter incidents by date range, status, severity, type, and owner; search evidence by tags and criteria
Custom Fields: Support for instance-specific custom fields via free-form JSON

Advanced features:

Resource Locators: Dynamic incident selection with searchable dropdowns
Severity Levels: Standard severity classification (Informational, Low, Medium, High, Critical)
Investigation Creation: Automatically create investigations when incidents are created
Multi-Incident Closure: Close multiple incidents with individual closure reasons and notes

Credential Configuration

Cortex XSOAR integration uses API Key authentication.

Authentication Method

API Key

Field	Description	Example
Server URL	URL of your Cortex XSOAR instance	`https://your-xsoar-instance.com`
API Key	API key generated from XSOAR Settings	`ABCD1234...`

How to Get Your Cortex XSOAR API Key

Log in to Cortex XSOAR: Navigate to your XSOAR instance
Go to Settings: Click the Settings icon (⚙️) in the top right
Navigate to API Keys: Select Settings → Integrations → API Keys
Generate New API Key:
- Click Get Your Key or Generate Your Key
- Name: e.g., "NINA Integration"
- Role: Select appropriate role (typically Administrator or Analyst)
- Expiration: Choose appropriate duration or set to never expire
- Click Generate
Copy Credentials:
- Copy the API Key (long string shown once - you won't see it again!)
Test the Connection: Verify the key works by making a test API call

Important: Store the API key securely immediately after generation, as you cannot retrieve it later.

Creating a Cortex XSOAR Credential

Navigate to the Credentials section in NINA
Click Add New Credential
Fill in:
- Integration Service: "Cortex XSOAR"
- Auth Type: "API Key"
- Server URL: Your XSOAR instance URL (without trailing slash)
- API Key: Your generated API key
Click Save

Supported Resources and Operations

Incident

Operation	Name	Description
create	Create	Creates a new incident in XSOAR
bulkCreate	Bulk Create	Creates multiple incidents in XSOAR sequentially
get	Get	Fetch details of a single incident by ID
search	Search	Search and filter incidents by various criteria
update	Update	Update incident fields and status
bulkUpdate	Bulk Update	Updates multiple incidents in XSOAR sequentially
close	Close	Close one or multiple incidents
bulkClose	Bulk Close	Closes multiple incidents in XSOAR sequentially with individual close reasons

War Room

Operation	Name	Description
get	Get War Room	Fetch complete war room details including entries, metadata, and timeline
addEntry	Add Entry	Add a note/entry to incident war room and optionally mark as note or evidence
bulkAddEntry	Bulk Add Entry	Add multiple entries to incident war rooms sequentially
markAsNote	Mark As Note	Mark or unmark a war room entry as a note
markAsEvidence	Mark As Evidence	Mark a war room entry as evidence
searchEvidence	Search Evidence	Search and retrieve evidence entries for a specific incident

Examples

Create Incident

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "create",
  "name": "Suspicious Login Attempt Detected",
  "details": "Multiple failed login attempts detected from IP 192.168.1.100 targeting admin account",
  "type": "Phishing",
  "severity": 3,
  "owner": "[email protected]",
  "createInvestigation": true,
  "customFields": {
    "sourceip": "192.168.1.100",
    "targetuser": "admin",
    "attemptcount": 15
  }
}

Bulk Create Incidents

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "bulkCreate",
  "incidents": [
    {
      "name": "Malware Detection - Host A",
      "details": "Malicious file detected on workstation",
      "type": "Malware",
      "severity": 4,
      "owner": "[email protected]",
      "createInvestigation": true,
      "customFields": {
        "hostname": "workstation-a",
        "malwarehash": "abc123..."
      }
    },
    {
      "name": "Data Exfiltration Attempt",
      "details": "Large data transfer to unknown external IP",
      "type": "Data Leak",
      "severity": 4,
      "owner": "[email protected]",
      "createInvestigation": true
    }
  ]
}

Get Incident

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "get",
  "incidentId": {"mode": "id", "value": "123456"}
}

Search Incidents

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "search",
  "fromDate": "2025-09-03T00:00:00Z",
  "toDate": "2025-10-03T00:00:00Z",
  "status": "opened",
  "severity": 3,
  "type": "Phishing",
  "owner": "[email protected]",
  "limit": 50
}

Update Incident

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "update",
  "incidentId": {"mode": "id", "value": "123456"},
  "status": "under_investigation",
  "severity": 4,
  "owner": "[email protected]",
  "details": "Escalated: Additional IOCs discovered",
  "customFields": {
    "escalationreason": "Additional compromised hosts identified"
  }
}

Close Incident(s)

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "close",
  "incidentIds": "123456,123457,123458",
  "closeReason": "Resolved - False Positive",
  "closeNotes": "After investigation, determined to be benign activity from automated scanning tool"
}

Bulk Update Incidents

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "bulkUpdate",
  "incidents": [
    {
      "incidentId": "123",
      "status": "under_investigation",
      "severity": 4
    },
    {
      "incidentId": "124",
      "owner": "[email protected]",
      "details": "Updated details after further analysis"
    }
  ]
}

Bulk Close Incidents

{
  "integration_service": "cortex-xsoar",
  "resource": "incident",
  "operation": "bulkClose",
  "incidents": [
    {
      "incidentId": "123",
      "closeReason": "False Positive",
      "closeNotes": "Verified legitimate traffic"
    },
    {
      "incidentId": "124",
      "closeReason": "Resolved",
      "closeNotes": "Malware removed from endpoint"
    }
  ]
}

Get War Room

{
  "integration_service": "cortex-xsoar",
  "resource": "warRoom",
  "operation": "get",
  "incidentId": {"mode": "id", "value": "123456"},
  "pageSize": 100,
  "categories": ["notes", "commandAndResults"]
}

Add War Room Entry

{
  "integration_service": "cortex-xsoar",
  "resource": "warRoom",
  "operation": "addEntry",
  "incidentId": {"mode": "id", "value": "123456"},
  "entry": "## Investigation Update\n\nAnalyzed network logs. Confirmed malicious activity from IP 192.168.1.100.\n\n**Next Steps:**\n- Block IP at firewall\n- Reset compromised credentials",
  "markAsNote": true
}

Bulk Add War Room Entries

{
  "integration_service": "cortex-xsoar",
  "resource": "warRoom",
  "operation": "bulkAddEntry",
  "entries": [
    {
      "incidentId": "123456",
      "entry": "Initial analysis completed",
      "markAsNote": true
    },
    {
      "incidentId": "123457",
      "entry": "## IOC Found\n\nIP: 192.168.1.100",
      "markAsEvidence": true,
      "evidenceDescription": "Suspicious IP detected in logs",
      "evidenceTags": ["IOC", "network"]
    }
  ]
}

Mark War Room Entry As Note

{
  "integration_service": "cortex-xsoar",
  "resource": "warRoom",
  "operation": "markAsNote",
  "incidentId": {"mode": "id", "value": "123456"},
  "entryId": "10@123456",
  "markAsNote": true
}

Mark War Room Entry As Evidence

{
  "integration_service": "cortex-xsoar",
  "resource": "warRoom",
  "operation": "markAsEvidence",
  "incidentId": {"mode": "id", "value": "123456"},
  "entryId": "6@123456",
  "description": "Critical IOC identified - malicious domain contacted",
  "tags": ["IOC", "network", "critical"],
  "occurred": "2025-10-20T14:15:30+00:00"
}

Search Evidence

{
  "integration_service": "cortex-xsoar",
  "resource": "warRoom",
  "operation": "searchEvidence",
  "incidentId": {"mode": "id", "value": "123456"},
  "tags": ["IOC", "malware"],
  "limit": 20
}

Severity Levels

Cortex XSOAR uses numeric severity levels:

Value	Label	Description
0.5	Informational	Low-priority informational events
1	Low	Minor issues with minimal impact
2	Medium	Moderate security concerns requiring attention
3	High	Serious security incidents requiring prompt response
4	Critical	Critical incidents requiring immediate action

Custom Fields

Cortex XSOAR allows custom fields specific to your instance configuration. Use the customFields parameter with a JSON object containing your custom field definitions:

{
  "customFields": {
    "sourceip": "192.168.1.100",
    "targetuser": "admin",
    "alertsource": "SIEM",
    "businessunit": "Finance",
    "affectedsystems": ["server1", "server2"],
    "complianceimpact": true
  }
}

Note: Custom field names and requirements vary by XSOAR instance configuration. Consult your XSOAR administrator for available custom fields.

Best Practices

Use Descriptive Incident Names: Create clear, searchable incident names that describe the issue concisely.
Leverage Custom Fields: Utilize custom fields to capture instance-specific metadata for better incident tracking and reporting.
Bulk Operations: Use bulkCreate when creating multiple related incidents to improve efficiency.
War Room Documentation: Regularly add war room entries to document investigation progress and decisions.
Appropriate Severity Levels: Assign accurate severity levels to ensure proper incident prioritization.
Close with Context: Always provide meaningful closure reasons and detailed notes when closing incidents.
Search Optimization: Use date ranges and specific filters in search operations to reduce result sets and improve performance.
Owner Assignment: Assign incidents to specific users or teams for clear ownership and accountability.
Investigation Creation: Enable createInvestigation: true for incidents requiring detailed analysis workflows.
API Key Rotation: Regularly rotate API keys and update credentials in NINA for security.

Troubleshooting

Issue	Resolution
401 Unauthorized	Verify API Key is correct; check if key has expired
403 Forbidden	Ensure the API key has appropriate permissions/role in XSOAR
404 Not Found	Verify the Server URL is correct and accessible; check incident ID exists
Incident creation fails	Verify required fields (name, details, type, severity) are provided; check incident type exists in your XSOAR instance
Custom fields not saving	Ensure custom field names match your XSOAR configuration; verify JSON syntax is valid
War room entry fails	Check incident ID is valid and accessible; verify entry content is not empty
Search returns no results	Verify date format (ISO 8601); check filter parameters match existing incident values
Bulk operation partial failure	Review individual item errors in response; ensure all items have required fields
Evidence marking fails	Ensure description is provided and timestamp includes timezone (e.g., +00:00 or Z)

Response Structure

Incident Object

Typical incident response includes:

id: Unique incident identifier
name: Incident name
type: Incident type
severity: Severity level (0.5-4)
status: Current status
owner: Assigned user
created: Creation timestamp
modified: Last modification timestamp
details: Incident description
customFields: Instance-specific fields

War Room Entry Object

War room entries include:

id: Entry ID
contents: Entry content
created: Creation timestamp
user: User who created the entry
category: Entry category (e.g., notes, commandAndResults)
type: Entry type

Workflow Context

This integration is particularly useful for:

Automated Incident Creation: Automatically create XSOAR incidents from threat intelligence feeds, SIEM alerts, or security tool outputs
Incident Enrichment: Update incidents with additional context from external sources
Multi-Tool Orchestration: Coordinate XSOAR with other security tools in complex workflows
Reporting and Metrics: Search and analyze incident data for security reporting
Human-in-the-Loop: Add war room entries to document automated investigation steps and request analyst input

Security Considerations

Protect API Keys: Store API keys securely; never commit to version control or expose in logs.
Least Privilege: Create API keys with minimum required permissions for the integration.
Network Security: Ensure XSOAR instance is accessible only from trusted networks.
Audit Logging: Monitor API key usage through XSOAR audit logs.
Key Rotation: Implement regular API key rotation policy (e.g., every 90 days).
Sensitive Data: Be cautious when including sensitive information in incident details or custom fields.

Overview​

Status​

Credential Configuration​

Authentication Method​

API Key​

How to Get Your Cortex XSOAR API Key​

Creating a Cortex XSOAR Credential​

Supported Resources and Operations​

Incident​

War Room​

Examples​

Create Incident​

Bulk Create Incidents​

Get Incident​

Search Incidents​

Update Incident​

Close Incident(s)​

Bulk Update Incidents​

Bulk Close Incidents​

Get War Room​

Add War Room Entry​

Bulk Add War Room Entries​

Mark War Room Entry As Note​

Mark War Room Entry As Evidence​

Search Evidence​

Severity Levels​

Custom Fields​

Best Practices​

Troubleshooting​

Response Structure​

Incident Object​

War Room Entry Object​

Workflow Context​

Security Considerations​