Palo Alto Cortex XDR Integration Guide

Overview

The Palo Alto Cortex XDR integration connects your NINA workflows to the Cortex XDR REST API, enabling comprehensive endpoint detection and response operations. This integration lets you manage alerts, investigate incidents, control endpoints, run XQL queries, manage threat intelligence indicators, query assets and vulnerabilities, execute scripts, manage BIOC and correlation rules, and administer users and API keys — all directly from your workflows.

Palo Alto Cortex XDR is an extended detection and response platform that unifies network, endpoint, and cloud data to detect and stop sophisticated attacks. It provides automated investigation, behavioral analytics, and flexible response actions across managed endpoints.

Status

We currently support 22 resources across the Cortex XDR API surface:

Alert Management: Retrieve security alerts with flexible filtering and sorting
Case Management: Search cases, retrieve case artifacts, and update case details
Incident Management: Retrieve incidents and bulk incident extra data
Endpoint Management: Query, isolate, unisolate, scan, tag, triage, and delete managed endpoints
Endpoint Actions: Track action status, list triage presets, and check API health
File Operations: Quarantine, restore, retrieve, blocklist, and allowlist files by hash
Legacy Scripts: List, retrieve, and execute pre-built XDR scripts and code snippets
Automation Scripts: Upload, retrieve, and delete custom automation scripts
Automation Playbooks: Upload, retrieve, and delete automation playbooks
XQL Queries: Start and retrieve generic and dataset-specific XQL queries; manage the XQL library
BIOC Rules: List, upsert, and delete Behavioral Indicator of Compromise rules
Correlation Rules: List, upsert, and delete XQL-based correlation detection rules
IOC Management: Full-sync, push, get-changes, enable, disable, and keep IOC indicators
Asset Management: Retrieve individual assets, list assets, get schema, and fetch field enum options
Asset Groups: Create, list, update, and delete asset groups
Vulnerability Management: Retrieve vulnerability details by CVE ID
Agent Distributions: Create install packages, check distribution status and download URLs
Audit Logs: Retrieve management audit logs and agent reports
Users and Roles: List users, set/remove roles, list user groups, list roles
Risk Management: List risky users and risky hosts
API Key Management: List and delete API keys
Issues: Search, create, and update Cortex XDR issues
Featured Fields: Replace featured field sets (AD groups, user groups, hosts, IP addresses)
System: Retrieve tenant information and API healthcheck

Credential Configuration

Before using the Palo Alto Cortex XDR integration in your workflows, you need to configure an API key through the Cortex XDR management console. The integration uses Palo Alto's proprietary per-request API key authentication — no OAuth, no user interaction required.

Authentication Method

Cortex XDR supports two API key types that determine how the Authorization header is computed on every request:

Key Type	Authorization Header Value
`standard`	Raw API key string sent directly
`advanced`	`hex(SHA-256(api_key + nonce + timestamp))` — signed per-request hash

Every request also includes three additional signed headers:

Header	Value
`x-xdr-auth-id`	Numeric API Key ID
`x-xdr-nonce`	64-character cryptographically random alphanumeric string (unique per request)
`x-xdr-timestamp`	Current epoch time in milliseconds

Credential Fields

Field	Required	Description	Example
`apiKeyId`	Yes	Numeric identifier of the API key shown in the Cortex XDR console. Sent as `x-xdr-auth-id`.	`12`
`apiKey`	Yes	Secret API key string. For standard keys, sent directly. For advanced keys, used to compute the per-request hash.	`AbCdEfGh1234567890...`
`apiKeyType`	No	Auth scheme to use: `standard` or `advanced`. Defaults to `standard` when omitted.	`standard`
`baseUrl`	Yes	Your Cortex XDR tenant base URL. Trailing slashes are stripped automatically.	`https://api-tenant.xdr.us.paloaltonetworks.com`

Finding Your Tenant Base URL

The tenant base URL follows the pattern:

https://api-<fqdn>.xdr.<region>.paloaltonetworks.com

You can find the exact URL in the Cortex XDR console:

Log in to the Cortex XDR management console
Navigate to Settings > Configurations > Integrations > API Keys
The tenant URL is displayed at the top of the page — copy it exactly as shown, without a trailing slash

Common regional patterns:

Region	URL pattern
US	`https://api-<fqdn>.xdr.us.paloaltonetworks.com`
EU	`https://api-<fqdn>.xdr.eu.paloaltonetworks.com`
APAC	`https://api-<fqdn>.xdr.sg.paloaltonetworks.com`
Australia	`https://api-<fqdn>.xdr.au.paloaltonetworks.com`
Japan	`https://api-<fqdn>.xdr.jp.paloaltonetworks.com`

Choosing Standard vs. Advanced API Keys

Standard keys (apiKeyType: standard):

The raw API key string is sent directly in the Authorization header
Simpler to configure and debug
Suitable for internal, trusted network environments
Default when apiKeyType is omitted

Advanced keys (apiKeyType: advanced):

A per-request SHA-256 hash of (api_key + nonce + timestamp) is sent in Authorization
The nonce changes on every request; the timestamp is epoch milliseconds
Provides replay-attack protection — intercepted requests cannot be replayed
Recommended for production deployments and external-facing integrations

Important: The key type (standard or advanced) must match the type selected when the key was created in the Cortex XDR console. Mismatching types will result in authentication failures.

Creating an API Key in the Cortex XDR Console

Log in to the Cortex XDR management console as an administrator
Navigate to Settings > Configurations > Integrations > API Keys
Click + New Key
Select the key type:
- Choose Standard for simple Authorization: <api_key> auth
- Choose Advanced for per-request HMAC-SHA-256 signed auth
Set the Security Level:
- Choose Standard for general integrations
- Choose Super Admin only for operations requiring administrative API access (user management, API key management, tenant settings)
Optionally add a Comment to identify the key's purpose (e.g., "NINA Integration")
Click Generate
Copy the API key immediately — it is displayed only once and cannot be retrieved again
Note the numeric Key ID shown in the key list — this is your apiKeyId

Caution: Store the API key securely. Anyone with the key and key ID can make API calls with the permissions granted to that key.

Required Permissions Per Resource

Cortex XDR uses role-based access control (RBAC) to govern what API keys can do. When creating an API key, you select a role. The role's permissions determine which API operations succeed. The table below maps each integration resource to the Cortex XDR permission required:

