How badsectorlabs/ludus works
Purpose and Top-Level Entry Points
Ludus provisions multi-user cyber ranges: VM networks and automation built on Proxmox. The principal operational path is server bootstrap → API/control plane → Proxmox/Ansible execution. Key binaries are the installer/controller in ludus-server/main.go, the user CLI in ludus-client/main.go, and the API service centered in ludus-api/routers.go. dynamic-inventory/main.go supplies generated Ansible inventory.
Server Bootstrap and Host Lifecycle
ludus-server converts a clean Debian host into a Ludus/Proxmox host, managing installation state, configuration, subprocesses, permissions, and upgrades. Its install workflow invokes staged Ansible provisioning, notably ludus-server/ansible/proxmox-install/main.yml and ludus-server/ansible/proxmox-install/stage-1.yml. This is the boundary from a local bootstrap executable to a persistent virtualization host with system services, networking, DNS, and WireGuard.
API Control Plane and Persistence
The Go API exposes management domains for ranges, VMs, templates, snapshots, users/groups, blueprints, sources, diagnostics, and power state through handlers such as ludus-api/api_range_management.go, ludus-api/api_vm_management.go, and ludus-api/api_blueprint_management.go. Routing/middleware form the HTTP boundary in ludus-api/routers.go and ludus-api/middleware.go. PocketBase is the embedded persistence/authentication backend, initialized through ludus-api/pocketbase.go; schema and access-control evolution are maintained in ludus-api/migrations/.
Range Configuration, Authorization, and Scheduling
Range definitions are validated, normalized, stored, and written through ludus-api/range_config.go, ludus-api/range_config_write.go, and ludus-api/yaml_validate.go. The API enforces tenant/group access and capacity boundaries in ludus-api/range_access.go and ludus-api/quota.go. Background timing behavior, including lifecycle work such as automatic shutdown, is centralized in ludus-api/scheduler/scheduler.go.
Provisioning Execution Boundary
API operations delegate long-running host work to Ansible and command execution rather than directly configuring every VM. ludus-api/ansible.go and ludus-api/commandmanager/commandmanager.go bridge request handling to commands/playbooks. The primary range orchestration playbook is ludus-server/ansible/range-management/ludus.yml; VM deployment and state transitions occur under ludus-server/ansible/range-management/tasks/proxmox/deploy-vm.yml and ludus-server/ansible/range-management/tasks/proxmox/set-vm-state.yml. This decouples durable API state from asynchronous infrastructure reconciliation.
Network, Access, and Virtualization Integration
Proxmox is the VM/storage hypervisor integration, represented by ludus-api/proxmox.go; SDN/network composition is handled by ludus-api/network.go and ludus-api/sdn.go. Per-range router, VLAN, DNS, and firewall setup is realized by Ansible in ludus-server/ansible/range-management/tasks/router/configure-router.yml and ludus-server/ansible/range-management/tasks/firewall/firewall-management.yml. WireGuard provides user connectivity via ludus-api/wireguard.go; access artifacts are produced by ludus-server/ansible/user-management/add-user.yml.
Templates, Blueprints, and Extensible Content
Packer builds reusable OS VM templates from HCL definitions, e.g. ludus-server/packer/debian12/debian12.pkr.hcl and ludus-server/packer/win2022-server-x64/win2022-server-x64.pkr.hcl. Blueprints compose range configurations and dependencies through ludus-api/blueprint_resolver.go. Source installation/synchronization supplies externally sourced blueprints and Ansible roles through ludus-api/source_install.go and ludus-api/source_sync.go, forming a controlled content-ingestion boundary.
Client and Embedded Interfaces
The Go CLI maps commands to API operations, with command registration in ludus-client/cmd/root.go, REST communication in ludus-client/rest/restapi.go, and domain commands such as ludus-client/cmd/range.go. The API can serve embedded Web UI and documentation via ludus-api/embedded_webui.go and ludus-api/embedded_docs.go. Documentation itself is a separate Docusaurus/Node site under docs/.
Main entry points: api_range_management.go Range and VM management · ludus.yml Range orchestration · proxmox.go Proxmox host · routers.go Ludus API
Components 20
Interfaces
- User CLI
ludus-client/main.go - CLI commands
ludus-client/cmd/root.go - Embedded web UI and docs
ludus-api/embedded_webui.go
Control Plane
- Ludus API · Management control plane for ranges and infrastructure.
ludus-api/routers.go - HTTP middleware
ludus-api/middleware.go - Range and VM management
ludus-api/api_range_management.go - Range configuration · Validates, normalizes, persists, and writes range definitions.
ludus-api/range_config.go - Access and quotas · Enforces tenant, group, and capacity limits.
ludus-api/range_access.go - PocketBase
ludus-api/pocketbase.go - Lifecycle scheduler
ludus-api/scheduler/scheduler.go - Blueprint resolver
ludus-api/blueprint_resolver.go - Source sync · Installs and synchronizes external blueprints and roles.
ludus-api/source_sync.go
Provisioning
- Command manager · Bridges API work to host commands and playbooks.
ludus-api/commandmanager/commandmanager.go - Range orchestration · Reconciles range infrastructure and VM lifecycle.
ludus-server/ansible/range-management/ludus.yml - Network and SDN
ludus-api/network.go - WireGuard access
ludus-api/wireguard.go
Host Platform
- Server bootstrap · Installs and upgrades the Ludus host.
ludus-server/main.go - Host install playbooks · Staged Debian-to-Proxmox provisioning.
ludus-server/ansible/proxmox-install/main.yml - Proxmox host · Persistent VM, storage, and network platform.
ludus-api/proxmox.go - Packer templates · Builds reusable OS VM templates.
ludus-server/packer/debian12/debian12.pkr.hcl
Connections 20
- Server bootstrap → Host install playbooks: runs
- Host install playbooks → Proxmox host: provisions
- User CLI → CLI commands: registers
- CLI commands → Ludus API: calls REST API
- Ludus API → HTTP middleware: uses
- HTTP middleware → Range and VM management: routes authorized requests
- Range and VM management → Range configuration: manages
- Range and VM management → Access and quotas: checks
- Range configuration → PocketBase: stores state
- Lifecycle scheduler → Range and VM management: triggers lifecycle work
- Range and VM management → Command manager: delegates long-running work
- Command manager → Range orchestration: runs
- Range orchestration → Proxmox host: deploys and changes VM state
- Network and SDN → Proxmox host: composes SDN
- Range orchestration → Network and SDN: configures ranges
- WireGuard access → Range orchestration: provisions user access
- Blueprint resolver → Range configuration: composes definitions
- Source sync → Blueprint resolver: supplies content
- Packer templates → Proxmox host: publishes VM images
- Ludus API → Embedded web UI and docs: serves