ludus-development

main@e655f93
Download ZIP
SpecterOps/skills/plugins/ludus/skills/ludus-development
npx skills add SpecterOps/skills --skill ludus-development
SKILL.md
nameludus-development
descriptionProvides information on how to develop Ludus configuration files
licenseMIT
metadata{"author":"xpn","version":"0.2.0","category":"security"}

Ludus Configuration Skill

When to Use

Use this skill when tasked to work on a project related to Ludus, including Ludus range configurations, Ludus roles, Ludus CLI usage, Ludus API interaction, or Ludus supporting files.

When NOT to Use

Do not use this skill when the task you are given does not mention Ludus.

Terminology

  • Ludus - A system to build easy to use cyber environments ("ranges") for testing and development, built on Proxmox
  • Range - A collection of VMs, networks, and firewall rules deployed by Ludus from a single YAML configuration file
  • Template - A base VM image built from ISO that Ludus clones to create range VMs
  • VLAN - Virtual LAN segments within a range; each VLAN becomes the third octet of the VM's IP (e.g., VLAN 10 = 10.X.10.Y)
  • Testing Mode - A Ludus state that snapshots VMs and blocks internet access for safe tool/technique testing
  • Router VM - A Debian-based VM automatically deployed per range that handles routing, DNS (AdGuard Home), and firewall rules
  • Deploy Tags - Ansible tags that control which parts of the deployment process run (e.g., vm-deploy, network, user-defined-roles)
  • Role - An Ansible role added to Ludus and applied to VMs during deployment for additional configuration

Ludus Overview

Ludus is a system to build easy to use cyber environments, or "ranges" for testing and development.

Built on Proxmox, Ludus enables advanced automation while still allowing easy manual modifications or setup of virtual machines and networks.

Ludus is implemented as a server that runs Packer and Ansible to create templates and deploy complex cyber environments from a single configuration file. Ludus is accessed via the Ludus CLI (client) or the Proxmox web interface. Normal users should not need to access Ludus via SSH.

Users can always make manual changes or set up manual environments via Proxmox instead of/in addition to Ludus managed VMs/networks. Ludus is an automation overlay on top of Proxmox, not a 100% replacement for manual configuration - just most of the common setup tasks!

Key Concepts

  • Range configs are YAML files with a ludus array of VM definitions plus optional network, router, defaults, and notify sections
  • VMs are assigned to VLANs (2-255) and given a unique ip_last_octet within the VLAN
  • IP addresses follow the pattern: 10.<range_number>.<vlan>.<ip_last_octet>
  • The {{ range_id }} template string in configs resolves to the user's ID (e.g., "JD")
  • Windows VMs require a windows key; Linux VMs require linux: true; macOS VMs require macOS: true
  • Ansible roles are added via ludus ansible role add and referenced in the roles array per VM
  • Network firewall rules use iptables on the router VM with LUDUS_USER_RULES and LUDUS_DEFAULTS chains

References

For detailed information on specific areas of Ludus, consult the Reference Index which catalogs all available documentation.

Key references for common tasks:

  • Reference Index - Master index of all documentation with descriptions and when to reference each document
  • Range Configuration - Full annotated range config YAML example with all fields
  • Range Config Schema - JSON schema reference for all config properties, types, constraints, and enum values
  • API Reference - Complete REST API endpoint documentation
  • CLI Reference - All Ludus CLI commands and flags
  • Networking - Network architecture, VLANs, firewall rules, and packet capture
  • Templates - Template management, creation, and performance tuning
  • Roles - Using Ansible roles with Ludus and the community role catalog
  • Deploy Tags - Controlling partial deployments with tags
  • Troubleshooting - Solutions for common issues