# austinsonger/incident-playbook architecture

> Architecture diagram of the GitHub repository austinsonger/incident-playbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/austinsonger/incident-playbook
- Repository: https://github.com/austinsonger/incident-playbook

## Overview

##### Project Type and Purpose
- This is a documentation/catalog repository rather than a compiled or runtime application. It’s a static “knowledge base” that lives on GitHub.
- Its purpose is to serve the SOC/Incident Response community by providing:
- A catalog of incident response playbooks organized by MITRE ATT&CK techniques
- A catalog of automations, checklists, exercises, battle cards, SIEM event codes, etc.
- Collaboration and CI (e.g., GitHub Actions for spell‐checking and GitLab sync)

##### Main Components
- Content Repository (Git objects + .md files)
- Top‐level folders: Automations, Playbooks, SIEM, Incident-Response, Exercises, Threat-Hunting, etc.
- Each folder contains subfolders and markdown files representing individual playbooks, automations, or checklists.
- Version Control & Hosting
- GitHub (with repository metadata like .github/workflows, README.md, LICENSE)
- GitHub Actions workflows (codespell.yml, gitlabsync.yml)
- Collaboration Channels
- GitHub Issues/Discussions for new playbook requests
- Gitter community chat
- (Optional) Static Site Generator or Markdown Viewer
- GitHub Pages or any chosen SSG that will read the markdown tree and publish it as a documentation site

##### Relationships & Data Flows
- Contributors → push / pull request → GitHub Repository
- On push/PR → GitHub Actions runs:
- Spelling checks
- Sync to GitLab (if configured)
- End user (reader) → browses GitHub UI or static site → reads compiled docs
- Community chat (Gitter) and Discussions → feed issues and feature requests → backlog

