Skip to main content

🎭 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.

RoleDescriptionAuthorNotes
badsectorlabs.ludus_vulhubRuns Vulhub environments on a Linux system.Bad Sector LabsSee the env guide
badsectorlabs.ludus_adcsInstalls ADCS on Windows Server and optionally configures Certified Preowned templates.Bad Sector LabsSee the env guide
badsectorlabs.ludus_bloodhound_ceInstalls Bloodhound CE on a Debian based system.Bad Sector Labs
badsectorlabs.ludus_mssqlInstalls MSSQL on Windows systems.Bad Sector Labs
badsectorlabs.ludus_elastic_containerInstalls "The Elastic Container Project" on a Linux system.Bad Sector LabsSee the env guide
badsectorlabs.ludus_elastic_agentInstalls an Elastic Agent on a Windows, Debian, or Ubuntu systemBad Sector LabsSee the env guide
badsectorlabs.ludus_xz_backdoorInstalls the xz backdoor (CVE-2024-3094) on a Debian host and optionally installs the xzbot tool.Bad Sector LabsSee the env guide
badsectorlabs.ludus_commandovmSets up Commando VM on Windows >= 10 hostsBad Sector LabsAvailable as a template
badsectorlabs.ludus_flarevmInstalls Flare VM on Windows >= 10 hostsBad Sector LabsAvailable as a template
badsectorlabs.ludus_remnuxInstalls REMnux on Ubuntu 20.04 systemsBad Sector LabsAvailable as a template
badsectorlabs.ludus_emuxInstalls EMUX and runs an emulated device on Debian based hostsBad Sector Labs
aleemladha.wazuh_server_installInstall Wazuh SIEM Unified XDR and SIEM protection with SOC Fortress Rules@LadhaAleem
aleemladha.ludus_wazuh_agentDeploys Wazuh Agents to Windows systems@LadhaAleem
aleemladha.ludus_exchangeInstalls Microsoft Exchange Server on a Windows Server host@LadhaAleem
ludus_child_domainCreate a child domain and domain controller because ansible's microsoft.ad doesn't support it@_choisecMust install from directory
ludus_child_domain_joinJoin 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@_choisecMust install from directory
ludus-local-usersManages local users and groups for Windows or Linux@tigrebleuMust install from directory
ludus-gitlab-ceHandles the installation of a Gitlab instance@tigrebleuMust install from directory
ludus-ad-contentCreates content in an Active Directory (OUs, Groups, Users)@tigrebleuMust install from directory
ludus_tailscaleProvision or remove a device to/from a Tailnet@__Mastadon
ludus_velociraptor_clientInstall a Velociraptor Agent on a System in Ludus@f_MurerMust install from directory
ludus_velociraptor_serverInstall a Velociraptor Server in Ludus@f_MurerMust install from directory