# cliffe/secgen architecture

> Architecture diagram of the GitHub repository cliffe/secgen, 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/cliffe/secgen
- Repository: https://github.com/cliffe/secgen

## Overview

SecGen turns a scenario specification and its module catalog into randomized vulnerable systems and challenges, then generates project artifacts and provisions virtual machines. The README documents the main orchestration and provisioning flow; the tree shows reader, model, generator, output, and provider components. Source excerpts are sparse, so edges below rely on the README’s explicit workflow descriptions; internal calls between unsampled components are not asserted.

Main entry points: [`secgen.rb`](https://github.com/cliffe/secgen/blob/master/secgen.rb) (SecGen CLI), [`lib/readers/xml_reader.rb`](https://github.com/cliffe/secgen/blob/master/lib/readers/xml_reader.rb) (XML reader), [`lib/batch/batch_secgen.rb`](https://github.com/cliffe/secgen/blob/master/lib/batch/batch_secgen.rb) (Scenario randomization), [`lib/readers/module_reader.rb`](https://github.com/cliffe/secgen/blob/master/lib/readers/module_reader.rb) (Module catalog reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Scenario entry"]
  node_cli["SecGen CLI<br/>[secgen.rb]"]
  node_scenario["Scenario definition"]
end

subgraph group_domain["Scenario processing"]
  node_xml_reader["XML reader<br/>[xml_reader.rb]"]
  node_module_reader["Module catalog reader<br/>[module_reader.rb]"]
  node_system_reader["System reader<br/>[system_reader.rb]"]
  node_scenario_model["Scenario model<br/>[scenario.rb]"]
  node_system_model["System model<br/>[system.rb]"]
  node_module_model["Module model<br/>[module.rb]"]
  node_randomization["Scenario randomization<br/>[batch_secgen.rb]"]
end

subgraph group_content["Challenge content"]
  node_module_catalog[("Services and vulnerabilities")]
  node_content_generators["Challenge generators"]
  node_string_encoder["String encoder"]
end

subgraph group_outputs["Artifacts and provisioning"]
  node_project_files["Project files"]
  node_xml_scenario["Scenario XML output"]
  node_xml_cybok["CyBOK XML output"]
  node_ctfd["CTFd output<br/>[ctfd_generator.rb]"]
end

subgraph group_providers["Infrastructure providers"]
  node_vagrant["Vagrant"]
  node_puppet["Puppet"]
  node_virtualbox["VirtualBox"]
  node_ovirt["oVirt<br/>[ovirt.rb]"]
  node_proxmox["Proxmox<br/>[proxmox.rb]"]
end

node_user(("Scenario author"))

node_user -->|"invokes"| node_cli
node_user -->|"specifies"| node_scenario
node_cli -->|"reads configuration"| node_xml_reader
node_xml_reader -.->|"loads scenario"| node_scenario_model
node_xml_reader -.->|"loads catalog"| node_module_reader
node_module_reader -->|"reads modules"| node_module_catalog
node_cli -->|"randomizes scenario"| node_randomization
node_randomization -.->|"selects systems"| node_system_model
node_randomization -.->|"selects modules"| node_module_model
node_module_catalog -.->|"provides content"| node_content_generators
node_content_generators -.->|"uses encoder"| node_string_encoder
node_cli -.->|"generates project"| node_project_files
node_cli -.->|"generates XML"| node_xml_scenario
node_cli -.->|"generates index"| node_xml_cybok
node_cli -.->|"generates CTFd"| node_ctfd
node_cli -->|"provisions VMs"| node_vagrant
node_vagrant -->|"runs guests"| node_virtualbox
node_vagrant -->|"provisions guests"| node_puppet
node_cli -.->|"supports deployment"| node_ovirt
node_cli -.->|"supports deployment"| node_proxmox

click node_cli "https://github.com/cliffe/secgen/blob/master/secgen.rb"
click node_xml_reader "https://github.com/cliffe/secgen/blob/master/lib/readers/xml_reader.rb"
click node_module_reader "https://github.com/cliffe/secgen/blob/master/lib/readers/module_reader.rb"
click node_system_reader "https://github.com/cliffe/secgen/blob/master/lib/readers/system_reader.rb"
click node_scenario_model "https://github.com/cliffe/secgen/blob/master/lib/helpers/scenario.rb"
click node_system_model "https://github.com/cliffe/secgen/blob/master/lib/objects/system.rb"
click node_module_model "https://github.com/cliffe/secgen/blob/master/lib/objects/module.rb"
click node_randomization "https://github.com/cliffe/secgen/blob/master/lib/batch/batch_secgen.rb"
click node_module_catalog "https://github.com/cliffe/secgen/tree/master/modules"
click node_content_generators "https://github.com/cliffe/secgen/tree/master/lib/objects"
click node_string_encoder "https://github.com/cliffe/secgen/blob/master/lib/objects/local_string_encoder.rb"
click node_project_files "https://github.com/cliffe/secgen/blob/master/lib/output/project_files_creator.rb"
click node_xml_scenario "https://github.com/cliffe/secgen/blob/master/lib/output/xml_scenario_generator.rb"
click node_xml_cybok "https://github.com/cliffe/secgen/blob/master/lib/output/xml_cybok_generator.rb"
click node_ctfd "https://github.com/cliffe/secgen/blob/master/lib/output/ctfd_generator.rb"
click node_ovirt "https://github.com/cliffe/secgen/blob/master/lib/helpers/ovirt.rb"
click node_proxmox "https://github.com/cliffe/secgen/blob/master/lib/helpers/proxmox.rb"

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_cli,node_scenario toneBlue
class node_xml_reader,node_module_reader,node_system_reader,node_scenario_model,node_system_model,node_module_model,node_randomization toneAmber
class node_module_catalog,node_content_generators,node_string_encoder toneMint
class node_project_files,node_xml_scenario,node_xml_cybok,node_ctfd toneRose
class node_vagrant,node_puppet,node_virtualbox,node_ovirt,node_proxmox,node_user toneIndigo
```

## Components

### Scenario entry

- [SecGen CLI](https://github.com/cliffe/secgen/blob/master/secgen.rb): `secgen.rb`
- **Scenario definition**

### Scenario processing

- [XML reader](https://github.com/cliffe/secgen/blob/master/lib/readers/xml_reader.rb): `lib/readers/xml_reader.rb`
- [Module catalog reader](https://github.com/cliffe/secgen/blob/master/lib/readers/module_reader.rb): `lib/readers/module_reader.rb`
- [System reader](https://github.com/cliffe/secgen/blob/master/lib/readers/system_reader.rb): `lib/readers/system_reader.rb`
- [Scenario model](https://github.com/cliffe/secgen/blob/master/lib/helpers/scenario.rb): `lib/helpers/scenario.rb`
- [System model](https://github.com/cliffe/secgen/blob/master/lib/objects/system.rb): `lib/objects/system.rb`
- [Module model](https://github.com/cliffe/secgen/blob/master/lib/objects/module.rb): `lib/objects/module.rb`
- [Scenario randomization](https://github.com/cliffe/secgen/blob/master/lib/batch/batch_secgen.rb): `lib/batch/batch_secgen.rb`

### Challenge content

- [Services and vulnerabilities](https://github.com/cliffe/secgen/tree/master/modules): `modules`
- [Challenge generators](https://github.com/cliffe/secgen/tree/master/lib/objects): `lib/objects`
- [String encoder](https://github.com/cliffe/secgen/blob/master/lib/objects/local_string_encoder.rb): `lib/objects/local_string_encoder.rb`

### Artifacts and provisioning

- [Project files](https://github.com/cliffe/secgen/blob/master/lib/output/project_files_creator.rb): `lib/output/project_files_creator.rb`
- [Scenario XML output](https://github.com/cliffe/secgen/blob/master/lib/output/xml_scenario_generator.rb): `lib/output/xml_scenario_generator.rb`
- [CyBOK XML output](https://github.com/cliffe/secgen/blob/master/lib/output/xml_cybok_generator.rb): `lib/output/xml_cybok_generator.rb`
- [CTFd output](https://github.com/cliffe/secgen/blob/master/lib/output/ctfd_generator.rb): `lib/output/ctfd_generator.rb`

### Infrastructure providers

- **Vagrant**
- **Puppet**
- **VirtualBox**
- [oVirt](https://github.com/cliffe/secgen/blob/master/lib/helpers/ovirt.rb): `lib/helpers/ovirt.rb`
- [Proxmox](https://github.com/cliffe/secgen/blob/master/lib/helpers/proxmox.rb): `lib/helpers/proxmox.rb`

### Other components

- **Scenario author**

## Connections

- Scenario author → SecGen CLI: invokes
- Scenario author → Scenario definition: specifies
- SecGen CLI → XML reader: reads configuration
- XML reader → Scenario model: loads scenario
- XML reader → Module catalog reader: loads catalog
- Module catalog reader → Services and vulnerabilities: reads modules
- SecGen CLI → Scenario randomization: randomizes scenario
- Scenario randomization → System model: selects systems
- Scenario randomization → Module model: selects modules
- Services and vulnerabilities → Challenge generators: provides content
- Challenge generators → String encoder: uses encoder (evidence: `lib/objects/local_paragraph_generator.rb`)
- SecGen CLI → Project files: generates project
- SecGen CLI → Scenario XML output: generates XML
- SecGen CLI → CyBOK XML output: generates index
- SecGen CLI → CTFd output: generates CTFd
- SecGen CLI → Vagrant: provisions VMs
- Vagrant → VirtualBox: runs guests
- Vagrant → Puppet: provisions guests
- SecGen CLI → oVirt: supports deployment
- SecGen CLI → Proxmox: supports deployment