Resource	Operations	Required Cortex XDR Permission
Alert	`get`	Default API access (any valid key)
Case	`list`, `artifactList`, `update`	Cases And Issues → View (list/artifacts); Cases And Issues → Edit (update)
Incident	`get`, `getBulk`	Default API access
Endpoint	`get`, `getPolicy`, `getDeviceControlViolations`	Default API access
Endpoint	`delete`, `isolate`, `unisolate`, `scan`, `abortScan`, `aliasChange`, `triage`	Endpoint Management
Endpoint	`addTag`, `removeTag`	Endpoint Management
Endpoint Action	`getActionStatus`, `triagePresetList`	Default API access
Endpoint Action	`healthcheck`	Default API access
File Operation	`quarantine`, `restore`, `retrieveFiles`, `getRetrieveResult`	Endpoint Management
File Operation	`getQuarantineStatus`	Default API access
File Operation	`blocklist`, `allowlist`, `removeBlocklist`, `removeAllowlist`	Endpoint Management
Script (legacy)	`list`, `getMetadata`, `getCode`	Default API access
Script (legacy)	`run`, `runSnippet`, `runCommands`, `runDeleteFile`, `runFileExists`, `runKillProcess`	Scripts Management
Script (legacy)	`getExecutionStatus`, `getExecutionResults`, `getExecutionFiles`	Default API access
Automation Script	`create`, `get`, `delete`	Scripts Management
Automation Playbook	`create`, `get`, `delete`	Scripts Management
XQL Query	`startGeneric`, `getResults`, `getQuota`, `start*` (all dataset queries)	Investigation → XQL
XQL Query	`libraryCreate`, `libraryList`, `libraryDelete`	Investigation → XQL Library
BIOC Rule	`list`	Default API access
BIOC Rule	`upsert`, `delete`	Threat Intelligence → BIOC Manage
Correlation Rule	`list`	Default API access
Correlation Rule	`upsert`, `delete`	Threat Intelligence → Correlation Manage
IOC	`getChanges`	Default API access
IOC	`fullSync`, `push`, `enable`, `disable`, `keepFile`	Threat Intelligence → IOC Manage
Asset	`get`, `list`, `getSchema`, `getFieldOptions`	Asset Management → View
Asset Group	`create`, `update`, `delete`	Asset Management → Manage
Asset Group	`list`	Asset Management → View
Vulnerability	`get`	Vulnerability Management → View
Distribution	`create`, `getStatus`, `getDistributionUrl`, `getVersions`	Default API access
Audit Log	`getManagementLogs`, `getAgentReports`	Audit → View
User	`list`, `setRole`, `removeRole`	Administration → User Management
User Group	`list`	Administration → User Management
Role	`list`	Administration → User Management
Risky User	`list`	Investigation → Risk Management
Risky Host	`list`	Investigation → Risk Management
API Key	`list`, `delete`	Administration → API Keys
Issue	`list`, `create`, `update`	Cases And Issues → View (list); Cases And Issues → Edit (create/update)
Featured Field	`replace`	Administration → Featured Fields
System	`getTenantInfo`	Default API access

Recommendation: Create a dedicated API key for this integration with only the permissions your workflows actually need. Avoid using Super Admin keys unless required. Read-only workflows should use a key with read permissions only.

Creating a Cortex XDR Credential in NINA

