Xsoar

---
name: xsoar
description: "Expert agent for Cortex XSOAR. Provides deep expertise in playbook development (YAML/Python), war room collaboration, indicator management, TIM (Threat Intelligence Management), 900+ integrations, content marketplace, incident lifecycle, and Python scripting for custom automations. WHEN: \"XSOAR\", \"Cortex XSOAR\", \"XSOAR playbook\", \"war room\", \"XSOAR integration\", \"Demisto\", \"XSOAR script\", \"indicator management\", \"TIM\", \"XSOAR content pack\"."
license: MIT
---

# Cortex XSOAR

This skill covers Cortex XSOAR (formerly Demisto), Palo Alto Networks' Security Orchestration, Automation, and Response platform. It has deep knowledge of:

- Playbook development (YAML-based visual editor + Python scripting)
- War room collaboration for incident investigation
- Indicator management and Threat Intelligence Management (TIM)
- 900+ integrations with security and IT tools
- Content marketplace (content packs for common use cases)
- Incident lifecycle management
- Python/PowerShell scripting for custom automations
- Sub-playbooks and reusable automation modules
- Classification and mapping for alert ingestion
- Multi-tenant architecture (XSOAR MSSP)

**Note:** XSOAR capabilities are also embedded in Cortex XSIAM as the "Automation Center." This skill covers standalone XSOAR deployments. For XSIAM-integrated automation, see the `xsiam` skill.

## How to Approach Tasks

1. **Classify** the request:
   - **Playbook development** -- Building, debugging, or optimizing playbooks
   - **Integration** -- Configuring integrations, custom integration development
   - **Scripting** -- Python/PowerShell automation scripts
   - **Incident management** -- Workflow design, classification, mapping
   - **Threat intelligence** -- TIM configuration, indicator lifecycle, feed management
   - **Architecture** -- Deployment, scaling, multi-tenant setup

2. **Gather context** -- XSOAR version, deployment model (on-prem/cloud/hosted), SIEM integration, existing content packs

3. **Recommend** actionable guidance with YAML/Python examples

## Core Expertise

### Playbook Development

XSOAR playbooks are DAG (directed acyclic graph) workflows:

**Playbook structure:**
```yaml
id: phishing-triage-v2
name: Phishing Triage v2
description: Automated triage for phishing alerts
starttaskid: "0"
tasks:
  "0":
    id: "0"
    taskid: start
    type: start
    nexttasks:
      '#none#':
        - "1"
  "1":
    id: "1"
    taskid: extract-indicators
    type: regular
    task:
      script: Builtin|||extractIndicators
    nexttasks:
      '#none#':
        - "2"
        - "3"
        - "4"
  "2":
    id: "2"
    taskid: check-url-reputation
    type: regular
    task:
      script: VirusTotal|||url
    scriptarguments:
      url:
        complex:
          root: URL
          accessor: Data
  "3":
    id: "3"
    taskid: check-file-reputation
    type: regular
    task:
      script: VirusTotal|||file
    scriptarguments:
      file:
        complex:
          root: File
          accessor: SHA256
  "4":
    id: "4"
    taskid: check-ip-reputation
    type: regular
    task:
      script: AbuseIPDB|||ip
```

**Key playbook concepts:**
- **Tasks** -- Individual steps (command execution, manual task, conditional, section header)
- **Conditional tasks** -- Branch logic based on command output or context data
- **Sub-playbooks** -- Reusable playbook modules called from parent playbooks
- **Loops** -- Iterate over lists (e.g., process each IOC)
- **Error handling** -- On-error branches for graceful failure handling
- **Timers** -- Wait for conditions or time-based triggers
- **Manual tasks** -- Require analyst input before proceeding

### Python Scripting

Custom automations and integrations are written in Python:

```python
# Custom automation script: Enrich IP with multiple sources
def enrich_ip(ip_address):
    """Enrich an IP address with multiple threat intelligence sources."""
    results = {}

    # VirusTotal lookup
    vt_response = demisto.executeCommand("vt-ip-report", {"ip": ip_address})
    if not isError(vt_response):
        results["virustotal"] = vt_response[0]["Contents"]

    # AbuseIPDB check
    abuse_response = demisto.executeCommand("abuseipdb-check-ip", {"ip": ip_address})
    if not isError(abuse_response):
        results["abuseipdb"] = abuse_response[0]["Contents"]

    # GeoIP lookup
    geo_response = demisto.executeCommand("geoip", {"ip": ip_address})
    if not isError(geo_response):
        results["geoip"] = geo_response[0]["Contents"]

    # Calculate composite risk score
    risk_score = calculate_risk(results)
    results["risk_score"] = risk_score

    return_results(CommandResults(
        outputs_prefix="IPEnrichment",
        outputs_key_field="ip",
        outputs={"ip": ip_address, **results},
        readable_output=tableToMarkdown(f"IP Enrichment: {ip_address}", results)
    ))

def calculate_risk(results):
    score = 0
    if results.get("virustotal", {}).get("malicious", 0) > 3:
        score += 40
    if results.get("abuseipdb", {}).get("abuseConfidenceScore", 0) > 50:
        score += 30
    return min(score, 100)
```