##### Architectural Patterns & Design Principles
- Single “monorepo” design for documentation (all content in one Git repo)
- Separation of concerns by directory (each major catalog has its own folder)
- GitOps/CICD for automated quality checks (codespell) and cross-platform sync
- Modular content grouping (MITRE ATT&CK folders, Automations by language/tool, SIEM by platform)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Swimlanes
  subgraph "Content Zone" 
    direction TB
    Repo["GitHub Repository"]:::storage
    subgraph "Content Repository"
      direction TB
      Automations["Automations"]:::storage
      Playbooks["Playbooks"]:::storage
      SIEM["SIEM"]:::storage
      IncidentResponse["Incident-Response"]:::storage
      Exercises["Exercises"]:::storage
      ThreatHunting["Threat-Hunting"]:::storage
      BattleCards["Battle-Cards"]:::storage
      subgraph "Docs & Templates"
        direction TB
        ADSFramework["ADS-Framework.md"]:::storage
        ActionTemplate["Action-Template.md"]:::storage
        MitigationCategories["Mitigation-Categories.md"]:::storage
        PlaybookTemplate["Playbook-Template.md"]:::storage
        DiscoveringRisks["Discovering-Risks.md"]:::storage
        IdentifyingAttacks["Identifying-Attacks"]:::storage
        ThreatCatalogue["Threat_Catalogue.md"]:::storage
        TODO["TO-DO.md"]:::storage
        Responses["Responses.md"]:::storage
        ResponseTemplate["Response_template.yaml"]:::storage
      end
    end
  end

  subgraph "CI/CD Zone"
    direction TB
    Actions["GitHub Actions"]:::process
    Codespell["codespell.yml"]:::process
    GitlabSync["gitlabsync.yml"]:::process
  end

  subgraph "Community Zone"
    direction TB
    Issues["GitHub Issues/Discussions"]:::community
    Gitter["Gitter Chat"]:::community
    Backlog["Feature Backlog"]:::community
  end

  subgraph "Delivery Zone"
    direction TB
    SSG["Static Site Generator\n(GitHub Pages)"]:::delivery
    EndUsers["End Users"]:::delivery
  end

  %% Connections
  Contributors["Contributors"]:::actor -->|push/PR| Repo
  Repo -->|contains| Automations
  Repo -->|contains| Playbooks
  Repo -->|contains| SIEM
  Repo -->|contains| IncidentResponse
  Repo -->|contains| Exercises
  Repo -->|contains| ThreatHunting
  Repo -->|contains| BattleCards
  Repo -->|contains| Docs & Templates
  Repo -->|triggers CI| Actions
  Actions -->|runs codespell| Codespell
  Actions -->|runs gitlabsync| GitlabSync
  Codespell -->|reports| Repo
  GitlabSync -->|syncs| Repo
  Repo -->|publishes| SSG
  SSG -->|serves| EndUsers
  Issues -->|requests| Backlog
  Gitter -->|community input| Backlog
  Backlog -->|leads to| Repo

  %% Click Events
  click Automations "https://github.com/austinsonger/incident-playbook/tree/main/Automations"
  click Playbooks "https://github.com/austinsonger/incident-playbook/tree/main/Playbooks"
  click SIEM "https://github.com/austinsonger/incident-playbook/tree/main/SIEM"
  click IncidentResponse "https://github.com/austinsonger/incident-playbook/tree/main/Incident-Response"
  click Exercises "https://github.com/austinsonger/incident-playbook/tree/main/Exercises"
  click ThreatHunting "https://github.com/austinsonger/incident-playbook/tree/main/Threat-Hunting"
  click BattleCards "https://github.com/austinsonger/incident-playbook/tree/main/Battle-Cards"
  click Codespell "https://github.com/austinsonger/incident-playbook/blob/main/.github/workflows/codespell.yml"
  click GitlabSync "https://github.com/austinsonger/incident-playbook/blob/main/.github/workflows/gitlabsync.yml"
  click ADSFramework "https://github.com/austinsonger/incident-playbook/blob/main/ADS-Framework.md"
  click ActionTemplate "https://github.com/austinsonger/incident-playbook/blob/main/Action-Template.md"
  click MitigationCategories "https://github.com/austinsonger/incident-playbook/blob/main/Mitigation-Categories.md"
  click PlaybookTemplate "https://github.com/austinsonger/incident-playbook/blob/main/Playbook-Template.md"
  click DiscoveringRisks "https://github.com/austinsonger/incident-playbook/blob/main/Discovering-Risks.md"
  click IdentifyingAttacks "https://github.com/austinsonger/incident-playbook/tree/main/Identifying-Attacks"
  click ThreatCatalogue "https://github.com/austinsonger/incident-playbook/blob/main/Threat_Catalogue.md"
  click TODO "https://github.com/austinsonger/incident-playbook/blob/main/TO-DO.md"
  click Responses "https://github.com/austinsonger/incident-playbook/blob/main/Responses.md"
  click ResponseTemplate "https://github.com/austinsonger/incident-playbook/blob/main/Response_template.yaml"
  click Issues "https://github.com/austinsonger/incident-playbook/blob/main/.github/ISSUE_TEMPLATE/new-playbook.md"
  click Issues "https://github.com/austinsonger/incident-playbook/blob/main/.github/ISSUE_TEMPLATE/incident-response-process-suggestion.md"
  click Issues "https://github.com/austinsonger/incident-playbook/blob/main/.github/ISSUE_TEMPLATE/playbook-tuning.md"
  click Issues "https://github.com/austinsonger/incident-playbook/blob/main/.github/ISSUE_TEMPLATE/question.md"

  %% Styles
  classDef storage fill:#f9f,stroke:#333,stroke-width:2px
  classDef process fill:#ff9,stroke:#333,stroke-width:2px
  classDef community fill:#9ff,stroke:#333,stroke-width:2px
  classDef delivery fill:#cfc,stroke:#333,stroke-width:2px
  classDef actor fill:#ccc,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
```