Navigate to the Credentials section in NINA
Click Add New Credential
Fill in the credential details:
- Name: A descriptive name (e.g., "Cortex XDR Production")
- Description: Optional — describe the key's purpose and scope
- Integration Service: Select "Palo Alto Cortex XDR"
- Auth Type: Select "API Key"
- API Key ID: Enter the numeric key ID from the Cortex XDR console
- API Key: Enter the secret API key string
- API Key Type: Select standard or advanced (must match the type chosen when creating the key)
- Base URL: Enter your tenant URL (e.g., https://api-tenant.xdr.us.paloaltonetworks.com)
Click Test Connection to verify — this makes a live call to POST /public_api/v1/alerts/get_alerts/ with a minimal payload to confirm authentication succeeds
Click Save

Request Mechanics

Understanding how requests are built helps when troubleshooting failures or constructing complex parameters.

Standard POST Requests

Most operations use POST with a JSON body shaped as:

{
  "request_data": { <your parameters> }
}

The integration wraps your parameters in request_data automatically.

GET Requests

Some operations (assets by ID, case artifacts, healthcheck, asset schema, asset field options) use GET with no body. The resource ID or path segment is appended directly to the URL path.

Vulnerability Endpoint

The vulnerability.get operation uses a non-standard path prefix (/uvem/v1/) instead of /public_api/v1/, and passes the CVE ID as a URL query parameter:

GET /uvem/v1/vulnerabilities?vulnerabilityId=<CVE-ID>

Multipart Uploads

The following operations upload files using multipart/form-data POST instead of JSON:

automationScript.create — uploads a script file
automationPlaybook.create — uploads a playbook file
ioc.fullSync — uploads a full IOC replacement file
ioc.keepFile — uploads an IOC file to add/update without removing existing entries

For these operations, provide file (the file content as a string) and file_name (the filename to use in the form).

HTTP Timeout

The integration uses a default HTTP client timeout of 90 seconds per request.

Error Responses

Cortex XDR API errors follow the envelope:

{
  "reply": {
    "err_code": 500,
    "err_msg": "description of the error",
    "err_extra": null
  }
}

The integration extracts err_msg and surfaces it as the error message. If the body is empty (HTTP 2xx with no content), the integration returns {"success": true}.

Supported Resources and Operations

Alert

Retrieve security alerts from Cortex XDR with flexible filter and sort controls.

Operation	Name	Description
`get`	Get Alerts	Retrieve alerts with optional filters, pagination, and sorting

Key parameters for get:

search_from — starting index for pagination (default: 0)
search_to — ending index for pagination (e.g., 100 to retrieve the first 100)
filters — array of filter objects; each object has field, operator, and value
sort_field — field name to sort by (e.g., creation_time)
sort_keyword — sort direction: asc or desc

The sort_field and sort_keyword flat parameters are automatically converted to the nested sort object expected by the API:

{ "sort": { "field": "creation_time", "keyword": "desc" } }

Case

Manage Cortex XDR cases (the replacement for deprecated XSOAR incident endpoints).

Operation	Name	Description
`list`	Search Cases	Search and list cases with filters, sorting, and pagination
`artifactList`	Get Case Artifacts	Retrieve artifacts (files, network connections, etc.) attached to a specific case
`update`	Update Case	Update the status, resolution reason, or comment on a case

Key parameters for list:

search_from, search_to — pagination bounds
filters — array of filter objects (field, operator, value)
sort_field, sort_keyword — sort controls (auto-nested by the integration)

Key parameters for artifactList:

case_id (required) — the case ID (e.g., "1234")

Key parameters for update:

case_id (required) — the case ID to update
status — new status value
resolve_reason — resolution reason (when closing)
resolve_comment — comment to add

Note: case_id is extracted from the parameters and appended to the URL path. Do not include it in the request body — the integration handles this automatically.

Incident

Retrieve Cortex XDR incidents and their extra data.

Operation	Name	Description
`get`	Get Incidents	List incidents with filters, pagination, and sorting
`getBulk`	Get Multiple Incidents Extra Data	Retrieve full extra data for multiple incidents in one call

Key parameters for get:

search_from, search_to — pagination bounds
filters — array of filter objects (field, operator, value)
sort_field, sort_keyword — sort controls (auto-nested)

Key parameters for getBulk:

incident_id_list — array of incident ID strings to retrieve extra data for

Endpoint

Query and manage Cortex XDR managed endpoints.

Operation	Name	Description
`get`	Get Endpoints	Retrieve endpoints matching filter criteria
`getPolicy`	Get Endpoint Policy	Retrieve the security policy applied to a specific endpoint
`getDeviceControlViolations`	Get Device Control Violations	Retrieve device control violations with filters and pagination
`delete`	Delete Endpoint	Permanently delete an endpoint from the XDR console
`isolate`	Isolate Endpoints	Network-isolate one or more endpoints
`unisolate`	Unisolate Endpoints	Restore network access to isolated endpoints
`scan`	Scan Endpoints	Initiate a malware scan on one or more endpoints
`abortScan`	Abort Endpoint Scan	Cancel an in-progress scan
`aliasChange`	Change Endpoint Alias	Rename an endpoint's display alias
`addTag`	Add Tag to Endpoints	Add a tag to one or more endpoints
`removeTag`	Remove Tag from Endpoints	Remove a tag from one or more endpoints
`triage`	Triage Endpoint	Submit a triage request for an endpoint

Key parameters for get:

filters — array of filter objects
search_from, search_to — pagination bounds
sort_field, sort_keyword — sort controls (auto-nested)

Key parameters for getPolicy:

endpoint_id (required) — ID of the endpoint

Key parameters for aliasChange:

endpoint_id (required) — endpoint ID
new_alias — the new alias name

Key parameters for addTag / removeTag:

endpoint_id_list (required) — array of endpoint ID strings
tags — array of tag strings to add or remove

Note: For addTag and removeTag, the endpoint IDs are joined with commas and appended to the URL path as {ids}:add or {ids}:remove. The integration constructs this path automatically.

Endpoint Action

Track the status of asynchronous endpoint response actions.

Operation	Name	Description
`getActionStatus`	Get Action Status	Poll the status of an endpoint action by its numeric action ID
`triagePresetList`	List Triage Presets	Retrieve the available triage presets
`healthcheck`	API Healthcheck	Verify API connectivity and service health

Key parameters for getActionStatus:

action_id (required) — numeric action ID returned when initiating an endpoint action

Note: Script execution actions use string action IDs (via scriptLegacy.getExecutionStatus); endpoint actions (isolate, scan, etc.) use numeric action IDs. Use endpointAction.getActionStatus for numeric IDs only.

File Operation

Quarantine, restore, retrieve, and manage file blocklists and allowlists on endpoints.

Operation	Name	Description
`quarantine`	Quarantine File	Quarantine a specific file on one or more endpoints
`getQuarantineStatus`	Get Quarantine Status	Check the quarantine status of a file on an endpoint
`restore`	Restore File	Restore a quarantined file on an endpoint
`retrieveFiles`	Retrieve Files	Initiate retrieval of files from one or more endpoints
`getRetrieveResult`	Get File Retrieve Result	Retrieve the output of a completed file retrieval action
`blocklist`	Blocklist File Hash	Add SHA-256 file hashes to the blocklist
`allowlist`	Allowlist File Hash	Add SHA-256 file hashes to the allowlist
`removeBlocklist`	Remove from Blocklist	Remove SHA-256 hashes from the blocklist
`removeAllowlist`	Remove from Allowlist	Remove SHA-256 hashes from the allowlist

Key parameters for quarantine:

endpoint_id_list (required) — array of endpoint IDs
file_path (required) — full path of the file to quarantine
file_hash (required) — SHA-256 hash of the file

Key parameters for getQuarantineStatus:

endpoint_id (required) — single endpoint ID
file_path (required) — path of the quarantined file
file_hash (required) — SHA-256 hash of the file

Key parameters for restore:

endpoint_id (required) — endpoint ID
file_hash (required) — SHA-256 hash of the file to restore

Key parameters for retrieveFiles:

endpoint_id_list (required) — array of endpoint IDs
At least one of: windows_file_paths, linux_file_paths, mac_file_paths (array of file path strings)

Key parameters for getRetrieveResult:

action_id (required) — numeric action ID from the retrieveFiles response

Key parameters for blocklist / allowlist / removeBlocklist / removeAllowlist:

hash_list (required) — non-empty array of SHA-256 hash strings

Script (Legacy)

Access and execute the pre-built scripts available in the Cortex XDR script library.

Operation	Name	Description
`list`	List Scripts	Retrieve available scripts with filters and pagination
`getMetadata`	Get Script Metadata	Retrieve metadata for a specific script by UID
`getCode`	Get Script Code	Retrieve the source code of a specific script
`run`	Run Script	Execute a script on one or more endpoints
`runSnippet`	Run Code Snippet	Execute an ad-hoc code snippet on endpoints
`runCommands`	Run Shell Commands	Execute shell commands on endpoints
`runDeleteFile`	Run Delete File	Delete a file on endpoints using the built-in script
`runFileExists`	Run File Exists Check	Check whether a file exists on endpoints
`runKillProcess`	Run Kill Process	Terminate a process by name on endpoints
`getExecutionStatus`	Get Script Execution Status	Poll the status of a script execution by action ID
`getExecutionResults`	Get Script Execution Results	Retrieve the output of a completed script execution
`getExecutionFiles`	Get Script Execution Files	Retrieve files produced by a completed script execution

Key parameters for getMetadata / getCode:

script_uid (required) — unique identifier of the script

Key parameters for run:

script_uid (required) — UID of the script to run
endpoint_id_list (required) — array of endpoint IDs
parameters_values — object of parameter names to values (for parameterized scripts)
timeout — execution timeout in seconds

Key parameters for runSnippet:

snippet_code (required) — the code snippet to execute (as a string)
endpoint_id_list (required) — array of endpoint IDs

Key parameters for runCommands:

commands (required) — shell commands to execute (as a newline-delimited string)
endpoint_id_list (required) — array of endpoint IDs

Key parameters for runDeleteFile / runFileExists:

file_path (required) — full path of the target file
endpoint_id_list (required) — array of endpoint IDs

Key parameters for runKillProcess:

process_name (required) — name of the process to kill
endpoint_id_list (required) — array of endpoint IDs

Key parameters for getExecutionStatus / getExecutionResults / getExecutionFiles:

action_id (required) — string action ID returned when the script was run (script action IDs are strings, not integers)

Automation Script

Upload and manage custom automation scripts in Cortex XDR.

Operation	Name	Description
`create`	Upload Automation Script	Upload a new automation script via multipart form upload
`get`	Get Automation Script	Retrieve an automation script by a filter field and value
`delete`	Delete Automation Script	Delete an automation script matching a filter

Key parameters for create:

file (required) — script file content as a string
file_name (required) — filename to use in the upload (e.g., my_script.py)

Key parameters for get / delete:

filter_field (required) — field to filter on (e.g., script_uid, name)
filter_value (required) — value to match

Note: These operations use multipart/form-data encoding for create, and a nested {"filter": {"field": ..., "value": ...}} body for get and delete. The integration builds these structures automatically from the flat parameters you provide.

Automation Playbook

Upload and manage automation playbooks in Cortex XDR.

Operation	Name	Description
`create`	Upload Automation Playbook	Upload a new playbook via multipart form upload
`get`	Get Automation Playbook	Retrieve a playbook by a filter field and value
`delete`	Delete Automation Playbook	Delete a playbook matching a filter

Key parameters for create:

file (required) — playbook file content as a string
file_name (required) — filename for the upload (e.g., incident_response.yml)

Key parameters for get / delete:

filter_field (required) — field to filter on
filter_value (required) — value to match

XQL Query

Execute and manage XQL (Extended Query Language) queries against Cortex XDR datasets.

Operation	Name	Description
`startGeneric`	Start Generic XQL Query	Execute a free-form XQL query
`getResults`	Get XQL Query Results	Poll and retrieve results of a running or completed query
`getQuota`	Get XQL Quota	Retrieve the tenant's XQL query quota usage
`startFileEvent`	Start File Event Query	Query the file event dataset with a pre-built XQL template
`startProcessEvent`	Start Process Event Query	Query the process event dataset
`startNetworkConnection`	Start Network Connection Query	Query the network connection dataset
`startDllModule`	Start DLL/Module Load Query	Query the module load (DLL) dataset
`startRegistry`	Start Registry Event Query	Query the registry event dataset
`startEventLog`	Start Event Log Query	Query the event log dataset
`startDns`	Start DNS Query	Query the DNS event dataset
`startFileDropper`	Start File Dropper Query	Query the file dropper dataset
`startProcessInstanceNetworkActivity`	Start Process Instance Network Query	Query process instance network activity
`startProcessCausalityNetworkActivity`	Start Process Causality Network Query	Query process causality network activity
`libraryCreate`	Create XQL Library Query	Save a query to the XQL library
`libraryList`	List XQL Library Queries	Retrieve saved queries from the XQL library
`libraryDelete`	Delete XQL Library Query	Remove a query from the XQL library

Key parameters for startGeneric:

query (required) — the XQL query string
timeframe — time range object (e.g., {"from": 1700000000000, "to": 1700100000000})
max_fields — maximum number of fields to return per row
request_data — additional query options

Key parameters for getResults:

query_id (required) — query ID returned by a start* operation
format — response format: json or json_line
max_rows — maximum number of rows to return

Key parameters for libraryCreate:

name (required) — name for the saved query
query (required) — the XQL query string to save
description — optional description

Key parameters for libraryDelete:

query_id (required) — ID of the library query to delete

Note: XQL operations require the XQL license on your Cortex XDR tenant. Use getQuota to check remaining query capacity.

BIOC Rule

Manage Behavioral Indicator of Compromise (BIOC) detection rules.

Operation	Name	Description
`list`	List BIOC Rules	Retrieve all BIOC rules
`upsert`	Create or Update BIOC Rule	Insert or update a BIOC rule
`delete`	Delete BIOC Rule	Delete BIOC rules matching a filter

Key parameters for upsert:

xql (required) — the XQL query defining the BIOC rule behavior
name — display name for the rule
rule_id — if provided, updates an existing rule with this ID; if omitted, creates a new rule
severity — severity level: LOW, MEDIUM, HIGH, CRITICAL
description — human-readable description
mitre_techniques — array of MITRE ATT&CK technique IDs (e.g., ["T1059", "T1055"])
mitre_tactics — array of MITRE ATT&CK tactic IDs

Key parameters for delete:

filter_field (required) — field to filter on (e.g., rule_id, name)
filter_operator — comparison operator; defaults to eq
filter_value — value to match

Correlation Rule

Manage XQL-based correlation detection rules.

Operation	Name	Description
`list`	List Correlation Rules	Retrieve all correlation rules
`upsert`	Create or Update Correlation Rule	Insert or update a correlation rule
`delete`	Delete Correlation Rule	Delete a correlation rule by rule ID

Key parameters for upsert:

xql_query (required) — the XQL query defining the correlation logic
name — display name
rule_id — if provided, updates an existing rule; if omitted, creates a new rule
severity — severity level: LOW, MEDIUM, HIGH, CRITICAL
schedule_cron_expression — cron expression for scheduled execution (e.g., 0 * * * *)
mitre_techniques, mitre_tactics — MITRE ATT&CK mappings
suppression_fields — fields to use for alert de-duplication and suppression

Key parameters for delete:

rule_id (required) — ID of the correlation rule to delete

IOC

Manage Threat Intelligence indicators (Indicators of Compromise) in Cortex XDR.

Operation	Name	Description
`fullSync`	Full IOC Sync	Upload a file to replace all existing IOCs (complete replacement)
`push`	Push IOCs	Batch upsert individual IOC objects via JSON
`getChanges`	Get IOC Changes	Retrieve IOC changes since a given timestamp
`enable`	Enable IOCs	Enable a list of IOC indicators
`disable`	Disable IOCs	Disable a list of IOC indicators
`keepFile`	Keep File IOC Sync	Upload a file to add/update IOCs without removing existing entries

Key parameters for fullSync / keepFile:

file (required) — IOC file content as a string (CSV or JSON format per XDR spec)
file_name (required) — filename for the upload

Key parameters for push:

indicator (required) — non-empty array of IOC objects; each object should include indicator, type, severity, and optionally expiration_date, comment, class

Key parameters for getChanges:

last_update_ts (required) — epoch milliseconds timestamp; retrieves IOCs changed after this time

Key parameters for enable / disable:

indicators (required) — non-empty array of indicator value strings to enable or disable

Asset

Query the Cortex XDR asset inventory.

Operation	Name	Description
`get`	Get Asset	Retrieve a single asset by its asset ID
`list`	List Assets	Query the asset inventory with filters, pagination, and sorting
`getSchema`	Get Asset Schema	Retrieve the schema definition for the asset data model
`getFieldOptions`	Get Field Enum Options	Retrieve the allowed values for a specific asset enum field

Key parameters for get:

asset_id (required) — the asset identifier; appended to the URL path automatically

Key parameters for list:

filters — array of filter objects (field, operator, value)
search_from, search_to — pagination bounds
sort_field, sort_keyword — sort controls (auto-nested)

Key parameters for getFieldOptions:

field_name (required) — the asset field whose allowed values you want to retrieve; appended to the URL path automatically

Asset Group

Create and manage logical groupings of assets.

Operation	Name	Description
`create`	Create Asset Group	Create a new asset group
`list`	List Asset Groups	Retrieve all asset groups
`update`	Update Asset Group	Update an existing asset group
`delete`	Delete Asset Group	Delete an asset group

Key parameters for create:

name (required) — display name for the group
type (required) — group type (e.g., dynamic or static, per XDR schema)
Additional group configuration fields as supported by the XDR API

Key parameters for update / delete:

group_id (required) — ID of the asset group; appended to the URL path automatically

Vulnerability

Retrieve vulnerability details from the Cortex XDR vulnerability management module.

Operation	Name	Description
`get`	Get Vulnerability	Retrieve details for a specific vulnerability by CVE ID

Key parameters for get:

vulnerabilityId (required) — the CVE identifier (e.g., CVE-2021-44228)

Important: This operation calls a different API path (/uvem/v1/) and passes the CVE ID as a URL query parameter rather than in the request body. The integration handles this transparently — simply provide vulnerabilityId as a parameter.

Distribution

Manage Cortex XDR agent installation packages for endpoint onboarding.

Operation	Name	Description
`create`	Create Distribution	Create a new agent installation distribution package
`getStatus`	Get Distribution Status	Check the build status of a distribution package
`getDistributionUrl`	Get Distribution URL	Retrieve the download URL for a built distribution
`getVersions`	Get Agent Versions	Retrieve available Cortex XDR agent versions

Key parameters for create:

name (required) — display name for the distribution
platform (required) — target platform (e.g., windows, linux, macos)
Additional configuration parameters as supported by the XDR API

Key parameters for getStatus:

distribution_id (required) — ID returned by create

Key parameters for getDistributionUrl:

distribution_id (required) — distribution ID
package_type (required) — package format: pkg (installer) or sh (shell script)

Audit Log

Retrieve management and agent audit records.

Operation	Name	Description
`getManagementLogs`	Get Management Audit Logs	Retrieve console management audit logs with pagination and sorting
`getAgentReports`	Get Agent Audit Reports	Retrieve agent-reported audit events

Key parameters for getManagementLogs:

page — zero-indexed page number (default: 0)
limit — records per page (default: 20)
sort_field — field to sort by
sort_order — asc or desc

Note: The integration automatically converts page and limit to the search_from / search_to pagination format required by the XDR API, and nests sort_field / sort_order into the sort object.

User

Manage Cortex XDR user accounts and role assignments.

Operation	Name	Description
`list`	List Users	Retrieve all users in the tenant
`setRole`	Set User Role	Assign a role to a user
`removeRole`	Remove User Role	Remove a user's current role assignment

Key parameters for setRole:

user_email (required) — email address of the target user
role_name (required) — name of the role to assign

Key parameters for removeRole:

user_email (required) — email address of the target user

Note: Both setRole and removeRole call the same /rbac/set_user_role/ endpoint. removeRole automatically sets role_name to null in the request body to clear the assignment — you do not need to set this manually.

User Group

Retrieve Cortex XDR user group definitions.

Operation	Name	Description
`list`	List User Groups	Retrieve all user groups in the tenant

No required parameters.

Role

Retrieve Cortex XDR role definitions.

Operation	Name	Description
`list`	List Roles	Retrieve all roles defined in the tenant

No required parameters.

Risky User

Retrieve users flagged as high-risk by the Cortex XDR risk management engine.

Operation	Name	Description
`list`	List Risky Users	Retrieve users with elevated risk scores

Key parameters:

key_type — optional filter by risk key type
limit — maximum number of results to return

Risky Host

Retrieve hosts flagged as high-risk by the Cortex XDR risk management engine.

Operation	Name	Description
`list`	List Risky Hosts	Retrieve hosts with elevated risk scores

Key parameters:

key_type — optional filter by risk key type
limit — maximum number of results to return

API Key

Manage Cortex XDR API keys from within workflows.

Operation	Name	Description
`list`	List API Keys	Retrieve API keys with an optional filter
`delete`	Delete API Keys	Permanently delete one or more API keys by their numeric IDs

Key parameters for list:

filter_field — field to filter on (optional; if omitted, all keys are returned)
filter_operator — comparison operator (defaults to eq)
filter_value — filter value

Key parameters for delete:

key_id_list (required) — non-empty array of numeric API key IDs to delete

Caution: Deleting API keys is permanent and irreversible. Verify key IDs before calling delete. Deleting your own integration key will immediately invalidate all subsequent requests from this workflow.

Issue

Create, search, and update Cortex XDR issues.

Operation	Name	Description
`list`	Search Issues	Search and list issues with filters and pagination
`create`	Create Issue	Create a new Cortex XDR issue
`update`	Update Issue	Update an existing issue

Key parameters for list:

filters — array of filter objects
search_from, search_to — pagination bounds

Key parameters for create:

name (required) — issue title/name
severity (required) — severity level (e.g., LOW, MEDIUM, HIGH, CRITICAL)
domain (required) — domain or category the issue belongs to
Additional optional fields as supported by the XDR issue schema

Key parameters for update:

issue_id (required) — ID of the issue to update; appended to the URL path automatically
Update fields (status, comment, assignee, etc.) as supported by the XDR issue schema

Featured Field

Replace the contents of Cortex XDR featured field sets used for contextual enrichment.

Operation	Name	Description
`replace`	Replace Featured Fields	Replace all values in a featured field set with a new list

Key parameters for replace:

field_type (required) — the featured field set to replace; must be one of:
- ad_groups — Active Directory groups
- user_groups — user groups
- hosts — host names or IPs
- ip_addresses — IP address ranges
fields (required) — non-empty array of field value objects

Note: This is a full replacement — the existing entries in the specified field set are completely overwritten by the provided list.

System

Retrieve tenant and system information.

Operation	Name	Description
`getTenantInfo`	Get Tenant Info	Retrieve metadata about the Cortex XDR tenant

No required parameters.

Parameter Merging and Templating

The Cortex XDR integration takes full advantage of NINA's parameter merging and templating capabilities.

Parameter Sources (in order of precedence)

Node Parameters: Parameters configured directly in the Cortex XDR Integration Node
Extracted Parameters: Parameters automatically extracted from the input data
Input Data: The complete input data from upstream nodes

When a Cortex XDR Integration Node executes:

It combines parameters from all sources
Node parameters take precedence over extracted parameters
Template variables within parameters are resolved using {{variable_name}} syntax
The combined parameters are used to execute the operation

Template Variable Syntax

Use {{variable_name}} to inject values from upstream nodes:

{
  "case_id": "{{case_id_from_upstream}}"
}

Example: Alert Investigation

Retrieve the Latest 50 Alerts

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "alert",
  "operation": "get",
  "parameters": {
    "search_from": 0,
    "search_to": 50,
    "sort_field": "creation_time",
    "sort_keyword": "desc"
  }
}

