# datadog/stratus-red-team architecture

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

- Interactive diagram: https://gitdiagram.com/datadog/stratus-red-team
- Repository: https://github.com/datadog/stratus-red-team

## Overview

1. **What this repo is**
   - Stratus Red Team is a Go-based adversary-emulation framework.
   - The repository is organized around a single CLI and library that execute “attack techniques” against cloud/Kubernetes environments in a repeatable, self-contained way.

2. **Primary entrypoint and user-facing surface**
   - The current production code lives under `v2/`.
   - `v2/cmd/stratus` is the CLI entrypoint, with commands for the main lifecycle: `list`, `show`, `detonate`, `warmup`, `status`, `revert`, `cleanup`, and `version`.
   - These commands are the top boundary between the user and the execution engine.

3. **Core framework library**
   - `v2/pkg/stratus` is the central framework layer used by the CLI and by external Go consumers.
   - It contains the technique model, registry, platform abstractions, config loading/validation, runner orchestration, MITRE ATT&CK metadata, and user-agent handling.
   - This is the main “control plane” for selecting a technique, validating parameters, and dispatching execution.

4. **Attack-technique catalog**
   - Technique implementations live under `v2/internal/attacktechniques/`, grouped first by provider or platform (`aws`, `azure`, `gcp`, `eks`, `k8s`, `entra-id`) and then by ATT&CK category.
   - Each technique is a self-contained unit, usually with a `main.go` and a `main.tf`; some include supporting artifacts like shell scripts, JSON policies, keys, or certificates.
   - Conceptually, each directory is a bounded scenario: technique logic plus the infrastructure needed to detonate and revert it.

5. **Provider and platform boundaries**
   - `v2/internal/providers` defines provider-specific behavior for AWS, Azure, GCP, EKS, Kubernetes, and Entra ID.
   - These providers are the bridge between the generic framework and cloud-specific APIs, permissions, and execution patterns.
   - The same framework can therefore drive multiple control planes while keeping technique definitions provider-scoped.

6. **Execution engine and Terraform coupling**
   - `v2/pkg/stratus/runner` and `v2/pkg/stratus/runner/terraform.go` orchestrate technique execution through Terraform-based infrastructure changes.
   - The repo’s model is not “call an API and stop”; it typically provisions or modifies resources, executes the attack action, and then supports teardown/reversion.
   - This is the main data flow: CLI request → framework lookup/config → runner → Terraform/provider actions → cloud side effects.

7. **State management and lifecycle tracking**
   - `v2/internal/state` manages persisted state for detonations, including local/S3-backed state handling and correlation data.
   - State enables commands like `status`, `revert`, and `cleanup` to understand what was created and how to undo it.
   - This is a key architectural boundary: execution is not stateless; each detonation produces tracked state that downstream commands consume.

8. **Configuration and substitution**
   - `v2/pkg/stratus/config` owns configuration loading, schema, validation, substitutions, and Kubernetes-specific config handling.
   - Configuration ties together provider credentials, technique parameters, and runtime options, and is validated before execution.
   - This layer sits between user intent and the runner, ensuring techniques receive normalized inputs.

9. **Documentation and generated catalog**
   - `docs/` contains the published user guide and the per-technique reference pages.
   - `v2/tools` generates technique docs, coverage matrices, indexes, and YAML/Markdown artifacts from the technique registry.
   - The docs are not just prose; they are generated from the technique catalog, so the documentation pipeline is part of the repository’s architecture.

10. **Examples and embedding use cases**
   - `examples/` demonstrates programmatic usage of the library and custom technique expansion.
   - These examples show the framework can be consumed as an embedded Go library, not only as a standalone CLI.

11. **Distribution and release boundary**
   - The repo ships as a Go binary, a Docker image, and a Homebrew formula.
   - Release and CI/CD are handled through GitHub Actions plus GoReleaser, which produce binaries and package artifacts from the same source tree.
   - That means the build/release pipeline is a real part of the system boundary, not just repository maintenance.

12. **Operational outputs**
   - `docs/detonation-logs/` stores sample logs from successful runs, which serve as reference outputs for techniques and detection validation.
   - These artifacts reflect the intended feedback loop: execute technique, observe resulting cloud activity, and use the emitted evidence for validation.

13. **High-level diagram shape**
   - A useful architecture diagram should center on: user/CLI → framework/config/registry → runner/Terraform → cloud providers/services.
   - Surround that with state persistence for lifecycle operations, technique modules as pluggable units, and generated docs/examples/release tooling as supporting subsystems.

