How datadog/stratus-red-team works
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: registry.go Registry · terraform.go Terraform bridge · framework.go Framework · runner.go Runner
Components 23
CLI
User-facing command entrypoint and lifecycle commands.
- stratus CLI · Top-level Go CLI that exposes list, show, detonate, warmup, status, revert, cleanup, and version.
v2/cmd/stratus/main.go - Lifecycle cmds · 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 · Central library used by the CLI and external Go consumers.
v2/pkg/stratus/framework.go - Registry · Registers and resolves available attack techniques.
v2/pkg/stratus/registry.go - Config · Loads, normalizes, validates, and substitutes runtime configuration.
v2/pkg/stratus/config/config.go - Runner · Coordinates detonation flow and delegates infrastructure changes to Terraform.
v2/pkg/stratus/runner/runner.go - Terraform bridge · 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 · AWS attack scenarios grouped by tactic.
v2/internal/attacktechniques/aws - Azure techniques · Azure attack scenarios grouped by tactic.
v2/internal/attacktechniques/azure - GCP techniques · GCP attack scenarios grouped by tactic.
v2/internal/attacktechniques/gcp - EKS techniques · Amazon EKS attack scenarios.
v2/internal/attacktechniques/eks - K8s techniques · Kubernetes attack scenarios.
v2/internal/attacktechniques/k8s - Entra ID techniques · Microsoft Entra ID attack scenarios.
v2/internal/attacktechniques/entra-id
Providers
Provider-specific bridges to cloud and Kubernetes control planes.
- AWS provider · Provider-specific behavior for AWS API and permissions boundaries.
v2/internal/providers/aws.go - Azure provider · Provider-specific behavior for Azure API and permissions boundaries.
v2/internal/providers/azure.go - GCP provider · Provider-specific behavior for Google Cloud API and permissions boundaries.
v2/internal/providers/gcp.go - EKS provider · Provider-specific behavior for EKS control-plane operations.
v2/internal/providers/eks.go - K8s provider · Provider-specific behavior for Kubernetes cluster operations.
v2/internal/providers/kubernetes.go - Entra provider · 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 · 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 · Builds technique pages, indexes, coverage matrices, and YAML/Markdown artifacts.
v2/tools/generate-docs.go - Examples · Programmatic usage samples and custom expansion examples.
examples/README.md - Release pipeline · GitHub Actions, GoReleaser, Docker, and Homebrew packaging boundary.
.goreleaser.yaml
Connections 29
- 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.