Retrieve High-Severity Alerts with a Filter

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "alert",
  "operation": "get",
  "parameters": {
    "search_from": 0,
    "search_to": 100,
    "filters": [
      {
        "field": "severity",
        "operator": "eq",
        "value": ["high", "critical"]
      }
    ],
    "sort_field": "creation_time",
    "sort_keyword": "desc"
  }
}

Example: Case Management

Search for Open Cases

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "case",
  "operation": "list",
  "parameters": {
    "search_from": 0,
    "search_to": 25,
    "filters": [
      {
        "field": "status",
        "operator": "eq",
        "value": ["new", "under_investigation"]
      }
    ],
    "sort_field": "creation_time",
    "sort_keyword": "desc"
  }
}

Get Case Artifacts

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "case",
  "operation": "artifactList",
  "parameters": {
    "case_id": "{{case_id}}"
  }
}

Update Case Status

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "case",
  "operation": "update",
  "parameters": {
    "case_id": "{{case_id}}",
    "status": "resolved",
    "resolve_reason": "resolved_threat",
    "resolve_comment": "Threat contained and remediated. Endpoints isolated and cleaned."
  }
}

Example: Endpoint Response Actions

Isolate a Compromised Endpoint

Input Data from Previous Node:

{
  "endpoint_id": "abc123def456",
  "incident_id": "INC-2026-0087"
}

