Skip to content

configuration.md

Latest commit

 

History

History
109 lines (78 loc) · 4.84 KB

configuration.md

File metadata and controls

109 lines (78 loc) · 4.84 KB

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.