<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-security-orchestration-playbooks
description: >-
  Design and implement SOAR playbooks for automated incident response. Covers
  playbook architecture, enrichment workflows, containment actions, case management
  integration, and metrics tracking.
domain: cybersecurity
subdomain: blue-team
tags:
  - soar
  - orchestration
  - playbook
  - incident-response
  - automation
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: []
  mitre-attack: []
---

# Implementing Security Orchestration Playbooks

## Overview

Security Orchestration, Automation, and Response (SOAR) playbooks codify incident
response procedures into repeatable, automated workflows. Effective playbooks reduce
mean time to respond (MTTR), ensure consistent handling, and free analysts from
repetitive tasks. This skill covers playbook design, implementation, testing, and
metrics.

## Prerequisites

| Requirement | Install |
|---|---|
| SOAR platform | Splunk SOAR, Cortex XSOAR, Tines, Shuffle |
| SIEM integration | API access for alert ingestion |
| Threat intel APIs | VirusTotal, AbuseIPDB, Shodan |
| Ticketing system | ServiceNow, Jira, TheHive |
| Python 3.10+ | Custom integration scripts |

## Key Concepts

### Playbook Architecture

```
Alert Trigger
    │
    ▼
┌─────────────┐
│   Ingest     │ ── Parse alert, extract IOCs
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Enrich     │ ── Query TI feeds, SIEM context, asset DB
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Decide     │ ── Risk score threshold, auto vs. manual
└──────┬──────┘
       │
   ┌───┴───┐
   ▼       ▼
┌──────┐ ┌──────┐
│ Auto │ │Manual│ ── Analyst review required
│Contain│ │Review│
└──┬───┘ └──┬───┘
   │        │
   ▼        ▼
┌─────────────┐
│   Respond    │ ── Containment, eradication, notification
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Close      │ ── Update case, metrics, lessons learned
└─────────────┘
```

### Phishing Response Playbook

```yaml
name: Phishing Email Response
trigger: Alert from email security gateway
sla: 15 minutes to initial triage

steps:
  - name: Extract IOCs
    action: parse_email
    inputs:
      - sender_address
      - subject
      - urls
      - attachment_hashes
      - reply_to

  - name: Enrich sender
    action: query_threat_intel
    apis:
      - virustotal: lookup sender domain reputation
      - abuseipdb: check sender IP
    output: sender_risk_score

  - name: Enrich URLs
    action: url_analysis
    apis:
      - urlscan.io: submit for scanning
      - virustotal: URL reputation
    output: url_verdicts

  - name: Detonate attachments
    action: sandbox_analysis
    apis:
      - any_run: submit attachment
      - virustotal: hash lookup
    output: attachment_verdict

  - name: Decide severity
    action: risk_calculation
    logic: |
      if sender_risk_score > 70 or any(url_verdicts == "malicious"):
        severity = "high"
        action = "auto_contain"
      else:
        severity = "medium"
        action = "analyst_review"

  - name: Contain (auto)
    condition: action == "auto_contain"
    steps:
      - block_sender: add to email blocklist
      - quarantine: remove email from all recipient mailboxes
      - disable_user: if user clicked link, disable account pending review

  - name: Notify
    action: send_notification
    targets:
      - soc_channel: "#soc-alerts"
      - affected_users: email notification
      - management: if severity == "critical"

  - name: Create case
    action: create_ticket
    platform: thehive
    fields:
      title: "Phishing: {subject}"
      severity: "{severity}"
      iocs: "{extracted_iocs}"
```

### Enrichment Functions

```python
import requests

def enrich_ip(ip: str, api_key: str) -> dict:
    """Enrich an IP address via AbuseIPDB."""
    resp = requests.get(
        "https://api.abuseipdb.com/api/v2/check",
        params={"ipAddress": ip, "maxAgeInDays": 90},
        headers={"Key": api_key, "Accept": "application/json"},
        timeout=10,
    )
    data = resp.json().get("data", {})
    return {
        "ip": ip,
        "abuse_score": data.get("abuseConfidenceScore", 0),
        "country": data.get("countryCode", ""),
        "isp": data.get("isp", ""),
        "total_reports": data.get("totalReports", 0),
    }

def enrich_hash(file_hash: str, api_key: str) -> dict:
    """Enrich a file hash via VirusTotal."""
    resp = requests.get(
        f"https://www.virustotal.com/api/v3/files/{file_hash}",
        headers={"x-apikey": api_key},
        timeout=10,
    )
    data = resp.json().get("data", {}).get("attributes", {})
    stats = data.get("last_analysis_stats", {})
    return {
        "hash": file_hash,
        "malicious": stats.get("malicious", 0),
        "total": sum(stats.values()),
        "detection_names": list(data.get("popular_threat_classification", {}).get("suggested_threat_label", [])),
    }
```

### Playbook Metrics

| Metric | Target | Measurement |
|---|---|---|
| MTTD (Mean Time to Detect) | <5 min | Alert timestamp - event timestamp |
| MTTR (Mean Time to Respond) | <15 min | Containment timestamp - alert timestamp |
| Auto-resolution rate | >60% | Auto-closed / total alerts |
| False positive rate | <10% | FP alerts / total alerts |
| SLA compliance | >95% | Alerts handled within SLA |

## Workflow

1. **Identify use case** — Select high-volume, repeatable alert type
2. **Document manual process** — Map current analyst workflow step-by-step
3. **Design playbook** — Flowchart with decision points and escalation paths
4. **Implement enrichment** — Connect threat intel and context APIs
5. **Implement actions** — Configure containment and notification integrations
6. **Test** — Run playbook against historical alerts
7. **Deploy** — Enable in production with analyst oversight
8. **Measure** — Track MTTR, auto-resolution rate, and FP rate
9. **Iterate** — Tune thresholds and add edge case handling

## Verification

| Check | Method |
|---|---|
| Playbook triggers | Test alert ingestion from SIEM |
| Enrichment working | IOCs return threat intel data |
| Containment actions | Simulated containment executes correctly |
| Case created | Ticket/case appears in case management |
| Metrics tracked | Dashboard shows MTTR and resolution rates |

## References

- [Splunk SOAR Playbook Documentation](https://docs.splunk.com/Documentation/SOAR)
- [XSOAR Playbook Documentation](https://xsoar.pan.dev/docs/playbooks/playbooks)
- [TheHive Project](https://thehive-project.org/)
- [Shuffle SOAR](https://shuffler.io/)
