Platform

Python Security Playbooks

Write alert-to-response automation in real Python — not YAML, not drag-and-drop. Use asyncio for parallel execution, pip packages for integrations, and pytest for testing.

Why Python for security playbooks?

Every commercial SOAR platform invents its own way to define playbooks: visual drag-and-drop builders, YAML files, proprietary DSLs. They're easy to demo but painful to work with at scale.

Try implementing retry logic with exponential backoff in a drag-and-drop builder. Or unit testing a YAML playbook. Or reviewing a visual workflow in a pull request. It doesn't work.

Python playbooks give you everything a real programming language provides:

  • Conditional logic — if/elif/else, not a maze of visual branches
  • Error handling — try/except, not silent failures
  • Parallel execution — asyncio.gather(), not "parallel nodes"
  • Testing — pytest, not manual QA
  • Code review — git diffs, not side-by-side screenshots
  • Libraries — any pip package, not just vendor-provided integrations

How OpenSOAR playbooks work

An OpenSOAR playbook is a Python module with decorated functions. The @playbook decorator defines when it triggers. The @action decorator wraps individual steps with tracking, retries, and timeout handling.

Basic playbook

triage_high_severity.py 
from opensoar import playbook, action

@playbook(
    trigger="alert.created",
    condition={"severity": ["high", "critical"]}
)
async def triage_high_severity(alert):
    """Auto-enrich and triage high/critical alerts."""

    # Enrich with threat intelligence
    vt = await lookup_hash(alert.iocs.get("file_hash"))
    abuse = await check_ip(alert.source_ip)

    # Decide based on results
    if vt.malicious and abuse.confidence > 80:
        await isolate_host(alert.host)
        await notify_team(alert, verdict="confirmed_malicious")
    elif vt.malicious or abuse.confidence > 50:
        await escalate(alert, reason="Needs analyst review")
    else:
        await resolve(alert, determination="false_positive")

Parallel enrichment

Need to query multiple threat intel sources? Don't chain them sequentially — run them in parallel with asyncio.gather():

parallel_enrich.py 
import asyncio
from opensoar import playbook

@playbook(trigger="alert.created")
async def parallel_enrich(alert):
    # All three lookups run simultaneously
    vt, abuse, geo = await asyncio.gather(
        lookup_hash(alert.file_hash),
        check_ip(alert.source_ip),
        geolocate(alert.source_ip),
    )

    alert.enrichment = {
        "virustotal": vt.to_dict(),
        "abuseipdb": abuse.to_dict(),
        "geolocation": geo.to_dict(),
    }
    await save_alert(alert)

Human-in-the-loop

Not everything should be fully automated. Use approval gates for high-impact actions:

malware_response.py 
@playbook(trigger="alert.created", condition={"type": "malware"})
async def malware_response(alert):
    vt = await lookup_hash(alert.file_hash)

    if vt.malicious:
        # Auto-contain: low risk, high value
        await quarantine_file(alert.host, alert.file_path)

        # Seek approval for high-impact action
        approved = await request_approval(
            action="isolate_host",
            target=alert.host,
            channel="#security-ops",
            timeout_minutes=30,
        )
        if approved:
            await isolate_host(alert.host)

Testing playbooks

Because playbooks are Python, you test them like any other Python code:

test_triage.py 
import pytest
from playbooks.triage_high_severity import triage_high_severity
from opensoar.testing import MockAlert, mock_action

@pytest.mark.asyncio
async def test_confirmed_malicious_triggers_isolation():
    alert = MockAlert(severity="critical", source_ip="1.2.3.4")

    with mock_action("lookup_hash", returns={"malicious": True}):
        with mock_action("check_ip", returns={"confidence": 90}):
            await triage_high_severity(alert)

    assert alert.status == "resolved"
    assert "isolate_host" in alert.actions_taken

Run your playbook tests in CI. Catch bugs before they hit production. This is how software engineering works — security automation should be no different.

Playbooks as code: the workflow

  1. Write a playbook in your IDE with autocomplete and type checking
  2. Test it locally with pytest and mock data
  3. Review it in a pull request — teammates can read the logic, not decode a visual diagram
  4. Deploy it by merging to main — OpenSOAR hot-reloads playbooks
  5. Monitor execution in the OpenSOAR dashboard — every action is tracked with timing and results

Compare: Python vs visual vs YAML playbooks

Capability Python (OpenSOAR) Visual builder YAML
Complex logic Native Painful Verbose
Parallel execution asyncio.gather() Vendor-specific Limited
Unit testing pytest Manual QA Possible but awkward
Code review Git diffs Screenshots Git diffs
IDE support Full None Schema-based
Custom libraries Any pip package Vendor marketplace Limited
Learning curve Know Python Learn the builder Learn the schema

OpenSOAR is an open-source SOAR platform where playbooks are Python, not proprietary formats. Start building on GitHub →

One command. No credit card.

Apache 2.0 licensed. Self-host on your infrastructure. No feature gates, no per-action billing, no vendor lock-in. Your playbooks are yours.

$curl -fsSL https://opensoar.app/install.sh | sh
GitHub