🎭 Roles

How to use Roles

tip

Looking to create your own roles? Check out the role developer page!

Roles are Ansible roles that are applied to VMs in Ludus after they are deployed and configured. It's easy to add a role to a Ludus VM, simply add the role to Ludus and then define the roles key in the config.

Roles are unique to each user on a Ludus host, which allows users to have different versions of roles, custom roles, etc without overwriting or breaking each other's roles.

To add a role to Ludus, use the client as the user that will deploy the role (optionally specify the user/range that will use the role with --user)

# Add directly from Ansible Galaxy
ludus ansible role add badsectorlabs.ludus_adcs

# Add from a local directory
ludus ansible role add -d ./ludus_child_domain

# Add a role for another user/range (as an admin)
ludus ansible role add badsectorlabs.luds_adcs --user USER2

After roles have been added to Ludus, you can modify the range config to use them:

range-config.yml
ludus:
  - vm_name: "{{ range_id }}-docker-host"
    hostname: "{{ range_id }}-docker"
    template: debian-12-x64-server-template
    vlan: 10
    ip_last_octet: 11
    ram_gb: 8
    cpus: 4
    linux: true
    roles:                  # This key is an array of user-defined roles that will be installed on this VM. Roles must exist on the Ludus server and can be installed with `ludus ansible role add`
      - geerlingguy.docker  # Arbitrary role name, as it appears in `ludus ansible roles list`
    role_vars:              # This key contains `key: value` pairs of variables that are passed to ALL user-defined roles.
      docker_edition: ce    # Arbitrary variables for user-defined roles. Do *not* use hyphens to prefix these variables, the role_vars key *must* be a dictionary!
      docker_users:         # You can use lists or dicts here
        - localuser

You can define any variables that will be passed to the role with role_vars as seen above. Note that all variable in role_vars will be passed to all roles.

Ludus Specific Roles

While most existing ansible roles will work with Ludus, this page contains a table of roles specifically designed for Ludus.

Role	Description	Author	Notes
badsectorlabs.ludus_vulhub	Runs Vulhub environments on a Linux system.	Bad Sector Labs	See the env guide
badsectorlabs.ludus_adcs	Installs ADCS on Windows Server and optionally configures Certified Preowned templates.	Bad Sector Labs	See the env guide
badsectorlabs.ludus_bloodhound_ce	Installs Bloodhound CE on a Debian based system.	Bad Sector Labs
badsectorlabs.ludus_mssql	Installs MSSQL on Windows systems.	Bad Sector Labs
badsectorlabs.ludus_elastic_container	Installs "The Elastic Container Project" on a Linux system.	Bad Sector Labs	See the env guide
badsectorlabs.ludus_elastic_agent	Installs an Elastic Agent on a Windows, Debian, or Ubuntu system	Bad Sector Labs	See the env guide
badsectorlabs.ludus_xz_backdoor	Installs the xz backdoor (CVE-2024-3094) on a Debian host and optionally installs the xzbot tool.	Bad Sector Labs	See the env guide
badsectorlabs.ludus_commandovm	Sets up Commando VM on Windows >= 10 hosts	Bad Sector Labs	Available as a template
badsectorlabs.ludus_flarevm	Installs Flare VM on Windows >= 10 hosts	Bad Sector Labs	Available as a template
badsectorlabs.ludus_remnux	Installs REMnux on Ubuntu 20.04 systems	Bad Sector Labs	Available as a template
badsectorlabs.ludus_emux	Installs EMUX and runs an emulated device on Debian based hosts	Bad Sector Labs
aleemladha.wazuh_server_install	Install Wazuh SIEM Unified XDR and SIEM protection with SOC Fortress Rules	@LadhaAleem
aleemladha.ludus_wazuh_agent	Deploys Wazuh Agents to Windows systems	@LadhaAleem
aleemladha.ludus_exchange	Installs Microsoft Exchange Server on a Windows Server host	@LadhaAleem
ludus_child_domain	Create a child domain and domain controller because ansible's microsoft.ad doesn't support it	@_choisec	Must install from directory
ludus_child_domain_join	Join a machine to the child domain created from ludus_child_domain, since ludus's backend does not support domain/controllers created with 3rd party ansible roles	@_choisec	Must install from directory
ludus-local-users	Manages local users and groups for Windows or Linux	@tigrebleu	Must install from directory
ludus-gitlab-ce	Handles the installation of a Gitlab instance	@tigrebleu	Must install from directory
ludus-ad-content	Creates content in an Active Directory (OUs, Groups, Users)	@tigrebleu	Must install from directory
ludus_tailscale	Provision or remove a device to/from a Tailnet	@__Mastadon
ludus_velociraptor_client	Install a Velociraptor Agent on a System in Ludus	@f_Murer	Must install from directory
ludus_velociraptor_server	Install a Velociraptor Server in Ludus	@f_Murer	Must install from directory

How to use Roles​

Ludus Specific Roles​

How to use Roles

Ludus Specific Roles