# mastermjr/viberange-workshop architecture

> Architecture diagram of the GitHub repository mastermjr/viberange-workshop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mastermjr/viberange-workshop
- Repository: https://github.com/mastermjr/viberange-workshop

## Overview

VibeRange is a reproducible purple-team forensic workshop and isolated cyber-range blueprint. Participants use the experiment CLI to start a bounded run, execute a prepared Caldera attack against a vulnerable Kubernetes target, and investigate independently collected evidence in CH-UI and Jupyter. The map follows the documented stages from range provisioning and attack preparation through telemetry collection, storage, detection, and reporting. Several subsystem links reflect the README’s architecture description; unsampled implementations are represented by their exact enclosing directories.

Main entry points: [`ansible/roles/ludus_clickhouse_ir/files/schema.sql`](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_clickhouse_ir/files/schema.sql) (ClickHouse evidence), [`ansible/roles/ludus_experiment_cli/files/viberange_experiment.py`](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_experiment_cli/files/viberange_experiment.py) (Experiment CLI), [`ansible/roles/ludus_vector_attacker`](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_vector_attacker) (Vector transport), [`ansible/roles/ludus_caldera_server`](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_caldera_server) (Caldera operation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_range["Range and isolation"]
  node_ludus["Ludus range"]
  node_workload["Range workloads"]
end

subgraph group_experiment["Experiment control"]
  node_cli["Experiment CLI"]
  node_runcontrol["Run control<br/>[viberange_run.py]"]
end

subgraph group_collection["Attack and evidence"]
  node_caldera_content["Caldera content"]
  node_caldera["Caldera operation"]
  node_kali["Attacker host"]
  node_kubernetes["Kubernetes target"]
  node_victimtelemetry["Kubernetes telemetry"]
  node_routercapture["Router capture"]
  node_routerfinalize["PCAP and Zeek"]
  node_vector["Vector transport"]
end

subgraph group_analysis["Storage and analysis"]
  node_clickhouse[("ClickHouse evidence<br/>[schema.sql]")]
  node_chui["CH-UI analysis"]
  node_seed["CH-UI content<br/>[seed_ch_ui.py]"]
  node_jupyter["Jupyter analysis"]
end

subgraph group_reporting["Detection and reporting"]
  node_detections["Detection rules"]
  node_detection_runner["Detection runner<br/>[runner.py]"]
  node_receiver["Detection receiver<br/>[receiver.py]"]
  node_notebook["Reconstruction report"]
end

node_participant(("Participant"))

node_participant -->|"controls run"| node_cli
node_ludus -->|"deploys range"| node_workload
node_cli -->|"sets run state"| node_runcontrol
node_cli -->|"starts operation"| node_caldera
node_cli -->|"starts capture"| node_routercapture
node_caldera_content -->|"syncs abilities"| node_caldera
node_caldera -->|"runs on"| node_kali
node_kali -->|"attacks"| node_kubernetes
node_kubernetes -->|"produces evidence"| node_victimtelemetry
node_victimtelemetry -->|"ships telemetry"| node_vector
node_kali -->|"ships audit"| node_vector
node_routercapture -->|"processes capture"| node_routerfinalize
node_routerfinalize -->|"spools Zeek evidence"| node_vector
node_vector -->|"transports records"| node_clickhouse
node_seed -->|"seeds dashboards"| node_chui
node_chui -->|"queries evidence"| node_clickhouse
node_jupyter -->|"reconstructs runs"| node_clickhouse
node_detections -->|"provides rules"| node_detection_runner
node_detection_runner -.->|"queries evidence"| node_clickhouse
node_receiver -->|"stores matches"| node_clickhouse
node_notebook -->|"generates report"| node_jupyter

click node_ludus "https://github.com/mastermjr/viberange-workshop/tree/main/blueprints/viberange"
click node_workload "https://github.com/mastermjr/viberange-workshop/tree/main/templates"
click node_cli "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_experiment_cli/files/viberange_experiment.py"
click node_runcontrol "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_run_control/files/viberange_run.py"
click node_caldera_content "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_caldera_content/files"
click node_caldera "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_caldera_server"
click node_kali "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_vector_attacker"
click node_kubernetes "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_k3s_goat"
click node_victimtelemetry "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_k3s_goat"
click node_routercapture "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_router_evidence"
click node_routerfinalize "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_router_evidence/files/finalize_router_evidence.py"
click node_vector "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_vector_attacker"
click node_clickhouse "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_clickhouse_ir/files/schema.sql"
click node_chui "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_ch_ui"
click node_seed "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_ch_ui/files/seed_ch_ui.py"
click node_jupyter "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_jupyter"
click node_detections "https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_detection_runner/files/rules"
click node_detection_runner "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_detection_runner/files/runner.py"
click node_receiver "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_detection_runner/files/receiver.py"
click node_notebook "https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_jupyter/files/viberange-reconstruction.ipynb"

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_ludus,node_workload toneBlue
class node_cli,node_runcontrol toneAmber
class node_caldera_content,node_caldera,node_kali,node_kubernetes,node_victimtelemetry,node_routercapture,node_routerfinalize,node_vector toneMint
class node_clickhouse,node_chui,node_seed,node_jupyter toneRose
class node_detections,node_detection_runner,node_receiver,node_notebook,node_participant toneIndigo
```

## Components

### Range and isolation

- [Ludus range](https://github.com/mastermjr/viberange-workshop/tree/main/blueprints/viberange): `blueprints/viberange`
- [Range workloads](https://github.com/mastermjr/viberange-workshop/tree/main/templates): `templates`

### Experiment control

- [Experiment CLI](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_experiment_cli/files/viberange_experiment.py): `ansible/roles/ludus_experiment_cli/files/viberange_experiment.py`
- [Run control](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_run_control/files/viberange_run.py): `ansible/roles/ludus_run_control/files/viberange_run.py`

### Attack and evidence

- [Caldera content](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_caldera_content/files): `ansible/roles/ludus_caldera_content/files`
- [Caldera operation](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_caldera_server): `ansible/roles/ludus_caldera_server`
- [Attacker host](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_vector_attacker): `ansible/roles/ludus_vector_attacker`
- [Kubernetes target](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_k3s_goat): `ansible/roles/ludus_k3s_goat`
- [Kubernetes telemetry](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_k3s_goat): `ansible/roles/ludus_k3s_goat`
- [Router capture](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_router_evidence): `ansible/roles/ludus_router_evidence`
- [PCAP and Zeek](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_router_evidence/files/finalize_router_evidence.py): `ansible/roles/ludus_router_evidence/files/finalize_router_evidence.py`
- [Vector transport](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_vector_attacker): `ansible/roles/ludus_vector_attacker`

### Storage and analysis

- [ClickHouse evidence](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_clickhouse_ir/files/schema.sql): `ansible/roles/ludus_clickhouse_ir/files/schema.sql`
- [CH-UI analysis](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_ch_ui): `ansible/roles/ludus_ch_ui`
- [CH-UI content](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_ch_ui/files/seed_ch_ui.py): `ansible/roles/ludus_ch_ui/files/seed_ch_ui.py`
- [Jupyter analysis](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_jupyter): `ansible/roles/ludus_jupyter`

### Detection and reporting

- [Detection rules](https://github.com/mastermjr/viberange-workshop/tree/main/ansible/roles/ludus_detection_runner/files/rules): `ansible/roles/ludus_detection_runner/files/rules`
- [Detection runner](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_detection_runner/files/runner.py): `ansible/roles/ludus_detection_runner/files/runner.py`
- [Detection receiver](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_detection_runner/files/receiver.py): `ansible/roles/ludus_detection_runner/files/receiver.py`
- [Reconstruction report](https://github.com/mastermjr/viberange-workshop/blob/main/ansible/roles/ludus_jupyter/files/viberange-reconstruction.ipynb): `ansible/roles/ludus_jupyter/files/viberange-reconstruction.ipynb`

### Other components

- **Participant**

## Connections

- Participant → Experiment CLI: controls run (evidence: `README.md`)
- Ludus range → Range workloads: deploys range (evidence: `README.md`)
- Experiment CLI → Run control: sets run state (evidence: `ansible/roles/ludus_experiment_cli/files/viberange_experiment.py`)
- Experiment CLI → Caldera operation: starts operation (evidence: `ansible/roles/ludus_experiment_cli/files/viberange_experiment.py`)
- Experiment CLI → Router capture: starts capture (evidence: `ansible/roles/ludus_experiment_cli/files/viberange_experiment.py`)
- Caldera content → Caldera operation: syncs abilities (evidence: `ansible/roles/ludus_caldera_content/files/sync_content.py`)
- Caldera operation → Attacker host: runs on (evidence: `README.md`)
- Attacker host → Kubernetes target: attacks (evidence: `README.md`)
- Kubernetes target → Kubernetes telemetry: produces evidence (evidence: `README.md`)
- Kubernetes telemetry → Vector transport: ships telemetry (evidence: `README.md`)
- Attacker host → Vector transport: ships audit (evidence: `README.md`)
- Router capture → PCAP and Zeek: processes capture (evidence: `README.md`)
- PCAP and Zeek → Vector transport: spools Zeek evidence (evidence: `ansible/roles/ludus_router_evidence/files/finalize_router_evidence.py`)
- Vector transport → ClickHouse evidence: transports records (evidence: `README.md`)
- CH-UI content → CH-UI analysis: seeds dashboards (evidence: `ansible/roles/ludus_ch_ui/files/seed_ch_ui.py`)
- CH-UI analysis → ClickHouse evidence: queries evidence (evidence: `README.md`)
- Jupyter analysis → ClickHouse evidence: reconstructs runs (evidence: `README.md`)
- Detection rules → Detection runner: provides rules (evidence: `README.md`)
- Detection runner → ClickHouse evidence: queries evidence
- Detection receiver → ClickHouse evidence: stores matches (evidence: `ansible/roles/ludus_detection_runner/files/receiver.py`)
- Reconstruction report → Jupyter analysis: generates report (evidence: `README.md`)