Node Configuration:

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "endpoint",
  "operation": "isolate",
  "parameters": {
    "filters": [
      {
        "field": "endpoint_id_list",
        "operator": "in",
        "value": ["{{endpoint_id}}"]
      }
    ],
    "incident_id": "{{incident_id}}"
  }
}

Scan Endpoints Matching a Filter

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "endpoint",
  "operation": "scan",
  "parameters": {
    "filters": [
      {
        "field": "endpoint_id_list",
        "operator": "in",
        "value": ["{{endpoint_id_1}}", "{{endpoint_id_2}}"]
      }
    ]
  }
}

Check Action Status

After triggering an endpoint action, poll its status using the returned numeric action ID:

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "endpointAction",
  "operation": "getActionStatus",
  "parameters": {
    "action_id": "{{action_id}}"
  }
}

Add a Tag to Endpoints

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "endpoint",
  "operation": "addTag",
  "parameters": {
    "endpoint_id_list": ["{{endpoint_id}}"],
    "tags": ["incident-2026-087", "under-investigation"]
  }
}

Example: File Operations

Quarantine a Malicious File

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "fileOperation",
  "operation": "quarantine",
  "parameters": {
    "endpoint_id_list": ["{{endpoint_id}}"],
    "file_path": "C:\\Users\\victim\\Downloads\\malware.exe",
    "file_hash": "{{sha256_hash}}"
  }
}

