XSOAR Engineer cheat sheet

Core components: the application server (server + content engine), the PostgreSQL database, and the message broker (RabbitMQ) that carries work between server and engine workers.

Deployment topologies: single-server (all-in-one), multi-server (separate app server, database, and engine/Elasticsearch hosts), and the distributed engine model where engines run in remote/isolated networks and connect back to the server.

Elasticsearch/OpenSearch stores investigation and incident search indexes; if it is down, incident search and indexing fail even though the UI may still load.

The database stores configuration, incidents, and content metadata; it is the stateful component that must be backed up and sized for growth, unlike stateless engine workers.

Engine workers (docker-based in distributed engine) execute integrations and scripts; a playbook task that never starts usually indicates no engine is available or registered.

High availability requires an external load balancer in front of multiple app servers plus a highly available database and broker; the built-in single-node setup is not HA.

Ports and connectivity: HTTPS to the server UI/API, database port to PostgreSQL, broker port to RabbitMQ, and engine-to-server connectivity for distributed engines; TLS should terminate correctly at each hop.

Content packs (Marketplace content) are installed into the server and surfaced as integrations, playbooks, scripts, and layouts; pack version and server version must be compatible.

Sizing depends on incident volume, playbook concurrency, and integration call volume; undersized engines cause task queueing and timeouts under load.

Playbook tasks are typed: standard (run a command/script/integration), condition, manual, and built-in tasks such as 'collect' or 'task completed'; choose the type based on whether branching or human input is needed.

Task inputs map to command arguments; outputs are referenced as ${TaskName.FieldName} or via context paths like ${incident.details}, so field naming must match the integration's command outputs.

Conditional tasks use filters (AND/OR groups) over context keys; a misconfigured filter silently routes down the wrong branch, so test both paths.

Integrations are YAML-defined: a definition file declares commands, arguments, and outputs, while the Python code implements the commands; outputs must be declared or they will not be mapped to context.

Scripts run in the server/engine Python runtime; use demisto.results(), return_results(), and return_error() appropriately, and avoid blocking calls that exceed the script timeout.

Use CommonServerPython helper classes (BaseClient, CommandResults) to standardize HTTP calls, error handling, and output formatting across integrations.

Incident fields and custom fields are defined in the incident field schema; playbook and layout references to a field must use the exact machine name, not the display label.

Layouts control what analysts see on an incident; playbook tasks can update fields and layouts, so field updates must align with the layout's bound fields.

Content is versioned in packs; use the pack structure (metadata, integrations, playbooks, scripts, layouts) and test changes in a non-production tenant before promoting.

Incidents have a type, severity, and status lifecycle; statuses such as New, In Progress, Pending, and Closed drive dashboards and SLA reporting.

Incident types map to dedicated layouts and playbooks; creating an incident with the wrong type skips the intended playbook and shows the wrong fields.

Deduplication and grouping rules prevent duplicate incidents; a grouping rule that is too broad merges unrelated alerts, while too narrow creates noise.

Classification and mapping (incoming fetch mapping) translate raw alert fields into incident fields; a missing mapping leaves fields empty and breaks downstream conditions.

Playbook triggers can be automatic (on creation) or manual; automatic triggers require the incident type to match the playbook's configured trigger.

SLA and timers track time-to-detect and time-to-respond; timers are configured per incident field or playbook and pause/resume based on defined conditions.

Closing an incident can run a closing playbook; ensure close reasons and required fields are set so reports and audits are accurate.

War Room entries capture analyst notes, task outputs, and evidence; entries are searchable and are the audit trail for the case.

Playbook orchestration chains integrations, scripts, and manual approvals; each task's success/failure path determines whether the workflow continues or branches to error handling.

Use the built-in 'generic' tasks and error-handling branches to catch task failures; an unhandled failure can halt the playbook silently.

Commands return structured outputs; map them to context using the task's output configuration, and reference them downstream with the exact context path.

Automation can be scheduled via jobs (time-based) or triggered by incident events; jobs run scripts/integrations on a schedule and are useful for enrichment and housekeeping.

Indicator enrichment and reputation commands (e.g., IP, domain, file, URL) feed indicator scoring; scores drive whether indicators are marked malicious or benign.

Playbook loops and iteration tasks process lists of indicators or alerts; guard against infinite loops by bounding the list and using condition-based exit.

Idempotency matters: automations may retry, so scripts should check whether an action (comment, ticket, containment) was already performed.

Use the API/CLI and integration commands to orchestrate external tools (EDR, SIEM, ticketing); failures should be logged and surfaced to the analyst, not swallowed.

First triage: check server health, engine availability, database connectivity, and broker status; a single failed dependency often explains many symptoms.

Playbook task stuck in 'Waiting' or 'In Progress': verify an engine is registered and free, the task's integration is enabled, and the command is not timing out.

Integration command fails: check instance configuration (credentials, URL, proxy), then test the command directly in the integration's command tester to isolate the failure.

Context/output missing: confirm the integration declares outputs, the task maps them, and the downstream reference uses the exact path; typos yield empty values, not errors.

Database growth and performance: monitor table size and slow queries; large incident/context tables slow search and dashboards and require archival or cleanup.

Backups: back up the PostgreSQL database and configuration regularly; test restore procedures, since a backup that cannot be restored is not a backup.

Logs: server logs, engine logs, and integration logs are separate; correlate by timestamp and incident ID when diagnosing cross-component issues.

Upgrades: review release notes and pack compatibility, back up first, and validate playbooks and integrations in a staging environment before production.