Main entry points: [`v2/pkg/stratus/registry.go`](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/registry.go) (Registry), [`v2/pkg/stratus/runner/terraform.go`](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/runner/terraform.go) (Terraform bridge), [`v2/pkg/stratus/framework.go`](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/framework.go) (Framework), [`v2/pkg/stratus/runner/runner.go`](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/runner/runner.go) (Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_root["stratus CLI<br/>command-line entrypoint<br/>[main.go]"]
  node_cli_commands["Lifecycle cmds<br/>command set<br/>[root.go]"]
end

subgraph group_framework["Core framework"]
  node_framework_core["Framework<br/>control plane<br/>[framework.go]"]
  node_registry["Registry<br/>technique catalog<br/>[registry.go]"]
  node_config["Config<br/>validation and substitution<br/>[config.go]"]
  node_runner["Runner<br/>execution orchestrator<br/>[runner.go]"]
  node_terraform_runner["Terraform bridge<br/>terraform orchestration<br/>[terraform.go]"]
end

subgraph group_techniques["Attack techniques"]
  node_aws_tech["AWS techniques<br/>technique family"]
  node_azure_tech["Azure techniques<br/>technique family"]
  node_gcp_tech["GCP techniques<br/>technique family"]
  node_eks_tech["EKS techniques<br/>technique family"]
  node_k8s_tech["K8s techniques<br/>technique family"]
  node_entra_tech["Entra ID techniques<br/>technique family"]
end

subgraph group_providers["Providers"]
  node_aws_provider["AWS provider<br/>cloud provider adapter<br/>[aws.go]"]
  node_azure_provider["Azure provider<br/>cloud provider adapter<br/>[azure.go]"]
  node_gcp_provider["GCP provider<br/>cloud provider adapter<br/>[gcp.go]"]
  node_eks_provider["EKS provider<br/>platform adapter<br/>[eks.go]"]
  node_k8s_provider["K8s provider<br/>platform adapter<br/>[kubernetes.go]"]
  node_entra_provider["Entra provider<br/>identity adapter<br/>[entra_id.go]"]
end

subgraph group_state["State"]
  node_state_mgr[("State store<br/>persistent state<br/>[state.go]")]
end

subgraph group_support["Supporting systems"]
  node_docs_tools["Docs generator<br/>documentation pipeline<br/>[generate-docs.go]"]
  node_examples["Examples<br/>embedded usage<br/>[README.md]"]
  node_release["Release pipeline<br/>build and distribution<br/>[.goreleaser.yaml]"]
end

node_cli_root -->|"dispatches"| node_cli_commands
node_cli_commands -->|"invokes"| node_framework_core
node_framework_core -->|"loads"| node_config
node_framework_core -->|"resolves"| node_registry
node_framework_core -->|"orchestrates"| node_runner
node_runner -->|"delegates"| node_terraform_runner
node_runner -->|"persists"| node_state_mgr
node_terraform_runner -->|"uses"| node_aws_provider
node_terraform_runner -->|"uses"| node_azure_provider
node_terraform_runner -->|"uses"| node_gcp_provider
node_terraform_runner -->|"uses"| node_eks_provider
node_terraform_runner -->|"uses"| node_k8s_provider
node_terraform_runner -->|"uses"| node_entra_provider
node_registry -->|"catalogs"| node_aws_tech
node_registry -->|"catalogs"| node_azure_tech
node_registry -->|"catalogs"| node_gcp_tech
node_registry -->|"catalogs"| node_eks_tech
node_registry -->|"catalogs"| node_k8s_tech
node_registry -->|"catalogs"| node_entra_tech
node_aws_tech -.->|"binds"| node_aws_provider
node_azure_tech -.->|"binds"| node_azure_provider
node_gcp_tech -.->|"binds"| node_gcp_provider
node_eks_tech -.->|"binds"| node_eks_provider
node_k8s_tech -.->|"binds"| node_k8s_provider
node_entra_tech -.->|"binds"| node_entra_provider
node_docs_tools -->|"generates from"| node_registry
node_examples -.->|"consumes"| node_framework_core
node_release -->|"packages"| node_cli_root
node_release -.->|"publishes"| node_docs_tools

click node_cli_root "https://github.com/datadog/stratus-red-team/blob/main/v2/cmd/stratus/main.go"
click node_cli_commands "https://github.com/datadog/stratus-red-team/blob/main/v2/cmd/stratus/cmd/root.go"
click node_framework_core "https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/framework.go"
click node_registry "https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/registry.go"
click node_config "https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/config/config.go"
click node_runner "https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/runner/runner.go"
click node_terraform_runner "https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/runner/terraform.go"
click node_state_mgr "https://github.com/datadog/stratus-red-team/blob/main/v2/internal/state/state.go"
click node_aws_tech "https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/aws"
click node_azure_tech "https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/azure"
click node_gcp_tech "https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/gcp"
click node_eks_tech "https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/eks"
click node_k8s_tech "https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/k8s"
click node_entra_tech "https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/entra-id"
click node_aws_provider "https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/aws.go"
click node_azure_provider "https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/azure.go"
click node_gcp_provider "https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/gcp.go"
click node_eks_provider "https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/eks.go"
click node_k8s_provider "https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/kubernetes.go"
click node_entra_provider "https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/entra_id.go"
click node_docs_tools "https://github.com/datadog/stratus-red-team/blob/main/v2/tools/generate-docs.go"
click node_examples "https://github.com/datadog/stratus-red-team/blob/main/examples/README.md"
click node_release "https://github.com/datadog/stratus-red-team/blob/main/.goreleaser.yaml"

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_cli_root,node_cli_commands toneBlue
class node_framework_core,node_registry,node_config,node_runner,node_terraform_runner toneAmber
class node_aws_tech,node_azure_tech,node_gcp_tech,node_eks_tech,node_k8s_tech,node_entra_tech toneMint
class node_aws_provider,node_azure_provider,node_gcp_provider,node_eks_provider,node_k8s_provider,node_entra_provider toneRose
class node_state_mgr toneIndigo
class node_docs_tools,node_examples,node_release toneTeal
```

## Components

### CLI

User-facing command entrypoint and lifecycle commands.

- [stratus CLI](https://github.com/datadog/stratus-red-team/blob/main/v2/cmd/stratus/main.go): command-line entrypoint · Top-level Go CLI that exposes list, show, detonate, warmup, status, revert, cleanup, and version. · `v2/cmd/stratus/main.go`
- [Lifecycle cmds](https://github.com/datadog/stratus-red-team/blob/main/v2/cmd/stratus/cmd/root.go): command set · Concrete CLI subcommands for inspection, execution, and teardown. · `v2/cmd/stratus/cmd/root.go`

### Core framework

Shared library for technique selection, config, registry, and execution orchestration.

- [Framework](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/framework.go): control plane · Central library used by the CLI and external Go consumers. · `v2/pkg/stratus/framework.go`
- [Registry](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/registry.go): technique catalog · Registers and resolves available attack techniques. · `v2/pkg/stratus/registry.go`
- [Config](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/config/config.go): validation and substitution · Loads, normalizes, validates, and substitutes runtime configuration. · `v2/pkg/stratus/config/config.go`
- [Runner](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/runner/runner.go): execution orchestrator · Coordinates detonation flow and delegates infrastructure changes to Terraform. · `v2/pkg/stratus/runner/runner.go`
- [Terraform bridge](https://github.com/datadog/stratus-red-team/blob/main/v2/pkg/stratus/runner/terraform.go): terraform orchestration · Implements Terraform-backed execution and teardown mechanics. · `v2/pkg/stratus/runner/terraform.go`

### Attack techniques

Pluggable technique catalog organized by provider and ATT&CK tactic.

- [AWS techniques](https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/aws): technique family · AWS attack scenarios grouped by tactic. · `v2/internal/attacktechniques/aws`
- [Azure techniques](https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/azure): technique family · Azure attack scenarios grouped by tactic. · `v2/internal/attacktechniques/azure`
- [GCP techniques](https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/gcp): technique family · GCP attack scenarios grouped by tactic. · `v2/internal/attacktechniques/gcp`
- [EKS techniques](https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/eks): technique family · Amazon EKS attack scenarios. · `v2/internal/attacktechniques/eks`
- [K8s techniques](https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/k8s): technique family · Kubernetes attack scenarios. · `v2/internal/attacktechniques/k8s`
- [Entra ID techniques](https://github.com/datadog/stratus-red-team/tree/main/v2/internal/attacktechniques/entra-id): technique family · Microsoft Entra ID attack scenarios. · `v2/internal/attacktechniques/entra-id`

### Providers

Provider-specific bridges to cloud and Kubernetes control planes.

- [AWS provider](https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/aws.go): cloud provider adapter · Provider-specific behavior for AWS API and permissions boundaries. · `v2/internal/providers/aws.go`
- [Azure provider](https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/azure.go): cloud provider adapter · Provider-specific behavior for Azure API and permissions boundaries. · `v2/internal/providers/azure.go`
- [GCP provider](https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/gcp.go): cloud provider adapter · Provider-specific behavior for Google Cloud API and permissions boundaries. · `v2/internal/providers/gcp.go`
- [EKS provider](https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/eks.go): platform adapter · Provider-specific behavior for EKS control-plane operations. · `v2/internal/providers/eks.go`
- [K8s provider](https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/kubernetes.go): platform adapter · Provider-specific behavior for Kubernetes cluster operations. · `v2/internal/providers/kubernetes.go`
- [Entra provider](https://github.com/datadog/stratus-red-team/blob/main/v2/internal/providers/entra_id.go): identity adapter · Provider-specific behavior for Microsoft Entra ID operations. · `v2/internal/providers/entra_id.go`

### State

Persisted detonation state and correlation data for lifecycle commands.

- [State store](https://github.com/datadog/stratus-red-team/blob/main/v2/internal/state/state.go): persistent state · Persists detonation state and correlation data for later status, revert, and cleanup. · `v2/internal/state/state.go`

### Supporting systems

Documentation, examples, generation, and release tooling.

- [Docs generator](https://github.com/datadog/stratus-red-team/blob/main/v2/tools/generate-docs.go): documentation pipeline · Builds technique pages, indexes, coverage matrices, and YAML/Markdown artifacts. · `v2/tools/generate-docs.go`
- [Examples](https://github.com/datadog/stratus-red-team/blob/main/examples/README.md): embedded usage · Programmatic usage samples and custom expansion examples. · `examples/README.md`
- [Release pipeline](https://github.com/datadog/stratus-red-team/blob/main/.goreleaser.yaml): build and distribution · GitHub Actions, GoReleaser, Docker, and Homebrew packaging boundary. · `.goreleaser.yaml`

## Connections

- stratus CLI → Lifecycle cmds: dispatches · CLI entrypoint routes to subcommands.
- Lifecycle cmds → Framework: invokes · Commands call into the framework layer.
- Framework → Config: loads · Framework normalizes and validates configuration before execution.
- Framework → Registry: resolves · Framework looks up techniques in the registry.
- Framework → Runner: orchestrates · Framework hands selected techniques to the runner.
- Runner → Terraform bridge: delegates · Runner uses Terraform-backed orchestration for provisioning and teardown.
- Runner → State store: persists · Runner records detonation state and correlation data.
- Terraform bridge → AWS provider: uses · Terraform execution may target AWS control-plane actions.
- Terraform bridge → Azure provider: uses · Terraform execution may target Azure control-plane actions.
- Terraform bridge → GCP provider: uses · Terraform execution may target GCP control-plane actions.
- Terraform bridge → EKS provider: uses · Terraform execution may target EKS control-plane actions.
- Terraform bridge → K8s provider: uses · Terraform execution may target Kubernetes control-plane actions.
- Terraform bridge → Entra provider: uses · Terraform execution may target Entra ID control-plane actions.
- Registry → AWS techniques: catalogs · AWS techniques are registered as selectable scenarios.
- Registry → Azure techniques: catalogs · Azure techniques are registered as selectable scenarios.
- Registry → GCP techniques: catalogs · GCP techniques are registered as selectable scenarios.
- Registry → EKS techniques: catalogs · EKS techniques are registered as selectable scenarios.
- Registry → K8s techniques: catalogs · Kubernetes techniques are registered as selectable scenarios.
- Registry → Entra ID techniques: catalogs · Entra ID techniques are registered as selectable scenarios.
- AWS techniques → AWS provider: binds · AWS scenarios depend on the AWS provider boundary.
- Azure techniques → Azure provider: binds · Azure scenarios depend on the Azure provider boundary.
- GCP techniques → GCP provider: binds · GCP scenarios depend on the GCP provider boundary.
- EKS techniques → EKS provider: binds · EKS scenarios depend on the EKS provider boundary.
- K8s techniques → K8s provider: binds · Kubernetes scenarios depend on the Kubernetes provider boundary.
- Entra ID techniques → Entra provider: binds · Entra ID scenarios depend on the identity provider boundary.
- Docs generator → Registry: generates from · Docs tooling derives catalogs and pages from the registry.
- Examples → Framework: consumes · Examples demonstrate embedded Go usage of the framework.
- Release pipeline → stratus CLI: packages · Release tooling ships the CLI binary and artifacts.
- Release pipeline → Docs generator: publishes · Release pipeline includes generated documentation artifacts.
