securityplaybook - Incident Response Playbook Engine

A Go library for managing and executing structured incident response playbooks. Define procedures, track executions, and generate reports.

Features

• Pre-built incident response playbooks (malware, ransomware, phishing, data breach)
• Playbook management with filtering by type and severity
• Step execution engine with timeout support
• Execution tracking and reporting
• Severity and playbook type parsing utilities

Installation

Build from source

git clone https://github.com/hallucinaut/securityplaybook.git
cd securityplaybook
go build -o securityplaybook ./cmd/securityplaybook
sudo mv securityplaybook /usr/local/bin/

Install via Go

go install github.com/hallucinaut/securityplaybook/cmd/securityplaybook@latest

Usage

CLI

# List all available playbooks
securityplaybook list

# Execute a specific playbook
securityplaybook run pb-001

# Show detailed steps for a playbook
securityplaybook steps pb-001

# Generate execution report
securityplaybook report

# Show version
securityplaybook version

Programmatic usage

package main

import (
    "fmt"

    "github.com/hallucinaut/securityplaybook/pkg/playbook"
    "github.com/hallucinaut/securityplaybook/pkg/execute"
)

func main() {
    manager := playbook.NewPlaybookManager()

    common := playbook.CreateCommonPlaybooks()
    for _, pb := range common {
        manager.AddPlaybook(pb)
    }

    // Filter by type
    malware := manager.GetPlaybooksByType(playbook.TypeMalwarePlaybook)
    fmt.Printf("Malware Playbooks: %d\n", len(malware))

    // Execute a playbook
    exec := manager.ExecutePlaybook("pb-001")
    fmt.Printf("Status: %s, Outcome: %s\n", exec.Status, exec.Outcome)

    // Execute steps
    engine := execute.NewExecutionEngine()
    result := engine.ExecuteStep("step-001", "isolate system", 300)
    fmt.Printf("Result: %s\n", result.Status)

    // Generate report
    report := manager.GenerateReport()
    fmt.Println(report)
}

Available Playbooks

ID	Name	Type	Severity	Steps	Est. Time
pb-001	Malware Response	malware	critical	6	2 hours
pb-002	Data Breach Response	data_breach	critical	4	3 hours
pb-003	Ransomware Response	ransomware	critical	4	4 hours
pb-004	Phishing Response	phishing	medium	3	1 hour

Playbook Structure

Each playbook includes:

• Trigger conditions (when to execute)
• Severity level (critical, high, medium, low)
• Steps with action descriptions and optional commands
• Automation flags per step
• Timeout configuration
• Required resources and references

Architecture

securityplaybook/
├── cmd/
│   └── securityplaybook/
│       └── main.go          # CLI entry point
├── pkg/
│   ├── playbook/
│   │   ├── playbook.go      # Playbook definitions and management
│   │   └── playbook_test.go # Unit tests
│   └── execute/
│       ├── execute.go       # Step execution engine
│       └── execute_test.go  # Unit tests
├── go.mod
├── LICENSE
└── README.md

Testing

go test ./...
go test -cover ./...
go test -v ./pkg/playbook -run TestCreateCommonPlaybooks

Use Cases

• SOC operations: execute standardized response procedures
• Incident response: guide responders through complex incidents
• Compliance: document incident handling procedures
• Training: train teams on response procedures
• Automation: automate repeatable response actions

References

• NIST SP 800-61
• SANS Incident Response
• MITRE ATT&CK

License

MIT License - see LICENSE for details.