# theocaudan/ot-cyberrange architecture

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

- Interactive diagram: https://gitdiagram.com/theocaudan/ot-cyberrange
- Repository: https://github.com/theocaudan/ot-cyberrange

## Overview

OT Cyber Range is an Ansible-managed Purdue-style lab. An operator runs the deployment playbook, which provisions segmented libvirt networks and VMs, then configures firewall and application roles; the README describes the intended network boundaries and service mix. Configuration is split among network, VM, firewall, and per-role variables, with host secrets kept in Vault. The README documents the capabilities and intended wiring; source excerpts are limited to a PLC placeholder, so implementation-level calls and deployment order beyond that documentation are not verified.

Main entry points: [`deploy.yml`](https://github.com/theocaudan/ot-cyberrange/blob/main/deploy.yml) (Deployment playbook), [`roles/plc/tasks/main.yml`](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/plc/tasks/main.yml) (PLC / OpenPLC), [`roles/network/tasks/main.yml`](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/network/tasks/main.yml) (Network role), [`roles/vm/tasks/main.yml`](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/vm/tasks/main.yml) (VM role)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_playbook["Deployment playbook<br/>[deploy.yml]"]
end

subgraph group_networking["Networks and Security"]
  node_network_role["Network role<br/>[main.yml]"]
  node_firewall_role["Firewall role<br/>[main.yml]"]
end

subgraph group_machines["VM Provisioning"]
  node_vm_role["VM role<br/>[main.yml]"]
end

subgraph group_services["Lab Services"]
  node_bastion["Bastion / Guacamole<br/>[main.yml]"]
  node_siem["Wazuh / Suricata<br/>[main.yml]"]
  node_scada["SCADA / Ignition<br/>[main.yml]"]
  node_plc["PLC / OpenPLC<br/>[main.yml]"]
  node_plc_worker["PLC Python worker<br/>[plc-sim.py]"]
  node_caldera["Caldera<br/>[main.yml]"]
  node_ad_dc["AD controller<br/>[main.yml]"]
  node_ad_client["AD client<br/>[main.yml]"]
end

subgraph group_configuration["Configuration"]
  node_network_defs["Network definitions<br/>[networks.yml]"]
  node_firewall_defs["Firewall policies"]
  node_vm_defs["VM definitions<br/>[vms.yml]"]
  node_vault["Host secrets<br/>[vault.yml]"]
end

node_operator(("Lab operator"))
node_libvirt["QEMU / libvirt"]
node_docker["Docker"]

node_operator -->|"runs"| node_playbook
node_playbook -->|"deploys networks"| node_network_role
node_playbook -->|"deploys VMs"| node_vm_role
node_playbook -.->|"configures roles"| node_firewall_role
node_playbook -.->|"configures roles"| node_bastion
node_playbook -.->|"configures roles"| node_siem
node_playbook -.->|"configures roles"| node_scada
node_playbook -.->|"configures roles"| node_plc
node_playbook -.->|"configures roles"| node_caldera
node_playbook -.->|"configures roles"| node_ad_dc
node_playbook -.->|"configures roles"| node_ad_client
node_network_defs -->|"defines networks"| node_network_role
node_vm_defs -->|"defines VMs"| node_vm_role
node_firewall_defs -->|"defines rules"| node_firewall_role
node_network_role -.->|"creates networks"| node_libvirt
node_vm_role -->|"creates VMs"| node_libvirt
node_bastion -->|"deploys service"| node_docker
node_siem -->|"deploys services"| node_docker
node_scada -->|"deploys service"| node_docker
node_plc -->|"deploys services"| node_docker
node_plc -->|"includes worker"| node_plc_worker
node_vault -->|"stores secrets"| node_bastion
node_ad_client -->|"joins domain"| node_ad_dc

click node_playbook "https://github.com/theocaudan/ot-cyberrange/blob/main/deploy.yml"
click node_network_role "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/network/tasks/main.yml"
click node_network_defs "https://github.com/theocaudan/ot-cyberrange/blob/main/vars/networks.yml"
click node_firewall_role "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/firewall/tasks/main.yml"
click node_firewall_defs "https://github.com/theocaudan/ot-cyberrange/blob/main/vars/firewall-it-dmz.yml"
click node_vm_role "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/vm/tasks/main.yml"
click node_vm_defs "https://github.com/theocaudan/ot-cyberrange/blob/main/vars/vms.yml"
click node_bastion "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/bastion/tasks/main.yml"
click node_siem "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/siem/tasks/main.yml"
click node_scada "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/scada/tasks/main.yml"
click node_plc "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/plc/tasks/main.yml"
click node_plc_worker "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/plc/files/app/plc-sim.py"
click node_caldera "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/caldera/tasks/main.yml"
click node_ad_dc "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/ad-dc/tasks/main.yml"
click node_ad_client "https://github.com/theocaudan/ot-cyberrange/blob/main/roles/ad-client/tasks/main.yml"
click node_vault "https://github.com/theocaudan/ot-cyberrange/blob/main/host_vars/bastion/vault.yml"

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_playbook toneBlue
class node_network_role,node_firewall_role toneAmber
class node_vm_role toneMint
class node_bastion,node_siem,node_scada,node_plc,node_plc_worker,node_caldera,node_ad_dc,node_ad_client toneRose
class node_network_defs,node_firewall_defs,node_vm_defs,node_vault,node_operator,node_libvirt,node_docker toneIndigo
```

## Components

### Deployment

- [Deployment playbook](https://github.com/theocaudan/ot-cyberrange/blob/main/deploy.yml): `deploy.yml`

### Networks and Security

- [Network role](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/network/tasks/main.yml): `roles/network/tasks/main.yml`
- [Firewall role](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/firewall/tasks/main.yml): `roles/firewall/tasks/main.yml`

### VM Provisioning

- [VM role](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/vm/tasks/main.yml): `roles/vm/tasks/main.yml`

### Lab Services

- [Bastion / Guacamole](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/bastion/tasks/main.yml): `roles/bastion/tasks/main.yml`
- [Wazuh / Suricata](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/siem/tasks/main.yml): `roles/siem/tasks/main.yml`
- [SCADA / Ignition](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/scada/tasks/main.yml): `roles/scada/tasks/main.yml`
- [PLC / OpenPLC](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/plc/tasks/main.yml): `roles/plc/tasks/main.yml`
- [PLC Python worker](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/plc/files/app/plc-sim.py): `roles/plc/files/app/plc-sim.py`
- [Caldera](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/caldera/tasks/main.yml): `roles/caldera/tasks/main.yml`
- [AD controller](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/ad-dc/tasks/main.yml): `roles/ad-dc/tasks/main.yml`
- [AD client](https://github.com/theocaudan/ot-cyberrange/blob/main/roles/ad-client/tasks/main.yml): `roles/ad-client/tasks/main.yml`

### Configuration

- [Network definitions](https://github.com/theocaudan/ot-cyberrange/blob/main/vars/networks.yml): `vars/networks.yml`
- [Firewall policies](https://github.com/theocaudan/ot-cyberrange/blob/main/vars/firewall-it-dmz.yml): `vars/firewall-it-dmz.yml`
- [VM definitions](https://github.com/theocaudan/ot-cyberrange/blob/main/vars/vms.yml): `vars/vms.yml`
- [Host secrets](https://github.com/theocaudan/ot-cyberrange/blob/main/host_vars/bastion/vault.yml): `host_vars/bastion/vault.yml`

### Other components

- **Lab operator**
- **QEMU / libvirt**
- **Docker**

## Connections

- Lab operator → Deployment playbook: runs (evidence: `README.md`)
- Deployment playbook → Network role: deploys networks (evidence: `README.md`)
- Deployment playbook → VM role: deploys VMs (evidence: `README.md`)
- Deployment playbook → Firewall role: configures roles
- Deployment playbook → Bastion / Guacamole: configures roles
- Deployment playbook → Wazuh / Suricata: configures roles
- Deployment playbook → SCADA / Ignition: configures roles
- Deployment playbook → PLC / OpenPLC: configures roles
- Deployment playbook → Caldera: configures roles
- Deployment playbook → AD controller: configures roles
- Deployment playbook → AD client: configures roles
- Network definitions → Network role: defines networks (evidence: `README.md`)
- VM definitions → VM role: defines VMs (evidence: `README.md`)
- Firewall policies → Firewall role: defines rules (evidence: `README.md`)
- Network role → QEMU / libvirt: creates networks
- VM role → QEMU / libvirt: creates VMs (evidence: `README.md`)
- Bastion / Guacamole → Docker: deploys service (evidence: `README.md`)
- Wazuh / Suricata → Docker: deploys services (evidence: `README.md`)
- SCADA / Ignition → Docker: deploys service (evidence: `README.md`)
- PLC / OpenPLC → Docker: deploys services (evidence: `README.md`)
- PLC / OpenPLC → PLC Python worker: includes worker (evidence: `README.md`)
- Host secrets → Bastion / Guacamole: stores secrets (evidence: `README.md`)
- AD client → AD controller: joins domain (evidence: `README.md`)
