# redcanaryco/atomic-red-team architecture

> Architecture diagram of the GitHub repository redcanaryco/atomic-red-team, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redcanaryco/atomic-red-team
- Repository: https://github.com/redcanaryco/atomic-red-team

## Overview

##### Main Components and Their Roles
- Core Library (“atomic_red_team” directory): This contains the heart of the code. Components include:
– atomic_red_team.rb, attack_api.rb, models.py (and similar files): These files compose the domain logic for representing atomic tests and executing them.
– runner.rb and validator.rb: These serve as entry points for running and validating tests.
– tests folder: Contains unit tests ensuring the integrity of the core functionalities.
- Atomics Test Repository (“atomics” directory):
– Organized into subdirectories for individual MITRE techniques (e.g., T1001.002, T1003.001, etc.). Each folder generally contains corresponding Markdown and YAML files that define the test details.
– Indexes and matrices: Under atomics/Indexes, the content (CSV, Markdown, JSON, YAML) acts as a mapping layer to the MITRE ATT&CK framework.
- Build, Packaging, and Deployment:
– Gemfile and atomic-red-team.gemspec indicate a Ruby gem packaging setup.
– .devcontainer, GitHub workflows (.github/workflows) and configuration files (e.g., .gitignore, LICENSE.txt, CODE_OF_CONDUCT.md) support containerized development and continuous integration.
– The bin directory contains scripts (like generate-atomic-docs.rb and new-atomic.rb) to automate documentation generation and new test creation.
- Additional Tooling:
– Python configuration (pyproject.toml) and other language-specific resources suggest interoperability. Static documentation resources are in the “static” folder.

##### Interactions and Data Flow
- The “runner” component (runner.rb) interacts with the test definitions found in the “atomics” folder. It uses the core library code (and potentially the attack_api, models, and common functions) to parse and execute atomic tests.
- The workflow for test validation and document generation is automated through CI/CD pipelines (GitHub workflows) that pick up changes in both the core library and test files.
- The bin scripts and devcontainer settings assist in setting up development environments and automating documentation builds.
- The indexes are used to provide an entry point (e.g., for navigation or mapping) to the bulk repository of tests and to correlate atomic tests with MITRE ATT&CK techniques.

##### Architectural Patterns and Design Principles
- Modular Design: The separation between the core library (atomic_red_team) and the test repository (atomics) promotes a plug-in like, extensible design.
- Test-Driven Development: The “tests” subdirectory indicates that unit and validation tests are integral to the project.
- Code Reusability: The structure supports adding atomic tests as new modules/directories (each atomic technique gets its own directory with MD/YAML definitions) without changing the core engine.
- Continuous Integration: The presence of GitHub workflows points to automated testing, validation, and documentation generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Atomic Engine Core
    subgraph "Atomic Engine Core"
        A1["atomic_red_team.rb"]:::core
        A2["attack_api.rb"]:::core
        A3["models.py"]:::core
        A4["Test Runner (runner.rb)"]:::core
        A5["Validator (validator.rb)"]:::core
        A6["Unit Tests (tests)"]:::core
    end

    %% Atomic Test Definitions
    subgraph "Atomic Test Definitions"
        B1["Atomic Definitions (atomics/)"]:::repo
        B2["Indexes (atomics/Indexes)"]:::repo
    end

    %% CI/CD & Build/Packaging Tools
    subgraph "CI/CD & Build/Packaging"
        C1["Gem Packaging (Gemfile & Gemspec)"]:::cicd
        C2["GitHub Workflows"]:::cicd
        C3[".devcontainer"]:::cicd
        C4["Bin Scripts"]:::cicd
    end

    %% Supporting Assets & Documentation
    subgraph "Supporting Assets & Documentation"
        D1["Static Assets (static)"]:::assets
        D2["Documentation & Config Files (README, LICENSE, CODE_OF_CONDUCT, .gitignore)"]:::assets
    end

    %% Relationships within Atomic Engine Core
    A1 -->|"logic"| A4
    A2 -->|"logic"| A4
    A3 -->|"logic"| A4

    %% Relationship: Test Runner fetches atomic definitions
    A4 -->|"fetches_tests"| B1

    %% Relationship: Atomic Definitions mapping to Indexes
    B1 -->|"maps_to"| B2

    %% Relationship: Unit Tests and Validator send results to CI/CD workflows
    A6 -->|"run_tests"| C2
    A5 -->|"validate"| C2

    %% CI/CD workflows trigger documentation generation via Bin Scripts
    C2 -->|"trigger_docs"| C4
    C4 -->|"generate_docs"| D2

    %% Bin Scripts also include static assets for documentation
    C4 -->|"include_assets"| D1

    %% Additional CI/CD interactions
    C1 -->|"packaging"| C2
    C3 -->|"dev_setup"| C2

    %% Indexes contribute to documentation mapping
    B2 -->|"mapping"| D2

    %% Click Events for Atomic Engine Core
    click A1 "https://github.com/redcanaryco/atomic-red-team/blob/master/atomic_red_team/atomic_red_team.rb"
    click A2 "https://github.com/redcanaryco/atomic-red-team/blob/master/atomic_red_team/attack_api.rb"
    click A3 "https://github.com/redcanaryco/atomic-red-team/blob/master/atomic_red_team/models.py"
    click A4 "https://github.com/redcanaryco/atomic-red-team/blob/master/atomic_red_team/runner.rb"
    click A5 "https://github.com/redcanaryco/atomic-red-team/blob/master/atomic_red_team/validator.rb"
    click A6 "https://github.com/redcanaryco/atomic-red-team/tree/master/atomic_red_team/tests"

    %% Click Events for Atomic Test Definitions
    click B1 "https://github.com/redcanaryco/atomic-red-team/tree/master/atomics/"
    click B2 "https://github.com/redcanaryco/atomic-red-team/tree/master/atomics/Indexes"

    %% Click Events for CI/CD & Build/Packaging
    click C1 "https://github.com/redcanaryco/atomic-red-team/tree/master/Gemfile"
    click C2 "https://github.com/redcanaryco/atomic-red-team/tree/master/.github/workflows"
    click C3 "https://github.com/redcanaryco/atomic-red-team/blob/master/.devcontainer"
    click C4 "https://github.com/redcanaryco/atomic-red-team/tree/master/bin"

    %% Click Events for Supporting Assets & Documentation
    click D1 "https://github.com/redcanaryco/atomic-red-team/tree/master/static"
    click D2 "https://github.com/redcanaryco/atomic-red-team/blob/master/README.md"

    %% Class styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef repo fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef cicd fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef assets fill:#FFB6C1,stroke:#000,stroke-width:1px;
```