Blocklist a File Hash

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "fileOperation",
  "operation": "blocklist",
  "parameters": {
    "hash_list": [
      "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "{{malware_sha256}}"
    ]
  }
}

Retrieve a File from an Endpoint

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "fileOperation",
  "operation": "retrieveFiles",
  "parameters": {
    "endpoint_id_list": ["{{endpoint_id}}"],
    "windows_file_paths": ["C:\\Windows\\Temp\\suspicious.log"]
  }
}

Example: Script Execution

List Available Scripts

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "scriptLegacy",
  "operation": "list",
  "parameters": {
    "search_from": 0,
    "search_to": 50
  }
}

Run a Script on Endpoints

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "scriptLegacy",
  "operation": "run",
  "parameters": {
    "script_uid": "{{script_uid}}",
    "endpoint_id_list": ["{{endpoint_id}}"],
    "parameters_values": {
      "process_name": "suspicious_process.exe"
    },
    "timeout": 60
  }
}

Kill a Process on Endpoints

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "scriptLegacy",
  "operation": "runKillProcess",
  "parameters": {
    "process_name": "{{malware_process_name}}",
    "endpoint_id_list": ["{{endpoint_id}}"]
  }
}

Poll Script Execution Results

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "scriptLegacy",
  "operation": "getExecutionResults",
  "parameters": {
    "action_id": "{{script_action_id}}"
  }
}

Example: XQL Queries

Start a Generic XQL Query

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "xqlQuery",
  "operation": "startGeneric",
  "parameters": {
    "query": "dataset = xdr_data | filter event_type = PROCESS | fields actor_process_image_name, actor_process_command_line | limit 100",
    "timeframe": {
      "from": 1750000000000,
      "to": 1750086400000
    }
  }
}

Retrieve XQL Query Results

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "xqlQuery",
  "operation": "getResults",
  "parameters": {
    "query_id": "{{xql_query_id}}",
    "format": "json",
    "max_rows": 1000
  }
}

Query Network Connections Dataset

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "xqlQuery",
  "operation": "startNetworkConnection",
  "parameters": {
    "query": "dataset = xdr_data | filter event_type = NETWORK | filter action_remote_port = 4444 | fields agent_hostname, action_remote_ip | limit 50"
  }
}

Save a Query to the XQL Library

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "xqlQuery",
  "operation": "libraryCreate",
  "parameters": {
    "name": "Suspicious PowerShell Execution",
    "query": "dataset = xdr_data | filter event_type = PROCESS | filter actor_process_image_name = 'powershell.exe' | filter actor_process_command_line contains '-EncodedCommand' | fields agent_hostname, actor_process_command_line",
    "description": "Detects PowerShell execution with encoded commands — potential obfuscation indicator"
  }
}

Example: IOC Management

Push IOC Indicators

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "ioc",
  "operation": "push",
  "parameters": {
    "indicator": [
      {
        "indicator": "malicious-c2.example.com",
        "type": "DOMAIN_NAME",
        "severity": "HIGH",
        "expiration_date": "2026-12-31T00:00:00Z",
        "comment": "APT29 C2 domain — block immediately"
      },
      {
        "indicator": "198.51.100.42",
        "type": "IP",
        "severity": "HIGH",
        "expiration_date": "2026-12-31T00:00:00Z",
        "comment": "Known malicious IP from threat intel feed"
      }
    ]
  }
}

Push IOCs with Dynamic Input

Input Data:

{
  "malicious_domain": "c2.attacker-infra.net",
  "threat_actor": "APT41",
  "expiry": "2027-01-01T00:00:00Z"
}

Node Configuration:

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "ioc",
  "operation": "push",
  "parameters": {
    "indicator": [
      {
        "indicator": "{{malicious_domain}}",
        "type": "DOMAIN_NAME",
        "severity": "HIGH",
        "expiration_date": "{{expiry}}",
        "comment": "C2 domain attributed to {{threat_actor}}"
      }
    ]
  }
}

Retrieve IOC Changes Since a Timestamp

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "ioc",
  "operation": "getChanges",
  "parameters": {
    "last_update_ts": 1750000000000
  }
}

Disable IOC Indicators

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "ioc",
  "operation": "disable",
  "parameters": {
    "indicators": ["malicious-c2.example.com", "198.51.100.42"]
  }
}

Example: Vulnerability Management

Retrieve a Specific CVE

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "vulnerability",
  "operation": "get",
  "parameters": {
    "vulnerabilityId": "CVE-2021-44228"
  }
}

Example: User and RBAC Management

List All Users

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "user",
  "operation": "list",
  "parameters": {}
}

Assign a Role to a User

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "user",
  "operation": "setRole",
  "parameters": {
    "user_email": "{{analyst_email}}",
    "role_name": "Investigator"
  }
}

Remove a User's Role

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "user",
  "operation": "removeRole",
  "parameters": {
    "user_email": "{{analyst_email}}"
  }
}

Example: BIOC and Correlation Rules

Create a BIOC Rule

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "biocRule",
  "operation": "upsert",
  "parameters": {
    "name": "Suspicious LSASS Memory Access",
    "xql": "dataset = xdr_data | filter event_type = PROCESS | filter action_process_image_name = 'lsass.exe' | filter actor_process_image_name != 'MsMpEng.exe'",
    "severity": "HIGH",
    "description": "Detects unauthorized processes accessing LSASS memory — potential credential dumping",
    "mitre_techniques": ["T1003.001"],
    "mitre_tactics": ["TA0006"]
  }
}

Create a Correlation Rule

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "correlationRule",
  "operation": "upsert",
  "parameters": {
    "name": "Brute Force Login Attempt",
    "xql_query": "dataset = xdr_data | filter event_type = AUTHENTICATION | filter action_local_ip != null | summarize count() as attempt_count by action_local_ip | filter attempt_count > 50",
    "severity": "MEDIUM",
    "schedule_cron_expression": "0 * * * *",
    "mitre_techniques": ["T1110"]
  }
}

Example: Audit and System

Retrieve Management Audit Logs

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "auditLog",
  "operation": "getManagementLogs",
  "parameters": {
    "page": 0,
    "limit": 50,
    "sort_field": "timestamp",
    "sort_order": "desc"
  }
}

Get Tenant Information

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "system",
  "operation": "getTenantInfo",
  "parameters": {}
}

API Healthcheck

{
  "integration_service": "paloalto-cortex-xdr",
  "resource": "endpointAction",
  "operation": "healthcheck",
  "parameters": {}
}

Common Workflow Patterns

Incident Response — Endpoint Isolation and Forensic Collection

alert.get — retrieve high-severity alerts filtered by severity
incident.get — retrieve associated incident details
endpoint.get — verify endpoint status and details
endpoint.isolate — isolate the compromised endpoint from the network
endpointAction.getActionStatus — poll until isolation action status is COMPLETED
scriptLegacy.run — run a forensic collection script on the endpoint
scriptLegacy.getExecutionResults — retrieve the forensic data
case.update — update the case status to reflect containment