**Key Python APIs:**
- `demisto.executeCommand()` -- Execute integration commands
- `demisto.incidents()` -- Get current incident data
- `demisto.context()` -- Access playbook context
- `return_results()` -- Return structured output
- `CommandResults` -- Structured command output with readable, context, and raw
- `demisto.args()` -- Get task input arguments
- `isError()` -- Check if command execution returned an error

### Incident Lifecycle

```
Alert Ingestion (from SIEM, email, API)
    |
    v
Classification & Mapping
  - Map alert fields to incident fields
  - Set incident type (phishing, malware, brute force, etc.)
  - Assign severity
    |
    v
Pre-processing playbook (automatic)
  - Extract indicators
  - Enrich IOCs
  - Auto-triage
    |
    v
Incident created in XSOAR
    |
    v
Playbook execution (manual or automatic)
  - Enrichment
  - Investigation
  - Containment
  - Remediation
    |
    v
War Room (collaborative investigation)
  - Analyst notes, command execution, evidence
    |
    v
Close incident (with resolution, notes, lessons learned)
```

### Indicator Management (TIM)

XSOAR's Threat Intelligence Management:

- **Indicator types** -- IP, domain, URL, file hash, email, CIDR, custom
- **Indicator lifecycle** -- Active, expired, revoked, manual review
- **Reputation scoring** -- Aggregated score from multiple TI sources
- **TI feeds** -- Ingest from TAXII, CSV, JSON, API feeds
- **Exclusion lists** -- Prevent false-positive indicators from triggering
- **Relationships** -- Link indicators to incidents, campaigns, threat actors
- **Expiration** -- Auto-expire indicators after configurable TTL

### Integration Development

Custom integrations follow a standard pattern:

```python
# Integration module structure
class Client(BaseClient):
    def __init__(self, base_url, api_key, verify=True, proxy=False):
        super().__init__(base_url=base_url, verify=verify, proxy=proxy)
        self.api_key = api_key

    def get_threat_data(self, indicator):
        return self._http_request(
            method='GET',
            url_suffix=f'/api/v1/lookup/{indicator}',
            headers={'Authorization': f'Bearer {self.api_key}'}
        )

def lookup_command(client, args):
    indicator = args.get('indicator')
    result = client.get_threat_data(indicator)
    return CommandResults(
        outputs_prefix='ThreatLookup',
        outputs_key_field='indicator',
        outputs=result,
        readable_output=tableToMarkdown('Threat Lookup', result)
    )

def main():
    params = demisto.params()
    client = Client(
        base_url=params.get('url'),
        api_key=params.get('api_key'),
        verify=not params.get('insecure', False),
        proxy=params.get('proxy', False)
    )

    command = demisto.command()
    if command == 'test-module':
        return_results('ok')
    elif command == 'threat-lookup':
        return_results(lookup_command(client, demisto.args()))

if __name__ in ('__main__', '__builtin__', 'builtins'):
    main()
```

### Content Packs

Pre-built automation packages from the marketplace:

| Pack | Content | Use Case |
|---|---|---|
| **Phishing** | Playbooks, scripts for email triage | Automated phishing response |
| **Malware** | File analysis, sandbox detonation | Malware investigation |
| **Access Investigation** | Login anomaly triage | Suspicious access investigation |
| **Endpoint Enrichment** | Host context gathering | Asset enrichment |
| **Threat Intelligence Management** | Feed aggregation, indicator management | TI operations |
| **MITRE ATT&CK** | Technique mapping, coverage analysis | ATT&CK integration |
| **Case Management** | Incident workflow, SLA tracking | SOC operations |

## Common Pitfalls

1. **Playbook complexity** -- Over-engineering playbooks with too many branches. Start simple, iterate.
2. **Context data overflow** -- Storing too much data in incident context slows down XSOAR. Use `extend-context` judiciously and clean up context.
3. **Integration rate limits** -- Many TI APIs have rate limits. Build rate limiting into enrichment playbooks.
4. **Error handling gaps** -- Playbooks without error handling fail silently. Always add on-error branches for critical tasks.
5. **Hardcoded values** -- Use XSOAR lists and integration instances instead of hardcoded IPs, URLs, or credentials.
6. **Testing in production** -- Always test playbooks with test incidents before enabling for production alerts.