Ansible Roles

Attack Range uses Ansible to configure every server in your range: the VPN router and all lab hosts (Splunk, Windows, Linux, Kali, etc.). Which software and behavior each host gets is defined by roles. You choose those roles in a template (and thus in the generated config). Crucially, you can use any Ansible Galaxy role in a template to define a new configuration—not only the ones shipped with Attack Range.

Using any Ansible Galaxy role in a template

Templates define the layout of your range. Under attack_range, each server has a roles list. Every role you list there is:

  1. Installed automatically — Before any playbook runs, Attack Range extracts all role names from the config and runs ansible-galaxy install <role_name> for each. So any role that exists on Ansible Galaxy can be used.

  2. Applied at build time — The main lab playbook is generated from your config. Each server gets a play that runs exactly the roles you attached to it, in order, with any variables you passed.

So if you want to add a custom stack (e.g. a different Splunk app, a monitoring role, or a security tool), add the Galaxy role name to the roles list of the right server in your template and build from that template. No need to modify Attack Range code.

Role name format

Use the Galaxy role name as it appears on Ansible Galaxy. That is usually namespace.role_name (e.g. geerlingguy.nginx, P4T12ICK.ludus_ar_splunk). The same format is used when you run ansible-galaxy install namespace.role_name.

Declaring roles in a template

In the template (and thus in the config), each server is a list entry under attack_range. The roles key is a list. You can use either of these forms:

Role name only (string):

attack_range:
  - name: myserver
    instance_type: t3.medium
    ip_last_octet: 20
    linux: true
    user_name: ubuntu
    roles:
      - geerlingguy.docker
      - some_namespace.some_role

Role with variables (dictionary):

attack_range:
  - name: splunk
    ...
    roles:
      - role: P4T12ICK.ludus_ar_splunk
        vars:
          ludus_ar_splunk_password: "MySecurePass"
      - role: geerlingguy.nginx
        vars:
          nginx_http_port: 8080

  • role — The Galaxy role name (required in the dict form).

  • vars — Optional variables passed to that role for this host. Follow the role’s documentation on variable names and values.

  • inventory_name — Optional. If set, this role is applied to the host group with that name instead of the server’s name. Used when one role expects a specific group name in the inventory.

You can mix string and dict entries in the same roles list. Multiple roles on the same server run in the order listed.

Example: defining a new configuration with Galaxy roles

  1. Copy an existing template from templates/<provider>/ (e.g. splunk_minimal_aws.yml).

  2. Add or replace roles under the server(s) you want to change. Use any Galaxy role names.

  3. For each role that needs options, use the dict form and set vars according to the role’s docs.

  4. Save the template (e.g. as templates/aws/my_custom_range.yml) and build from it via the app or API (e.g. template aws/my_custom_range).

At build time, Attack Range will install every listed Galaxy role and run them on the matching hosts. No extra steps are required.

How roles are installed and run

  • Source of truth: The config file (created from your template) in config/<attack_range_id>.yml. Its attack_range section lists servers and their roles.

  • Installation: Before the VPN and lab playbooks run, the controller scans attack_range for all role names (from both role: name and plain name in the list) and runs ansible-galaxy install for each. So only roles referenced in your config are installed.

  • Execution: The lab playbook (lab.yaml) is generated from the same config: one play per host (or per inventory_name group), with that host’s roles and vars. So the exact roles and variables you put in the template are what run on each machine.

This is why any Galaxy role can define your configuration: if it’s in the template’s roles list, it gets installed and executed.

Summary

  • Templates define which Ansible roles run on which servers via the roles list under each server in attack_range.

  • Any Ansible Galaxy role can be used: list it by name (e.g. namespace.role_name). Attack Range installs it and runs it at build time.

  • Use vars (dict form) to pass variables to a role. Use inventory_name when the role expects a specific host group.

  • To define a new configuration, create or edit a template, add the desired Galaxy roles (and vars), and build from that template. No code changes are required.