Threat Intelligence IOC Lifecycle

Receive a threat intel feed with indicators (IPs, domains, hashes)
ioc.push — batch-upsert the indicators into Cortex XDR TIM
ioc.getChanges — periodically sync new IOC changes from XDR
ioc.disable — disable indicators whose confidence has dropped
ioc.fullSync — perform a periodic complete replacement of the IOC dataset

XQL-Based Threat Hunting

xqlQuery.startGeneric — run a threat hunting XQL query against the XDR dataset
xqlQuery.getResults — poll for results (repeat until status is SUCCESS)
Process the result rows to identify suspicious activity
endpoint.get — look up endpoint details for flagged hosts
endpoint.isolate or scriptLegacy.run — take containment action if confirmed

Vulnerability Prioritization and Asset Context

vulnerability.get — retrieve details for a known CVE (e.g., from a threat feed)
asset.list — identify assets in the inventory with matching software/attributes
assetGroup.create — create an asset group for affected systems
xqlQuery.startGeneric — hunt for exploitation indicators on affected endpoints
biocRule.upsert — deploy a BIOC rule to detect exploitation attempts

Automated Risky User Response

riskyUser.list — retrieve users with elevated risk scores
endpoint.get — find endpoints associated with risky users
scriptLegacy.runKillProcess — terminate suspicious processes on those endpoints
user.setRole — temporarily reduce the user's role permissions pending investigation
case.update or issue.create — open or update an investigation record

Field Reference

Alert Severity Values

Value	Description
`low`	Low-severity alert
`medium`	Medium-severity alert
`high`	High-severity alert
`critical`	Critical-severity alert

Endpoint Action Status Values

Value	Description
`PENDING`	Action queued, not yet delivered
`IN_PROGRESS`	Action delivered, executing on endpoint
`COMPLETED_SUCCESSFULLY`	Action completed without errors
`FAILED`	Action failed — check error details
`TIMEOUT`	Action timed out before completion
`CANCELED`	Action was canceled
`EXPIRED`	Action expired before the endpoint came online

IOC Type Values

Value	Description
`DOMAIN_NAME`	Domain name indicator
`IP`	IPv4 or IPv6 address
`FILE_SHA256`	SHA-256 file hash
`FILE_MD5`	MD5 file hash
`URL`	URL indicator

IOC Severity Values

Value	Description
`INFORMATIONAL`	Informational — no blocking action
`LOW`	Low severity
`MEDIUM`	Medium severity
`HIGH`	High severity
`CRITICAL`	Critical — highest priority

BIOC / Correlation Rule Severity Values

Value	Description
`LOW`	Low-impact behavioral indicator
`MEDIUM`	Medium-impact indicator
`HIGH`	High-impact indicator
`CRITICAL`	Critical — immediate response required

Featured Field Type Values

Value	Affects
`ad_groups`	Active Directory group names used for enrichment
`user_groups`	User group identifiers
`hosts`	Host names or IP addresses
`ip_addresses`	IP address ranges

Distribution Package Types

Value	Description
`pkg`	Installer package (Windows MSI, macOS pkg)
`sh`	Shell script installer (Linux)

Troubleshooting

Issue	Resolution
`Cortex XDR API error [HTTP 401]`	The API key or key ID is incorrect, or the key has been revoked. Verify both `apiKeyId` and `apiKey` in your NINA credential match the values in the Cortex XDR console.
`Cortex XDR API error [HTTP 401]` with advanced key type	The `apiKeyType` must match the type selected when the key was created. If you created a "Standard" key in the console but set `apiKeyType: advanced` in NINA, authentication will fail.
`credential validation failed` on Test Connection	The base URL may be wrong or unreachable. Confirm the URL is exactly as shown in the Cortex XDR console under Settings > Integrations > API Keys, with no trailing slash.
`Cortex XDR API error [HTTP 403]`	The API key's role does not have the permission required for this operation. Review the permissions table above and ensure the key was created with a role that includes the needed permission.
`Cortex XDR API error [HTTP 404]`	The resource ID (case ID, endpoint ID, asset ID, etc.) does not exist or is not accessible with your API key. Double-check the ID value and that your key has access to that tenant resource.
`action_id is required`	Endpoint action IDs are numeric (integers). Script execution action IDs are strings. Use `endpointAction.getActionStatus` for endpoint actions and `scriptLegacy.getExecutionStatus` for script actions.
`case_id is required`	The `case_id` parameter was not provided. It must be a non-empty string.
`endpoint_id_list is required`	Endpoint operations that act on multiple endpoints require `endpoint_id_list` as a non-empty array, not a single string.
`hash_list is required`	File hash blocklist/allowlist operations require `hash_list` as a non-empty array of SHA-256 hash strings.
`vulnerabilityId is required`	The `vulnerability.get` operation requires the exact CVE identifier (e.g., `CVE-2021-44228`).
Sort parameters ignored	Ensure you are using `sort_field` and `sort_keyword` (not `sort_order`) for all resources except `auditLog.getManagementLogs`, which uses `sort_field` and `sort_order`. The integration auto-nests these into the correct API format.
XQL queries return empty results	Confirm that the `timeframe` range includes data and that the XQL syntax is correct. Use `xqlQuery.getQuota` to ensure you have remaining XQL capacity.
Script action results not available yet	Script execution is asynchronous. Poll `scriptLegacy.getExecutionStatus` until `status` is `COMPLETED_SUCCESSFULLY` before calling `getExecutionResults`.
`at least one of windows_file_paths, linux_file_paths, or mac_file_paths is required`	The `fileOperation.retrieveFiles` operation requires at least one OS-specific file path list. Provide the appropriate list for the target endpoint OS.
`field_type must be one of: ad_groups, user_groups, hosts, ip_addresses`	The `featuredField.replace` operation only accepts these four field type values exactly as listed.
Multipart upload failures	For `automationScript.create`, `automationPlaybook.create`, `ioc.fullSync`, and `ioc.keepFile`, ensure `file` contains the file content as a string and `file_name` is a non-empty filename.
`key_id_list is required`	The `apiKey.delete` operation requires a non-empty array of numeric key IDs. Obtain the IDs first using `apiKey.list`.
HTTP 500 on `auditLog.getManagementLogs`	Do not send raw `sort_field`/`sort_order` and `page`/`limit` together in manual API calls — the integration converts these automatically. Use only the NINA parameters listed above.

Best Practices

