Playbooks & SOAR Engine

Visual playbook builder, execution engine with conditional branching, parallel steps, approval gates, 10+ action handlers, and 7 demo playbooks.

Overview

The SOAR (Security Orchestration, Automation, and Response) engine provides a complete playbook lifecycle: visual building, template instantiation, version-controlled editing, advanced execution with conditional branching, parallel step groups, approval gates, error handling, and dry-run mode. The production ActionDispatcher in soar_actions.py provides 10 action handlers with retry logic, audit logging, and graceful degradation when external APIs are unavailable.

What Was Proposed

• Visual playbook builder with drag-and-drop step management
• 10+ pre-built playbook templates (phishing, ransomware, malware, brute force, etc.)
• Advanced execution: conditional branching, parallel steps, approval gates, loops
• 10+ SOAR action types with production-quality handlers
• Version tracking with rollback capability
• Execution metrics and per-playbook analytics
• Import/export playbooks as JSON
• Dry-run mode for testing

What's Built

SOAR Action Handlers (soar_actions.py)

All handlers follow a validate -> execute -> (optional rollback) lifecycle. External-facing handlers fall back to dry-run mode when API keys are not configured.

Architecture

PlaybookExecutor.execute_playbook(playbook, trigger_context)
    |
    for each step in playbook.steps:
        |
        +-- type: "action"          -> ActionDispatcher.dispatch(action_type, config, event)
        |                                |-> validate() -> execute() -> ActionResult
        |                                |-> retry on failure (3 attempts, exponential backoff)
        |                                |-> audit log every execution
        |
        +-- type: "condition"       -> evaluate field against operator/value
        |                                |-> on_true: jump to step X
        |                                |-> on_false: jump to step Y
        |
        +-- type: "parallel_group"  -> asyncio.gather(parallel_steps)
        |
        +-- type: "approval_gate"   -> pause execution, wait for human approval
        |                                |-> POST /executions/{id}/gates/{step_id}/approve
        |
        +-- type: "notification"    -> SendNotificationHandler

API Routing

Router prefix: /api/v1/playbooks — Tag: playbooks

Templates

Metrics

Executions (Global)

Builder

CRUD

Versioning & Execution

Prerequisites

• PostgreSQL with playbooks and playbook_executions tables (TenantScopedBase)
• Pydantic schemas in app/schemas/playbook.py
• Tenant middleware for request.state.tenant_id
• External API keys for live SOAR actions (optional -- dry-run fallback available)

Data Model

File: platform/api/app/models/playbook.py

Playbook

Table: playbooks

PlaybookExecution

Table: playbook_executions

UI Description

File: platform/frontend/src/app/playbooks/page.tsx

• Playbook List -- Filterable card grid showing name, trigger type, tags, enabled/disabled toggle, step count, last execution
• Execution History -- Timeline view with step-by-step results, duration per step, status badges (completed/failed/paused), approval gate indicators
• Template Gallery -- Browse 10+ pre-built templates by category, one-click instantiation with customization modal
• Builder View -- Step editor with action type selector, configuration forms, condition builder, parallel group nesting
• Metrics Dashboard -- Overall and per-playbook metrics: total runs, success rate, avg duration, top playbooks chart