references/roles.md

GitHub

Roles

How to use Ansible roles with Ludus, add roles, configure role variables, and a table of Ludus-specific community roles.

How to use Roles

Tip: Looking to create your own roles? Check out the role developer page in the Ludus docs.

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.

Tip: Any ansible role (35,000+) can be used with Ludus, as long as it is compatible with the OS of the VM and the roles pre-requisites are met. You can search for roles on Ansible Galaxy.

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
badsectorlabs.ludus_adcs Installs ADCS on Windows Server and optionally configures Certified Preowned templates. Bad Sector Labs
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
badsectorlabs.ludus_elastic_agent Installs an Elastic Agent on a Windows, Debian, or Ubuntu system Bad Sector Labs
badsectorlabs.ludus_xz_backdoor Installs the xz backdoor (CVE-2024-3094) on a Debian host and optionally installs the xzbot tool. Bad Sector Labs
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 @_choisec Must install from directory
ludus_child_domain_join Join a machine to the child domain created from ludus_child_domain @_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
bagelByt3s.ludus_adfs Installs an ADFS deployment with optional configurations. Beyviel David Must install from directory
ludus_caldera_server Installs Caldera Server main branch on linux @frack113
ludus_caldera_agent Installs Caldera Agent on Windows @frack113
ludus_aurora_agent Installs Aurora Agent on Windows @frack113 Requires package and valid license
ludus_graylog_server Installs Graylog server on Ubuntu 22.04 @frack113 Must install from directory
ludus_filigran_opencti Installs OpenCTI @frack113
ludus_ghosts_server Installs Ghosts on a Linux server @frack113
jasonmull.ludus_ghosts_client Installs Ghosts client on a Windows endpoint @jasonmull
jasonmull.empire_c2_docker Deploy Empire C2 via Docker @jasonmull
0xRedpoll.ludus_cobaltstrike_teamserver Install and provision a Cobalt Strike teamserver in Ludus @0xRedpoll
0xRedpoll.ludus_mythic_teamserver Installs and spins up a Mythic Teamserver on a Debian or Ubuntu server @0xRedpoll
ludus-ad-vulns Adds vulnerabilities in an Active Directory. @Primusinterp Must install from directory
ludus_juiceshop Installs OWASP Juice Shop xurger Must install from directory
netpenguins.ludus_sliver Installs SliverC2 NetPenguins
netpenguins.ludus_redirector Sets up an Apache2 redirector for adversarial simulation ranges NetPenguins
netpenguins.ludus_k3s Deploys a k3s cluster in ludus ranges NetPenguins
ludus_enable_asr Enables many Attack Surface Reduction rules on a Windows host @curi0usJack Must install from directory
ludus_enable_mdi_gpo Creates GPOs and adds recommended auditing settings for Microsoft Defender for Identity @curi0usJack Must install from directory
ludus_badblood Outfits your ludus AD domain with BadBlood info @curi0usJack Must install from directory
ludus_splunk_universalforwarder Installs Splunk Universal Forwarder on Windows endpoints @curi0usJack Must install from directory
ludus_splunk Installs Splunk Enterprise on Linux @curi0usJack Must install from directory
ludus_adtimeline_syncthing Installs ADTimeline Splunk app with Syncthing for automatic ingestion mojeda101
ludus_litterbox Installs Litterbox controlled sandbox environment for payload development/testing professor-moody
professor_moody.scorch.ludus Sets up a full SCORCH deployment with various common misconfigurations professor-moody collection
5tuk0v.ludus_wsus Installs Windows Server Update Services (WSUS) on Windows Server @stuk0v_
5tuk0v.ludus_vectr Installs VECTR threat tracking and campaign management tool on Ubuntu 22.04 @stuk0v_
5tuk0v.ludus_ghostwritter Installs Ghostwriter on a Linux-based host @stuk0v_
5tuk0v.ludus_zeek Installs Zeek on Debian and Ubuntu hosts @stuk0v_
inf0junki3.ludus.netbox Sets up the Netbox network & infrastructure management solution inf0junki3 Part of the inf0junki3.ludus collection
inf0junki3.ludus.vectr Sets up the VECTR red/purple team platform inf0junki3 Part of the inf0junki3.ludus collection
brmkit.ludus_nemesis Installs Nemesis by SpecterOps @_brmkit
brmkit.ludus_guacamole Installs Guacamole on Linux and optionally configures connections @_brmkit