# mitre/caldera architecture

> Architecture diagram of the GitHub repository mitre/caldera, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mitre/caldera
- Repository: https://github.com/mitre/caldera

## Overview

##### Project’s Type and Purpose
- This is a full-stack cyber security platform designed to automate adversary emulation, assist red-teams, and support incident response.
- The README and file structure make clear that the “core system” is an asynchronous command-and-control server with RESTful API capabilities and a web interface. Additionally, there is a robust plugin system that allows extending functionality (e.g., Atomic, Builder, Magma UI, etc.).

##### File Structure
- Core Application Code (“app” directory): Contains initialization, API endpoints (found in “app/api” and “app/api/v2”), service definitions (in “app/service”), domain objects (in “app/objects” and “app/objects/secondclass”), utility functions, and configuration/version info.
- Frontend and UI Assets: The “templates” directory (for rendering web pages) and “static” directory (with CSS, JavaScript, images, etc.) point to the web interface component. Also, the README describes a VueJS UI bundled via the “--build” flag.
- Plugin System: The “plugins” directory shows many submodules supporting different cyber tools and techniques that integrate with the core system.
- Infrastructure & Configuration: Configuration files (in “conf”), Dockerfile and docker-compose.yml for containerized deployment, and additional build scripts (e.g. pre-commit configs, .dockerignore).
- Tests: Well-organized testing trees under “tests”, signifying a modular, testable design.

a. Primary Components:
- Core Server Engine: This is the asynchronous command-and-control core that handles the main application logic.
- REST API Layer: Present within “app/api” and “app/api/v2”. Each API version has its endpoints, error handling, and schema/validation components.
- Web Interface: Comprised of frontend UI components (templates, static assets) and in the newer build, a VueJS UI (note the Magma submodule and instructions in the README).
- Services Layer: Multiple services (in “app/service” and “app/service/interfaces”) that encapsulate business logic (authentication, file handling, contact handling, data services, etc.).
- Plugin System: A set of directories under “plugins” that can be integrated to extend functionality. Each plugin (e.g., atomic, builder, compass) may have independent workflow and configuration.
- Data Stores & Configuration: “data” directory for runtime artifacts, “conf” for configuration files and SSH keys.
- Auxiliary Components: Utility libraries (found under “app/utility”), Learning and Contacts modules (“app/learning”, “app/contacts”), which indicate how the system may simulate adversary tactics.
- Testing Infrastructure: A separate layered test suite (directories under “tests”) that exercises different parts of the system.

b. Relationships and Interactions:
- The core server (entry point: server.py) orchestrates incoming API calls from the REST API layer, routes them to the appropriate service layer (authentication, planning, etc.), and interacts with the backend modules (managers, handlers).
- API endpoints (v2) interact with managers for business logic and then send responses using standardized response and schema functions.
- The web interface communicates with the API layer, obtaining data and rendering outputs via HTML templates and VueJS-powered UI components.
- Plugin modules are designed to “plug in” to the core and extend functionality dynamically. Communication might occur via defined interfaces, service calls, or REST API remappings.
- External components such as Docker (Dockerfile, docker-compose.yml) encapsulate the application, while external dependencies (such as NodeJS for UI or Go for agent compilation) are managed at deployment.

c. Architectural Patterns and Design Principles:
- Layered Architecture: Clear separation between presentation (UI), application logic (services, API handlers) and data/configuration.
- Plugin/Modular Architecture: Separates core functionality from additional modules (plugins) allowing dynamic extension.
- Asynchronous and Scalable Command-and-Control: Indicates asynchronous processing methods, possibly event-driven handling of remote agents.
- RESTful API Design: Versioned endpoints, error and validation handling.

d. Technologies, Frameworks, and Tools:
- Python 3.9+ is the primary language, with a variety of Python libraries and conventions (e.g., asynchronous processing).
- VueJS is used for the modern UI (as noted in the README and submodule references).
- Docker is supported for both development and production.
- Testing frameworks are implied by the “tests” directory structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client Request"]:::external
    Client -->|"HTTP"| WebInterface

    subgraph "Backend Components"
        CoreEngine["Core Server Engine\n(asynchronous C2)"]:::backend
        RESTAPI["REST API Layer"]:::backend
        APIv2["API v2 (handlers,managers,schemas)"]:::backend
        Services["Service Layer"]:::backend
        Domain["Domain Objects & Logic"]:::backend
        Utility["Utility Libraries"]:::backend
    end

    subgraph "Frontend Components"
        WebInterface["Web Interface"]:::frontend
    end

    subgraph "Extension & Configuration"
        Plugins["Plugin System"]:::plugins
        DataConfig["Data Stores & Configuration"]:::config
    end

    External["External Dependencies\n(Docker,NodeJS,Go)"]:::external

    %% Connections between components
    Client -->|"HTTP"| WebInterface
    WebInterface -->|"APIRequest"| RESTAPI
    CoreEngine -->|"Orchestrates"| RESTAPI
    RESTAPI -->|"includes"| APIv2
    RESTAPI -->|"calls"| Services
    Services -->|"executes"| Domain
    Services -->|"utilizes"| Utility
    CoreEngine -->|"integrates"| Plugins
    DataConfig -->|"supplies"| CoreEngine
    External -->|"deploys"| CoreEngine

    %% Click Events for mapped components
    click CoreEngine "https://github.com/mitre/caldera/blob/master/server.py"
    click CoreEngine "https://github.com/mitre/caldera/blob/master/app/__init__.py"
    click RESTAPI "https://github.com/mitre/caldera/tree/master/app/api"
    click APIv2 "https://github.com/mitre/caldera/tree/master/app/api/v2"
    click WebInterface "https://github.com/mitre/caldera/tree/master/templates"
    click WebInterface "https://github.com/mitre/caldera/tree/master/static"
    click Services "https://github.com/mitre/caldera/tree/master/app/service"
    click Plugins "https://github.com/mitre/caldera/tree/master/plugins"
    click DataConfig "https://github.com/mitre/caldera/tree/master/data"
    click DataConfig "https://github.com/mitre/caldera/tree/master/conf"
    click Utility "https://github.com/mitre/caldera/tree/master/app/utility"
    click Domain "https://github.com/mitre/caldera/tree/master/app/objects"

    %% Styles
    classDef external fill:#ffcc00,stroke:#000,stroke-width:2px;
    classDef backend fill:#cce5ff,stroke:#003366,stroke-width:2px;
    classDef frontend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef plugins fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
