# fbsamples/caldera-security-tests architecture

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

- Interactive diagram: https://gitdiagram.com/fbsamples/caldera-security-tests
- Repository: https://github.com/fbsamples/caldera-security-tests

## Overview

##### Project type and purpose
- This is a Go-based command-line application (“caldera-security-tests”) whose sole purpose is to automate security regression tests (TTP Runner) against a live MITRE CALDERA instance.
- It is designed to be run locally or inside a CI workflow (GitHub Actions) to routinely validate that known vulnerabilities remain patched.

##### File structure
Top-level directories and files:
- cmd/
– Contains subcommands implemented in Go (testEnv, storedXSSUno, Dos, Tres, config, logging). These map directly to the CLI’s functionality.
- main.go
– Instantiates the root Cobra command and wire-up of subcommands.
- cmd/config/config.yaml
– Default configuration file template (connection info for CALDERA, Docker parameters, etc.).
- magefiles/
– Build and release automation via Mage (compiling, testing, docs generation).
- .github/workflows/
– CI pipelines: SRP (security regression pipeline), semgrep, tests, goreleaser, etc.
- docs/ & images/
- go.mod, go.sum, .goreleaser.yml
– Dependency and release orchestration.

##### Extract architectural insights from the README
- The CLI orchestrates two phases:
a) testEnv       → spin up or tear down an ephemeral CALDERA test environment (e.g., Docker).
b) storedXSS…   → execute one of three automated attack TTPs against the running environment via the CALDERA API.
- Run regularly in a GitHub Actions workflow (srp.yaml) to gate merge commits and open issues on regression.

a. Main components
1) CLI Application (Go binary)
– Subcomponents (modules/packages):
- Root/Cobra & Subcommands (testEnv, storedXSSUno/Dos/Tres, config, logging)
- Config Loader (reads config.yaml)
- Docker/Environment Orchestrator (provisions CALDERA environment)
- TTP Runner (executes stored XSS attacks via HTTP API)
- Logger (structured output to stdout/stderr)
2) External CALDERA Service
– Lives in Docker or remote host; exposes REST API for plugins/TTPs.
3) GitHub Actions CI
– Triggers the CLI periodically or on PR/push; monitors exit codes; creates issues on failures.
4) Build & Release (Mage + goreleaser)
– Automates binary builds, cross-compilation, and GitHub releases.

b. Relationships and interactions
– The CLI’s testEnv command calls into the Docker/Environment Orchestrator to bring up or tear down containers running MITRE CALDERA.
– The storedXSS… commands load TTP definitions and invoke CALDERA’s REST API to run each attack; they consume API responses to detect success/failure.
– The Config Loader feeds connection endpoints and credentials into both Env Orchestrator and TTP Runner.
– GitHub Actions workflows invoke the CLI (via “uses: fbsamples/caldera-security-tests…”) on schedule or events, parse its exit code, and create issues on regressions.
– Magefiles provide a separate build pipeline: compiling the CLI, running unit tests, linting, and packaging.

c. Architectural patterns and principles
– Modular CLI design using Cobra: each command is isolated in its own package.
– Single-responsibility: Env orchestration, TTP execution, config loading, and logging are separate modules.
– Infrastructure as code potential: testEnv could be extended with Terraform or Docker Compose.
– CI/CD integration: clear separation between build (Mage + goreleaser) and test runs (GitHub Actions).

d. Key technologies and libraries
– Go (compiler, modules)
– spf13/cobra (CLI framework)
– YAML (config, GitHub workflows)
– Docker (ephemeral CALDERA environment)
– GitHub Actions (CI workflows)
– Mage + goreleaser (build & release)
– Semgrep, pre-commit hooks (QA gates)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Build & Release Pipeline"
        MG["Magefiles"]:::config
        GR[".goreleaser.yml"]:::config
        HC[".hooks/"]:::config
        MG --> GR
        MG --> HC
    end

    subgraph "CI/CD"
        GH["GitHub Actions Workflows"]:::service
    end

    GH -->|"runs build"| MG
    GH -->|"runs tests & lint"| HC
    GH -->|"invokes CLI"| CLI

    subgraph "CLI Application"
        CLI["Go CLI (caldera-security-tests)"]:::compute
        CLI --> RC["Root Cobra Command"]:::compute
        RC --> CP["CLI Entrypoint (caldera.go)"]:::compute
        CP --> TE["testEnv"]:::compute
        CP --> SX1["storedXSSUno"]:::compute
        CP --> SX2["storedXSSDos"]:::compute
        CP --> SX3["storedXSSTres"]:::compute
        CP --> CFG["Config Loader"]:::config
        CP --> LOG["Logging Module"]:::compute
    end

    CFG -->|"reads"| CFGF["config.yaml"]:::config

    TE -->|"provisions"| DO["Docker Env"]:::compute
    DO -->|"runs"| CAL["CALDERA Instance"]:::service

    SX1 -->|"calls API"| CAL
    SX2 -->|"calls API"| CAL
    SX3 -->|"calls API"| CAL

    CAL -->|"response"| CP
    CP -->|"exit code"| GH

    subgraph "Documentation"
        DOC["docs/dev.md"]:::config
        IMG["images/"]:::config
    end

    click CLI "https://github.com/fbsamples/caldera-security-tests/blob/main/main.go"
    click RC "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/root.go"
    click CP "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/caldera.go"
    click TE "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/testEnv.go"
    click SX1 "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/storedXSSUno.go"
    click SX2 "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/storedXSSDos.go"
    click SX3 "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/storedXSSTres.go"
    click CFGF "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/config/config.yaml"
    click LOG "https://github.com/fbsamples/caldera-security-tests/blob/main/cmd/logging.go"
    click GH "https://github.com/fbsamples/caldera-security-tests/blob/main/.github/workflows/srp.yaml"
    click MG "https://github.com/fbsamples/caldera-security-tests/tree/main/magefiles/"
    click GR "https://github.com/fbsamples/caldera-security-tests/blob/main/.goreleaser.yml"
    click HC "https://github.com/fbsamples/caldera-security-tests/tree/main/.hooks/"
    click DOC "https://github.com/fbsamples/caldera-security-tests/blob/main/docs/dev.md"
    click IMG "https://github.com/fbsamples/caldera-security-tests/tree/main/images/"

    classDef compute fill:#ADD8E6,stroke:#000
    classDef config fill:#90EE90,stroke:#000
    classDef service fill:#FFA500,stroke:#000
```
