range42 is a modular cyber range platform based on Proxmox + Ansible for deploying reproducible offensive, defensive and hybrid training environments. One operator workstation can manage multiple Proxmox infrastructures, each running multiple lab scenarios. Everything is infrastructure-as-code.

Start with GETTING_STARTED.md for a hands-on walkthrough, or browse the GLOSSARY for terminology (codename, scenario, workspace, jump host, etc.).

• Start here
  • Quick start
  • Supported platforms
  • Daily operations
• About the project
  • Who it's for
  • Architecture overview
  • Networks and firewall
  • The stack
  • Project mid / long term goals
  • Extend the scenarios
  • Glossary
  • Authors

The recommended way to deploy range42 is the setup wizard:

sudo apt-get update ; apt-get upgrade -y
sudo apt-get install python3-venv git
mkdir -p $HOME/range42 && cd $HOME/range42
git clone https://github.com/range42/range42.git
cd range42
./range42-init.py

The wizard walks you through preflight checks, Proxmox connection, network configuration (SDN networks by default, outbound NAT per network, an optional ssh whitelist for the lab VMs) and the full deployment.

For the complete walkthrough (prerequisites, every wizard step explained, SSH access, daily operations, troubleshooting), see GETTING_STARTED.md.

If you'd rather drive the playbooks yourself, see Manual setup (advanced).

range42 is developed and tested on Ubuntu LTS (Desktop / Server) and is also expected to work on Debian 13. Full details and prerequisites: GETTING_STARTED.md - Prerequisites.

Once deployed, you manage your lab with the range42-context shell tool (switch workspaces, deploy / undeploy, SSH into VMs, view credentials, etc.). The full reference is in GETTING_STARTED.md - What you can do after deploy.

• Sysadmins - practice securing vulnerable stacks and test hardening procedures
• SOC analysts / blue teams - validate detection rules, tune alerts, test incident response
• Red teamers / researchers - build exploit chains, study CVEs in controlled environments
• Forensics teams - reconstruct incidents, analyse compromised systems

A range42 deployment can be driven in two complementary ways:

Web UI path (visual, recommended for day-to-day operations):

  ┌─ range42-deployer-ui (Vue 3 + VueFlow) ──────────────────┐
  │  Visual topology canvas — drag-and-drop lab design        │
  └──────────────────────────┬───────────────────────────────┘
                             │ REST + WebSocket
  ┌──────────────────────────▼───────────────────────────────┐
  │  range42-api-gw (Kong gateway)                           │
  │  Auth, ACLs, rate-limiting                               │
  └──────────────────────────┬───────────────────────────────┘
                             │
  ┌──────────────────────────▼───────────────────────────────┐
  │  range42-backend-api (FastAPI)                           │
  │  80 REST endpoints + /ws/status stream                   │
  └──────────┬───────────────────────┬───────────────────────┘
             │                       │
  range42-playbooks          range42-catalog
  (scenarios + bundles)      (roles, Docker, CTF content)
             │
             ▼
  [ Proxmox VE cluster ]
  VMs, LXC, networks

CLI path (direct, for advanced/scripted use):

  [ deployer-cli (range42-context) ]
     │
     ├─ runs the setup wizard
     ├─ holds inventory + credentials
     └─ drives Ansible playbooks directly
             │
             ▼
  [ Proxmox VE cluster ]
  VMs, LXC, networks

Both paths converge on the same Proxmox infrastructure and Ansible playbooks — the web UI simply adds a visual layer and a managed API on top.

The deployer-cli is your local machine by default, or a dedicated pivot VM if you manage multiple Proxmox infrastructures from one place.

Today, the lab VMs on Proxmox are generally organised into 3 host groups (this is the convention used by current scenarios and may evolve as new ones are added):

Only the lab systems are required. The admin VMs are off by default and switched on one by one with feature flags (INSTALL_WAZUH, INSTALL_MISP...), the student group is optional.

The lab networks are Proxmox SDN objects : one zone per host, one vnet per lab subnet (net142 for the admin tier, net143, net144... for the teams, net140 for the template builds), created once at init and declared by each scenario in its 00_sdn_bootstrap/_main.yml. Outbound NAT is a per-network toggle of the init. The Proxmox firewall is wired at every deployment : anti-lockout accepts on the datacenter and the node, an ssh accept on every VM, and an arming that stays opt-in.

range42-context networks-show-sdn                # zone, vnets, subnets, NAT, isolation of the active scenario
range42-context networks-internet-list           # declared vs live egress, per network
range42-context networks-internet-off            # cut the egress of the scenario networks (networks-internet-on restores it)
range42-context networks-show-firewall --rules   # datacenter, node and per-VM switches, then the rules and what is in force
range42-context networks-firewall-on             # arm the guests of the scenario (networks-firewall-off disarms)

Every gesture takes a scope (--roles, --vnet or --cidr for the egress pair, --scope for the firewall pair and the views) and --yes to skip its confirmation ; range42-context help lists them all, and range42-context --tui offers the same gestures in a dashboard.

At init, the ssh accept of the lab VMs can be restricted to addresses of your choice : it is the Proxmox firewall of each VM, not the firewall inside the VM, and every network of the scenario stays allowed so the deployer never locks itself out. Details in GETTING_STARTED.md.

In its recommended configuration, range42 relies on:

• Proxmox - hypervisor for virtual machines (mandatory)
• Ansible - provisioning and orchestration (mandatory)
• Docker / LXC - containerized services and vulnerable stacks (recommended)
• Wazuh - security monitoring and detection (optional)
• Firewalls / VPN - network segmentation and access control (recommended)
• Proxmox SDN + Proxmox firewall - lab networks as SDN vnets, hypervisor-side segmentation armed on demand (the default of the init)
• Vue.js / FastAPI / Kong - web UI and API layer (available)

The goal is to cover the full spectrum of cyber training. Here's where the project stands today and where it's heading.

Status legend: shipping = production-tested · early = working, content to grow · partial = code in place, currently disabled · planned = on the roadmap

All deployable scenarios live in range42-playbooks/scenarios - the list will grow over time.

The reusable building blocks (CVEs, misconfigured services, product setups, Ansible roles) live in the range42-catalog repository.

Want a specific product, CVE or misconfiguration added? Open an issue on the range42-catalog repo - we centralise catalog requests there.

Found a bug or have a feature request for range42 itself? Open an issue on the range42 repo (anything not related to the catalog goes here).

We'll prioritise as fast as we can.

See GLOSSARY.md for all terminology: codename, scenario, workspace, deployer-cli, jump host, vault, context, range42-context, SDN zone and vnets, firewall arming, host groups, inventory.

range42 is built and maintained by:

See AUTHORS file for the full list of contributors.