# kaushalrog/atomic-red-team architecture

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

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

## Overview

Atomic Red Team is a library of portable security tests mapped to MITRE ATT&CK. The main workflow is to choose a technique and atomic test, run its documented command directly on a target environment, and observe the resulting behavior for security testing. The repository also has a Ruby library for discovering and validating test definitions, plus Python runtime modules indicated by the tree. The README establishes direct execution; sampled source shows individual test implementations. The excerpts do not establish how the Python modules are wired into execution.

Main entry points: [`atomics`](https://github.com/kaushalrog/atomic-red-team/tree/master/atomics) (Atomic definitions), [`atomic_red_team/atomic_red_team.rb`](https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/atomic_red_team.rb) (Atomic test API), [`atomic_red_team/runner.py`](https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/runner.py) (Execution runner), [`atomics/T1071/src`](https://github.com/kaushalrog/atomic-red-team/tree/master/atomics/T1071/src) (Test implementations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Test catalog"]
  node_definitions["Atomic definitions"]
  node_implementations["Test implementations"]
end

subgraph group_library["Library API"]
  node_ruby_api["Atomic test API<br/>[atomic_red_team.rb]"]
  node_attack_api["ATT&amp;CK API<br/>[attack_api.rb]"]
  node_models["Test models<br/>[models.py]"]
  node_validator["Definition validator<br/>[validator.py]"]
end

subgraph group_runtime["Test execution"]
  node_runner["Execution runner<br/>[runner.py]"]
end

node_team(("Security team"))
node_attack["MITRE ATT&amp;CK"]
node_host["Test environment"]
node_observations["Security observations"]

node_team -->|"selects test"| node_definitions
node_definitions -->|"maps techniques"| node_attack
node_ruby_api -->|"discovers tests"| node_definitions
node_ruby_api -->|"resolves techniques"| node_attack_api
node_validator -->|"validates metadata"| node_definitions
node_team -->|"runs directly"| node_runner
node_runner -->|"executes tests"| node_host
node_implementations -->|"produce behavior"| node_host
node_host -->|"exposes behavior"| node_observations

click node_definitions "https://github.com/kaushalrog/atomic-red-team/tree/master/atomics"
click node_implementations "https://github.com/kaushalrog/atomic-red-team/tree/master/atomics/T1071/src"
click node_ruby_api "https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/atomic_red_team.rb"
click node_attack_api "https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/attack_api.rb"
click node_models "https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/models.py"
click node_validator "https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/validator.py"
click node_runner "https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/runner.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_definitions,node_implementations toneBlue
class node_ruby_api,node_attack_api,node_models,node_validator toneAmber
class node_runner toneMint
class node_team,node_attack,node_host,node_observations toneIndigo
```

## Components

### Test catalog

- [Atomic definitions](https://github.com/kaushalrog/atomic-red-team/tree/master/atomics): `atomics`
- [Test implementations](https://github.com/kaushalrog/atomic-red-team/tree/master/atomics/T1071/src): `atomics/T1071/src`

### Library API

- [Atomic test API](https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/atomic_red_team.rb): `atomic_red_team/atomic_red_team.rb`
- [ATT&CK API](https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/attack_api.rb): `atomic_red_team/attack_api.rb`
- [Test models](https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/models.py): `atomic_red_team/models.py`
- [Definition validator](https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/validator.py): `atomic_red_team/validator.py`

### Test execution

- [Execution runner](https://github.com/kaushalrog/atomic-red-team/blob/master/atomic_red_team/runner.py): `atomic_red_team/runner.py`

### Other components

- **Security team**
- **MITRE ATT&CK**
- **Test environment**
- **Security observations**

## Connections

- Security team → Atomic definitions: selects test
- Atomic definitions → MITRE ATT&CK: maps techniques
- Atomic test API → Atomic definitions: discovers tests
- Atomic test API → ATT&CK API: resolves techniques
- Definition validator → Atomic definitions: validates metadata
- Security team → Execution runner: runs directly
- Execution runner → Test environment: executes tests
- Test implementations → Test environment: produce behavior
- Test environment → Security observations: exposes behavior