Use the minimum necessary permissions: Create API keys with only the roles and permissions your workflows actually need. Read-only investigation workflows should use a key with read-only permissions. Avoid Super Admin keys unless you explicitly need user or key management operations.
Store the API key only in NINA credentials: Never embed the apiKey or apiKeyId directly in workflow parameters, comments, or logs. Use NINA's credential manager exclusively.
Prefer advanced key type for production: Advanced API keys provide per-request replay-attack protection. Use standard keys only for development or isolated internal environments where the added complexity is not justified.
Rotate API keys periodically: Cortex XDR API keys do not expire automatically, but rotating them limits the exposure window if a key is ever compromised. Update the NINA credential when you rotate a key to avoid workflow failures.
Poll asynchronous actions before proceeding: Endpoint actions (isolate, scan, quarantine, script execution) are asynchronous — they return immediately with a PENDING status. Always build polling logic using endpointAction.getActionStatus or scriptLegacy.getExecutionStatus before consuming results in downstream nodes.
Use string action IDs for scripts, numeric for endpoint actions: endpointAction.getActionStatus expects a numeric action_id; scriptLegacy.getExecutionStatus expects a string action_id. Mixing these up is a common source of validation errors.
Use paginated list operations for large datasets: Most list operations accept search_from and search_to. Retrieve data in pages (e.g., batches of 100) rather than requesting a single large result set to avoid timeouts.
Set expiration dates on IOC indicators: IOC indicators without an expiration date remain active indefinitely. Set expiration_date based on your threat intelligence confidence window and build cleanup workflows for expired or stale indicators.
Test credentials before production use: Use the Test Connection button when creating or updating NINA credentials. This makes a minimal live API call to confirm authentication succeeds before any workflow runs.
Verify endpoint IDs before taking disruptive actions: Isolation, file quarantine, and process termination have immediate operational impact. Always look up the endpoint by filter first using endpoint.get and confirm the correct endpoint ID before calling mutating operations.
Use ioc.keepFile for incremental IOC updates: If you need to add or update indicators without replacing the entire dataset, use ioc.keepFile instead of ioc.fullSync. fullSync replaces all existing IOCs and should be reserved for scheduled full-dataset replacements.
Match apiKeyType to the key type in the console: If a key was created as "Standard" in the Cortex XDR console, set apiKeyType: standard in NINA. If created as "Advanced", set apiKeyType: advanced. Mismatching types produces HTTP 401 errors that can be difficult to diagnose.
Use xqlQuery.getQuota before long hunts: XQL queries consume tenant quota. Check remaining capacity before running large queries in automated workflows to avoid hitting limits mid-investigation.
Use featuredField.replace with a complete list: The replace operation overwrites the entire field set. If you want to add a single entry, first retrieve the current list, append the new entry, and then call replace with the full merged list.

Security Considerations

Protect API keys as secrets: A Cortex XDR API key combined with the key ID grants full access to the API operations permitted by that key's role. Treat them with the same care as passwords. Store them exclusively in NINA's credential manager.
Use dedicated keys per integration: Create one API key for each separate integration or environment (development, staging, production). This limits the blast radius if a key is compromised and makes it easy to revoke access for a specific integration without affecting others.
Restrict key roles to required permissions: A key with Endpoint Management permission can isolate or delete endpoints. A key with Scripts Management can run arbitrary code on endpoints. Grant only the permissions actually needed by your workflow.
Audit endpoint action usage: Operations like endpoint isolation, file quarantine, and process termination have direct, immediate operational impact on managed systems. Implement workflow-level review or approval gates for disruptive actions, and ensure all actions are logged with meaningful context (case IDs, analyst names, incident references).
Monitor for anomalous API key activity: Use apiKey.list and auditLog.getManagementLogs in regular reporting workflows to detect unexpected API key usage or privilege changes.
Review IOC indicator lifecycles: A misconfigured block indicator can disrupt legitimate business traffic. Periodically audit active indicators using ioc.getChanges and implement expiration-date discipline to prevent stale indicators from persisting indefinitely.
Control access to BIOC and correlation rule management: BIOC and correlation rules affect detections across the entire tenant. Restrict the API key roles that can upsert or delete rules to a small number of trusted automation accounts.
Do not log or echo API key values: Ensure that workflow nodes processing credential outputs (e.g., from apiKey.list) do not inadvertently log the full key string. API key list responses may include masked key values — do not attempt to unmask or store them outside of NINA's credential store.

Updated: 2026-06-22

Overview​

Status​

Credential Configuration​

Authentication Method​

Credential Fields​

Finding Your Tenant Base URL​

Choosing Standard vs. Advanced API Keys​

Creating an API Key in the Cortex XDR Console​

Required Permissions Per Resource​

Creating a Cortex XDR Credential in NINA​

Request Mechanics​

Standard POST Requests​

GET Requests​

Vulnerability Endpoint​

Multipart Uploads​

HTTP Timeout​

Error Responses​

Supported Resources and Operations​

Alert​

Case​

Incident​

Endpoint​

Endpoint Action​

File Operation​

Script (Legacy)​

Automation Script​

Automation Playbook​

XQL Query​

BIOC Rule​

Correlation Rule​

IOC​

Asset​

Asset Group​

Vulnerability​

Distribution​

Audit Log​

User​

User Group​

Role​

Risky User​

Risky Host​

API Key​

Issue​

Featured Field​

System​

Parameter Merging and Templating​

Parameter Sources (in order of precedence)​

Template Variable Syntax​

Example: Alert Investigation​

Retrieve the Latest 50 Alerts​

Retrieve High-Severity Alerts with a Filter​

Example: Case Management​

Search for Open Cases​

Get Case Artifacts​

Update Case Status​

Example: Endpoint Response Actions​

Isolate a Compromised Endpoint​

Input Data from Previous Node:​

Node Configuration:​

Scan Endpoints Matching a Filter​

Check Action Status​

Add a Tag to Endpoints​

Example: File Operations​

Quarantine a Malicious File​

Blocklist a File Hash​

Retrieve a File from an Endpoint​

Example: Script Execution​

List Available Scripts​

Run a Script on Endpoints​

Kill a Process on Endpoints​

Poll Script Execution Results​

Example: XQL Queries​

Start a Generic XQL Query​

Retrieve XQL Query Results​

Query Network Connections Dataset​

Save a Query to the XQL Library​

Example: IOC Management​

Push IOC Indicators​

Push IOCs with Dynamic Input​

Input Data:​

Overview

Status

Credential Configuration

Authentication Method

Credential Fields

Finding Your Tenant Base URL

Choosing Standard vs. Advanced API Keys

Creating an API Key in the Cortex XDR Console

Required Permissions Per Resource

Creating a Cortex XDR Credential in NINA

Request Mechanics

Standard POST Requests

GET Requests

Vulnerability Endpoint

Multipart Uploads

HTTP Timeout

Error Responses

Supported Resources and Operations

Alert

Case

Incident

Endpoint

Endpoint Action

File Operation

Script (Legacy)

Automation Script

Automation Playbook

XQL Query

BIOC Rule

Correlation Rule

IOC

Asset

Asset Group

Vulnerability

Distribution

Audit Log

User

User Group

Role

Risky User

Risky Host

API Key

Issue

Featured Field

System

Parameter Merging and Templating

Parameter Sources (in order of precedence)

Template Variable Syntax

Example: Alert Investigation

Retrieve the Latest 50 Alerts

Retrieve High-Severity Alerts with a Filter

Example: Case Management

Search for Open Cases

Get Case Artifacts

Update Case Status

Example: Endpoint Response Actions

Isolate a Compromised Endpoint

Input Data from Previous Node:

Node Configuration:

Scan Endpoints Matching a Filter

Check Action Status

Add a Tag to Endpoints

Example: File Operations

Quarantine a Malicious File

Blocklist a File Hash

Retrieve a File from an Endpoint

Example: Script Execution

List Available Scripts

Run a Script on Endpoints

Kill a Process on Endpoints

Poll Script Execution Results

Example: XQL Queries

Start a Generic XQL Query

Retrieve XQL Query Results

Query Network Connections Dataset

Save a Query to the XQL Library

Example: IOC Management

Push IOC Indicators

Push IOCs with Dynamic Input

Input Data: