How redcanaryco/atomic-red-team works
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.