sica-fondt/knowledge/cyber-skills/skills/implementing-soar-playbook-with-palo-alto-xsoar/references/api-reference.md

API Reference: Palo Alto Cortex XSOAR SOAR Playbook

Libraries Used

Library	Purpose
requests	HTTP client for XSOAR REST API
json	Parse incident and playbook payloads
os	Read XSOAR_URL and XSOAR_API_KEY environment variables

Installation

pip install requests

Authentication

import requests
import os

XSOAR_URL = os.environ["XSOAR_URL"]  # e.g., "https://xsoar.example.com"
headers = {
    "Authorization": os.environ["XSOAR_API_KEY"],
    "Content-Type": "application/json",
    "Accept": "application/json",
}

REST API Endpoints

Method	Endpoint	Description
POST	/incident	Create a new incident
POST	/incident/search	Search incidents
GET	/incident/{id}	Get incident details
POST	/incident/close	Close an incident
POST	/playbook/search	Search playbooks
GET	/playbook/{id}	Get playbook details
POST	/entry/execute/{playbook}	Run a playbook on an incident
POST	/automation/search	Search automation scripts
POST	/automation/execute	Execute an automation command
GET	/settings/integration/search	List integrations
POST	/indicators/search	Search indicators (IOCs)
POST	/indicators	Create indicators
GET	/health	System health check
GET	/user	Get current user info

Core Operations

Create an Incident

incident = {
    "name": "Phishing Alert - Suspicious Email",
    "type": "Phishing",
    "severity": 3,  # 0=Unknown, 1=Low, 2=Medium, 3=High, 4=Critical
    "labels": [
        {"type": "Email/from", "value": "attacker@evil.com"},
        {"type": "Email/subject", "value": "Urgent: Verify Account"},
    ],
    "customFields": {
        "sourceemail": "attacker@evil.com",
        "reportedby": "soc-analyst-1",
    },
}
resp = requests.post(
    f"{XSOAR_URL}/incident",
    headers=headers,
    json=incident,
    timeout=30,
)
incident_id = resp.json()["id"]

Search Incidents

search = {
    "filter": {
        "query": "type:Phishing AND severity:>=3",
        "period": {"fromValue": "7 days ago"},
    },
    "page": 0,
    "size": 50,
}
resp = requests.post(
    f"{XSOAR_URL}/incident/search",
    headers=headers,
    json=search,
    timeout=30,
)
incidents = resp.json().get("data", [])

Execute a Playbook on an Incident

resp = requests.post(
    f"{XSOAR_URL}/entry/execute/{playbook_name}",
    headers=headers,
    json={"investigationId": incident_id},
    timeout=30,
)

Search Playbooks

resp = requests.post(
    f"{XSOAR_URL}/playbook/search",
    headers=headers,
    json={
        "query": "name:*phishing*",
        "page": 0,
        "size": 20,
    },
    timeout=30,
)
playbooks = resp.json().get("playbooks", [])
for pb in playbooks:
    print(f"{pb['name']} — tasks: {len(pb.get('tasks', {}))}")

Run an Automation Command

resp = requests.post(
    f"{XSOAR_URL}/automation/execute",
    headers=headers,
    json={
        "script": "!ip ip=8.8.8.8",
        "investigationId": incident_id,
    },
    timeout=60,
)

Search Indicators (IOCs)

resp = requests.post(
    f"{XSOAR_URL}/indicators/search",
    headers=headers,
    json={
        "query": "type:IP AND verdict:malicious",
        "size": 100,
    },
    timeout=30,
)
indicators = resp.json().get("iocObjects", [])

Check Integration Health

resp = requests.get(
    f"{XSOAR_URL}/settings/integration/search",
    headers=headers,
    timeout=30,
)
integrations = resp.json().get("instances", [])
for inst in integrations:
    status = "healthy" if inst.get("enabled") else "disabled"
    print(f"{inst['name']} — brand: {inst['brand']} — {status}")

Output Format

{
  "id": "12345",
  "name": "Phishing Alert - Suspicious Email",
  "type": "Phishing",
  "severity": 3,
  "status": 1,
  "created": "2025-01-15T10:30:00Z",
  "phase": "Triage",
  "playbooks": ["Phishing Investigation - Generic v2"],
  "labels": [
    {"type": "Email/from", "value": "attacker@evil.com"}
  ]
}