Configuration

Attack Range is driven by YAML configuration files. Each running or in-progress range has a config file in config/ named by its attack range ID (e.g. config/<uuid>.yml). Configs are created from templates in templates/{aws,azure,gcp}/.

Config file structure

A typical config has:

general — Passwords, cloud provider, naming, IP whitelist, description, and internal fields (e.g. attack_range_id, status, key_name, template_path).
Provider block — aws, azure, or gcp with region, keys, tags, etc.
attack_range — List of servers (Splunk, Windows, Linux, Kali, Zeek, etc.) with instance types, IP octets, and roles.

Example (minimal):

general:
  attack_range_password: "changeme123!"
  cloud_provider: aws
  attack_range_name: ar
  ip_whitelist: 0.0.0.0/0
  description: Minimal AWS deployment with Splunk only

aws:
  region: eu-central-1

attack_range:
  - name: splunk
    ami_name_filter: ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*
    ami_owner: "099720109477"
    instance_type: t3.xlarge
    ip_last_octet: 10
    linux: true
    user_name: ubuntu
    roles:
      - role: P4T12ICK.ludus_ar_splunk
        vars:
          ludus_ar_splunk_password: "changeme123!"

General section

Field	Description
`attack_range_password`	Master password used for Splunk, Windows/Linux accounts, and role vars when not overridden.
`cloud_provider`	`aws`, `azure`, or `gcp`.
`attack_range_name`	Short name prefix for resources (e.g. `ar`).
`ip_whitelist`	CIDR(s) allowed to reach certain resources (e.g. `0.0.0.0/0` for any).
`description`	Human-readable description of the range.
`attack_range_id`	Unique ID (UUID) for this range; set when creating from template.
`key_name`	SSH key name in the cloud (often same as `attack_range_id`).
`name` / `template_path`	Template name/path (set when creating from template).
`status`	Internal: `build_vpn`, `wait_for_vpn`, `build_lab`, `running`, `error`, `destroying`, etc.

Passwords in role vars (e.g. ludus_ar_splunk_password, ar_guacamole_password) override or complement the general password.

Provider sections

AWS (`aws`)

region — e.g. eu-central-1.
private_key_path — Path to the SSH private key (often under ssh_keys/<attack_range_id>.key).
ami_name_filter, ami_owner — Used per server when not using a shared image.
aws_default_tags — Optional tags applied to resources.

Azure (`azure`)

location — e.g. West Europe.
subscription_id — Azure subscription ID.
image_publisher, image_offer, image_sku — Defined per server in the template.

GCP (`gcp`)

Region/project and image settings as defined in the template and Terraform variables.

Attack range (servers)

Each entry under attack_range is a machine:

Field	Description
`name`	Host name; used as Ansible inventory host and as simulation target.
`instance_type`	Cloud instance type (e.g. `t3.xlarge`, `Standard_D4s_v3`).
`ip_last_octet`	Last octet of the private IP (e.g. 10 → `10.0.2.10`).
`linux` / `windows`	OS type.
`user_name`	SSH (Linux) or RDP (Windows) user.
`roles`	List of Ansible roles (and optional `vars`) applied to this server.

Additional provider-specific fields (e.g. ami_name_filter, image_offer) are set per server in templates.

Where configs live

Templates: templates/aws/, templates/azure/, templates/gcp/ — Read-only; use to create a new range.
Active configs: config/<attack_range_id>.yml — Created from a template at build start; updated with status, WireGuard config, sharing, etc.

The API and app always work with the config directory; the CLI uses config/ and resolves -c to a path or to config/<id>.yml.

Do not modify files in the config/ folder manually. The app and API create and update these files during build, destroy, share, and status changes. Editing them by hand can cause unintended side effects (e.g. out-of-sync state, failed operations, or duplicate or orphaned resources). Use the app, API, or CLI for all operations.

Creating a config from a template

API: POST /attack-range/build with {"template": "aws/splunk_minimal_aws"} (or provider/name / name). The server creates config/<new_uuid>.yml and starts the build.
CLI: python attack_range.py build -t aws/splunk_minimal_aws. The CLI creates the config and runs the two-phase build.

Environment and credentials

Docker: Mount ~/.aws, ~/.azure, and/or ~/.config/gcloud into the API and CLI containers so they can call cloud APIs and run Terraform.
API: GET /providers/check returns which provider CLIs and credentials are available.

See Templates for the list of built-in templates and their structure.