Skip to main content
Glama

Ludus FastMCP

Version Python Ludus License

A Model Context Protocol (MCP) server for automating Ludus cyber range environments through AI assistants written in Python.

Overview

Ludus FastMCP enables AI-powered management of Ludus cyber ranges through natural language commands. The server exposes 231 tools across 23 modules for range lifecycle management, scenario deployment, template creation, Ansible role management, and security monitoring integration.

Requires Ludus 2.0 or later. This release targets the Ludus 2.x API only, which is what makes blueprints, groups, content sources, VM console access, quotas and diagnostics available. Support for the Ludus 1.x API was removed; pin ludus-fastmcp to a 1.x release if you still run a Ludus 1.x server.

The client covers every endpoint in the Ludus API, validated against a live Ludus 2.3.0 server.

Key Capabilities

Category

Description

Range Management

Create, configure, deploy, and manage virtual lab environments

Blueprints

Create, export, import, share, and apply reusable range configurations

Content Sources

Add git or archive catalogs of templates, roles, and prebuilt labs such as GOAD

Groups

Organize users and ranges with group-based access control

Scenario Deployment

Pre-built scenarios for AD, red/blue/purple team, and malware analysis

Template Builder

Custom OS templates, skeleton configurations, and YAML generation

Role Management

Ansible Galaxy integration, custom roles, subscription roles, and scope control

SIEM Integration

Wazuh, Splunk, Elastic Stack, and Security Onion support

AI Configuration

Natural language to YAML configuration conversion

Diagnostics

System health, license info, deployment log history, and migration tools

Quotas & Limits

Per-user and per-group resource quotas, plus range auto-shutdown (plugin)

Supported Platforms

Works with any MCP-compatible client including Claude Desktop, VS Code (Cline), OpenWebUI, and AnythingLLM.

Related MCP server: Cobalt Strike MCP Server

Quick Start

Requirements

  • Python 3.11+

  • FastMCP 3.x (installed automatically)

  • A Ludus server running 2.0 or later

  • Ludus API key, or a JWT token for Pro/SSO deployments

Installation

# Using pipx (recommended)
pipx install git+https://github.com/tjnull/Ludus-FastMCP

# From source
git clone https://github.com/tjnull/Ludus-FastMCP
cd Ludus-FastMCP
pip install -e .

Setup

Run the interactive setup wizard:

ludus-fastmcp --setup

The wizard configures API credentials, tests connectivity, and generates MCP client configuration files.

For manual configuration options, see the Configuration Guide.

Usage

MCP Server (ludus-fastmcp)

ludus-fastmcp --setup          # Interactive setup wizard
ludus-fastmcp --list-tools     # List all 231 available tools
ludus-fastmcp --version        # Display version information
ludus-fastmcp                  # Start MCP server
ludus-fastmcp --daemon         # Run as background service

Client CLI (ludus-ai)

ludus-ai setup-llm                    # Configure local LLM (Ollama)
ludus-ai install anythingllm          # Install AnythingLLM interface
ludus-ai tool list-tools              # List available tools
ludus-ai tool call-tool <name>        # Execute tools directly

Example Interactions

Once connected to an MCP client, interact with your Ludus environment:

Show my current range status
Deploy an Active Directory lab with Wazuh monitoring
Create a snapshot named "pre-attack" for all VMs
Build a lab with 2 domain controllers and 5 workstations
Create a blueprint from my current range and share it with the red-team group
Show system diagnostics and storage usage
List all groups and their members

Examples of using Ludus-FastMCP with grok code through Opencode.

img

img

img

img

Documentation

Document

Description

Getting Started

Installation, setup, and first deployment

Configuration

Environment variables and MCP client setup

Tools Reference

Complete documentation for all 231 tools

Scenarios

Pre-built deployment scenarios

Troubleshooting

Common issues and solutions

Safety

Safety features and best practices

Ludus Server Requirements

This release speaks the Ludus 2.x API only. Every request goes to /api/v2; there is no v1 code path left to fall back to.

On the first call the client asks the server for its version and refuses to continue if it does not answer as a 2.x server, so a mismatch surfaces once, up front, instead of as a puzzling 404 from whichever tool you happened to run:

https://ludus.example:8080 does not serve the Ludus 2.x API
(GET /api/v2/ returned HTTP 404). This release requires Ludus 2.0 or later;
upgrade the server, or pin ludus-fastmcp to a 1.x release for a Ludus 1.x server.

Set LUDUS_API_VERSION=v2 to assert the version yourself and skip that check (it saves one request per session). LUDUS_API_VERSION=v1 is rejected at startup rather than silently ignored.

Still on Ludus 1.x?

Pin an older release:

pipx install "git+https://github.com/tjnull/Ludus-FastMCP@v1.0.0"

Upgrading the server is the better path: blueprints, content sources, groups, quotas, deployment log history and VM console access do not exist in the 1.x API at all.

Plugin-gated features

Some Ludus capabilities ship as server plugins that may not be loaded on a given install. Quotas and auto-shutdown are the common examples. When a plugin is absent, the Ludus API answers with HTTP 404 even though the request was correct.

Rather than reporting that as a missing endpoint, those tools return a clear result so an AI assistant does not go hunting for a nonexistent bug:

{
  "available": false,
  "feature": "Quotas",
  "error": "Quotas is not available on this Ludus server.",
  "reason": "This capability is provided by a Ludus plugin that is not loaded on the server.",
  "hint": "The request was well-formed. Do not retry or try alternative endpoints."
}

Endpoints a server does not implement at all (HTTP 501, such as /range/sshconfig on some builds) are reported the same way, with an explicit note that retrying will not help.

Resources

Resource

Link

Ludus Documentation

docs.ludus.cloud

Ludus API Reference

api-docs.ludus.cloud

Ludus GitHub

github.com/badsectorlabs/ludus

FastMCP Framework

gofastmcp.com

MCP Specification

modelcontextprotocol.io

Support

License

This project is licensed under the MIT License. See LICENSE for details.

Disclaimer

This software is intended for authorized security testing, educational purposes, and research in controlled environments. Users are responsible for compliance with applicable laws and organizational policies. The authors make no warranties and assume no liability for use or misuse of this software.

Acknowledgments

  • Ludus by Bad Sector Labs

  • FastMCP, and the Model Context Protocol community.

Credits

  • @LouDeter - MCP request/response logging middleware and log-file support (PR #8)

Available Tools

157 tools
abort_and_remove_rangeA

Abort any active deployment and then remove the range.

This is a convenience function that combines abort_range_deployment() and delete_range(). Equivalent to running:

  1. ludus range abort

  2. ludus rm (with confirmation)

Args: confirm: Confirmation flag (must be True to proceed) user_id: Optional user ID (admin only)

Returns: Combined abort and deletion results

Example: # Abort and remove current user's range result = await abort_and_remove_range(confirm=True)

Inputs: confirm, user_id. Returns: object

abort_range_deploymentA

Abort a range deployment.

Stops an active deployment. Use this before deleting a range that is currently deploying. After aborting, you can resume the deployment using deploy_range() with specific tags.

Equivalent to: ludus range abort

Args: user_id: Optional user ID (admin only)

Returns: Abort result

Example Workflow - Abort and Resume: # 1. Abort the deployment result = await abort_range_deployment()

# 2. Check what tags are available
tags = await get_range_tags()

# 3. Resume from where it stopped
deploy_range(tags="user,domain")

Note: After aborting, you can also: - Delete the range: delete_range(confirm=True) - Abort and delete: abort_and_remove_range(confirm=True) - Resume deployment: deploy_range(tags="...")

Inputs: user_id. Returns: object

abort_template_buildC

Abort a template build.

Args: template_id: Template ID user_id: Optional user ID (admin only)

Returns: Abort result

Inputs: template_id (required), user_id. Returns: object

add_templateC

Add a new template to the system.

Args: name: Template name url: Template URL or image source description: Optional template description user_id: Optional user ID (admin only)

Returns: Template addition result

Inputs: name (required), url (required), description, user_id. Returns: object

add_userB

Add a new user to the Ludus system.

Args: username: Username for the new user password: Password for the new user is_admin: Whether the user should have admin privileges proxmox_username: Optional Proxmox username for the user

Returns: Created user information

Inputs: username (required), password (required), is_admin, proxmox_username. Returns: object

apply_adversary_profileA

Apply adversary profile to inject realistic vulnerabilities for red team training.

This tool transforms an existing Ludus configuration by injecting educational vulnerabilities that simulate real-world security weaknesses. Perfect for:

  • Red team training and practice

  • Security testing scenarios

  • Learning exploitation techniques

  • Purple team exercises

Args: config: The Ludus range configuration to transform (dict with 'ludus' key) threat_level: Level of vulnerabilities to inject - "low": Basic weaknesses (weak passwords, open shares) - "medium": AD attacks (Kerberoasting, AS-REP roasting, weak GPO) - "high": Advanced attacks (unconstrained delegation, certificate vulns) target_vms: Optional list of specific VM hostnames to target (None = all VMs) include_documentation: Generate educational docs explaining vulnerabilities

Returns: Dictionary containing: - status: "success" - profile_type: "adversary" - threat_level: The applied threat level - modified_config: Transformed Ludus configuration - vulnerability_injections: List of injected vulnerabilities - vulnerabilities_count: Total number of vulnerabilities - affected_vms: List of VMs that were modified - documentation: Educational documentation (if requested) - warnings: Important safety warnings - next_steps: What to do next

Examples: # Apply medium-level vulnerabilities to all VMs result = await apply_adversary_profile( config=my_range_config, threat_level="medium" )

# Apply high-level vulnerabilities only to domain controllers
result = await apply_adversary_profile(
    config=my_range_config,
    threat_level="high",
    target_vms=["DC01", "DC02"]
)

# Apply low-level vulnerabilities without documentation
result = await apply_adversary_profile(
    config=my_range_config,
    threat_level="low",
    include_documentation=False
)

Vulnerability Categories: Active Directory: - Weak domain passwords - Kerberoasting opportunities - AS-REP roasting - Unconstrained delegation - DCSyn rights misconfigurations - Certificate Services vulnerabilities

Windows Security:
    - Weak local administrator passwords
    - Unquoted service paths
    - Weak ACLs and permissions
    - AlwaysInstallElevated
    - Cached credentials

Network Security:
    - Open SMB shares
    - Exposed RDP services
    - LLMNR poisoning opportunities
    - Weak network segmentation

Notes: ⚠️ These vulnerabilities are for EDUCATIONAL PURPOSES ONLY ⚠️ Deploy ONLY in isolated lab environments ⚠️ NEVER expose these systems to production or the internet

The modified configuration uses Ansible roles to implement vulnerabilities: - ludus_ad_weak_passwords - ludus_ad_kerberoast - ludus_ad_asreproast - ludus_ad_unconstrained_delegation - ludus_weak_local_admin - ludus_unquoted_service_paths - ludus_open_shares

Inputs: config (required), threat_level, target_vms, include_documentation.

apply_defender_profileA

Apply defender profile to add monitoring and detection capabilities for blue team training.

This tool enhances an existing Ludus configuration with comprehensive security monitoring, logging, and detection capabilities. Perfect for:

  • Blue team training and SOC practice

  • SIEM deployment and configuration

  • Threat hunting exercises

  • Purple team defensive exercises

  • Incident detection and response training

Args: config: The Ludus range configuration to enhance (dict with 'ludus' key) monitoring_level: Level of monitoring to deploy - "basic": SIEM agent + event forwarding - "comprehensive": + Sysmon/Auditd + PowerShell logging - "advanced": + EDR, process monitoring, FIM, network monitoring siem_type: SIEM platform to deploy - "wazuh": Wazuh (open source SIEM/XDR) - "splunk": Splunk Enterprise - "elastic": Elastic Stack (ELK) detection_focus: Optional list of specific attack types to focus detection on (e.g., ["kerberos_attacks", "lateral_movement", "credential_access"])

Returns: Dictionary containing: - status: "success" - profile_type: "defender" - monitoring_level: The applied monitoring level - siem_type: The SIEM platform used - modified_config: Enhanced Ludus configuration - monitoring_enhancements: List of added monitoring capabilities - enhancements_count: Total number of enhancements - siem_added: Whether SIEM server was added - detection_rules: List of detection rules configured - affected_vms: List of VMs that were enhanced - documentation: Implementation and usage documentation - next_steps: What to do after deployment

Examples: # Add comprehensive Wazuh monitoring to all VMs result = await apply_defender_profile( config=my_range_config, monitoring_level="comprehensive", siem_type="wazuh" )

# Add advanced monitoring with Splunk
result = await apply_defender_profile(
    config=my_range_config,
    monitoring_level="advanced",
    siem_type="splunk"
)

# Focus detection on Kerberos attacks and lateral movement
result = await apply_defender_profile(
    config=my_range_config,
    monitoring_level="comprehensive",
    siem_type="wazuh",
    detection_focus=["kerberos_attacks", "lateral_movement"]
)

Monitoring Capabilities: Windows Monitoring: - SIEM agent (Wazuh/Splunk/Elastic) - Event log forwarding - Sysmon (process, network, file monitoring) - PowerShell script block logging - EDR capabilities (advanced level) - Process monitoring (advanced level) - File integrity monitoring (advanced level)

Linux Monitoring:
    - SIEM agent (Wazuh/Splunk/Elastic)
    - Syslog forwarding
    - Auditd (system call auditing)
    - OSQuery (endpoint visibility)
    - EDR capabilities (advanced level)
    - Process monitoring (advanced level)
    - File integrity monitoring (advanced level)

Network Monitoring:
    - NetFlow collection
    - Packet capture
    - Zeek network security monitor (advanced level)
    - Suricata IDS/IPS (advanced level)

Detection Rules: - Kerberoasting detection (Event ID 4769) - Lateral movement detection (PsExec, WMI) - Credential dumping (LSASS access, Mimikatz) - PowerShell obfuscation - Suspicious process execution - And more based on detection_focus

Notes: - SIEM server will be automatically added if not present - All VMs will have monitoring agents installed - Detection rules are pre-configured but customizable - Dashboard and alerting must be configured post-deployment

Inputs: config (required), monitoring_level, siem_type, detection_focus.

apply_templateC

Apply a template to a VM.

Args: vm_name: Name of the VM to apply template to template_id: Template ID to apply user_id: Optional user ID (admin only)

Returns: Template application result

Inputs: vm_name (required), template_id (required), user_id. Returns: object

auto_scalingB

Configure auto-scaling for the range.

Args: enable: Enable or disable auto-scaling min_vms: Minimum number of VMs max_vms: Maximum number of VMs scaling_policy: Scaling policy configuration user_id: Optional user ID (admin only)

Returns: Auto-scaling configuration result

Inputs: enable, min_vms, max_vms, scaling_policy, +1 more. Returns: object

batch_get_vm_statusB

Get status of multiple VMs in parallel.

Args: vm_names: List of VM names user_id: Optional user ID (admin only)

Returns: Status for each VM

Inputs: vm_names (required), user_id.

batch_power_off_hostsC

Power off multiple VMs in parallel.

Args: vm_names: List of VM names to power off user_id: Optional user ID (admin only)

Returns: Results for each VM

Inputs: vm_names (required), user_id.

batch_power_on_hostsB

Power on multiple VMs in parallel.

Args: vm_names: List of VM names to power on user_id: Optional user ID (admin only)

Returns: Results for each VM

Example: result = await batch_power_on_hosts( vm_names=["DC01", "WS01", "WS02"] )

Inputs: vm_names (required), user_id.

batch_remove_snapshotsB

Remove snapshots from multiple VMs in parallel.

Args: vm_names: List of VM names snapshot_name: Name of snapshot to remove user_id: Optional user ID (admin only)

Returns: Results for each VM

Inputs: vm_names (required), snapshot_name (required), user_id.

batch_rollback_snapshotsA

Rollback multiple VMs to a snapshot in parallel.

Args: vm_names: List of VM names to rollback snapshot_name: Name of snapshot to rollback to user_id: Optional user ID (admin only)

Returns: Results for each VM including successes and failures

Inputs: vm_names (required), snapshot_name (required), user_id.

batch_snapshot_hostsA

Create snapshots for multiple VMs in parallel.

This is much faster than creating snapshots sequentially, especially for large numbers of VMs.

Args: vm_names: List of VM names to snapshot snapshot_name: Name for the snapshots description: Optional description for snapshots user_id: Optional user ID (admin only)

Returns: Results for each VM including successes and failures

Example: vm_names = ["DC01", "WS01", "WS02"] result = await batch_snapshot_hosts( vm_names=vm_names, snapshot_name="before-attack", description="Clean state before penetration test" )

Inputs: vm_names (required), snapshot_name (required), description, user_id.

build_container_based_templateA

Build a custom container-based template for applications.

This tool creates templates specifically designed to run Docker containers, perfect for deploying applications like Splunk, Wazuh, Grafana, etc.

Args: name: Template name (e.g., "ubuntu-splunk-server") base_os: Base OS (e.g., "ubuntu-22.04", "debian-12", "rocky-9") containers: List of container configurations with image, ports, volumes, env description: Template description

Returns: Template creation result with docker-compose configuration

Example: # Create a Splunk container template result = await create_container_template( name="ubuntu-splunk-server", base_os="ubuntu-22.04", containers=[{ "image": "splunk/splunk:latest", "ports": ["8000:8000", "8088:8088", "9997:9997"], "environment": { "SPLUNK_START_ARGS": "--accept-license", "SPLUNK_PASSWORD": "changeme123!" } }], description="Ubuntu 22.04 with Splunk container" )

Inputs: name (required), base_os (required), containers (required), description.

build_range_from_descriptionA

Build a custom range configuration from a natural language description.

This tool intelligently parses your description and automatically builds a complete range configuration with appropriate VMs, network rules, and SIEM.

Args: description: Natural language description of the desired range/scenario siem_type: SIEM type to include (wazuh, splunk, elastic, security-onion, none) resource_profile: Resource allocation profile (minimal, recommended, maximum) include_siem: Whether to include SIEM monitoring

Returns: Complete range configuration ready for deployment

Examples: # Simple AD lab "Create an Active Directory lab with 2 workstations and a file server"

# Red team lab
"Build a red team lab with a domain controller, 3 workstations, SQL server, and Kali attacker"

# Web application lab
"Create a web application testing lab with a web server, database, and Kali attacker"

# Complex enterprise
"Build an enterprise environment with AD domain corp.local, 5 workstations, file server, Exchange server, and Wazuh monitoring"

The tool automatically: - Detects AD/domain requirements and adds domain controller - Adds appropriate number of workstations - Adds servers based on keywords (file server, SQL, web, Exchange) - Adds Kali attacker if mentioned - Configures network rules for attacker access - Adds SIEM monitoring if requested

Inputs: description (required), siem_type, resource_profile, include_siem.

build_range_from_promptB

Build a range configuration from a natural language prompt.

Args: prompt: Natural language description of desired range auto_deploy: Automatically deploy after building configuration user_id: Optional user ID (admin only)

Returns: Generated configuration and deployment result if auto_deploy=True

Inputs: prompt (required), auto_deploy, user_id.

build_range_from_scratchA

Build a completely custom range configuration from scratch.

This tool allows you to create a range configuration with full control over every VM and network rule, not based on any existing scenario.

Args: vms: List of VM configurations (each with vm_name, hostname, template, vlan, ip_last_octet, ram_gb, cpus) network_rules: Optional list of network rules inter_vlan_default: Default inter-VLAN policy ("REJECT" or "ACCEPT") include_siem: Whether to automatically add a SIEM server siem_type: SIEM type if include_siem is True

Returns: Complete range configuration ready for deployment

Example: # Build a custom 3-VM pentesting lab from scratch vms = [ { "vm_name": "target-web-server", "hostname": "web01", "template": "ubuntu-22.04-template", "vlan": 10, "ip_last_octet": 10, "ram_gb": 4, "cpus": 2 }, { "vm_name": "target-database", "hostname": "db01", "template": "ubuntu-22.04-template", "vlan": 10, "ip_last_octet": 11, "ram_gb": 8, "cpus": 4 }, { "vm_name": "attacker-kali", "hostname": "kali", "template": "kali-x64-desktop-template", "vlan": 99, "ip_last_octet": 1, "ram_gb": 8, "cpus": 4 } ]

network_rules = [
    {
        "name": "Allow attacker to targets",
        "vlan_src": 99,
        "vlan_dst": 10,
        "protocol": "all",
        "ports": "all",
        "action": "ACCEPT"
    }
]

result = await build_range_from_scratch(
    vms=vms,
    network_rules=network_rules,
    include_siem=True,
    siem_type="wazuh"
)

Inputs: vms (required), network_rules, inter_vlan_default, include_siem, +1 more.

build_range_from_skeletonA

Build a complete range configuration starting from a skeleton.

Combines the power of skeleton templates with custom modifications. Start with a base skeleton and add/remove VMs as needed.

Args: skeleton_name: Base skeleton ("basic-ad", "enterprise-ad", etc.) add_vms: List of VM skeleton names to add (e.g., ["sql-server", "exchange"]) remove_vms: List of VM hostnames to remove domain: Custom domain name for AD labs siem_type: SIEM type (wazuh, splunk, elastic) include_siem: Whether to include SIEM include_attacker: Whether to include attacker VM

Returns: Complete customized range configuration

Example: # Start with basic AD and add more servers config = await build_range_from_skeleton( skeleton_name="basic-ad", add_vms=["sql-server", "file-server", "ca"], domain="mycorp.local", siem_type="splunk" )

# Enterprise AD without Exchange
config = await build_range_from_skeleton(
    skeleton_name="enterprise-ad",
    remove_vms=["ex01"]
)

Inputs: skeleton_name (required), add_vms, remove_vms, domain, +3 more.

build_templateC

Build a template.

Args: template_id: Template ID to build force: Force rebuild even if template exists user_id: Optional user ID (admin only)

Returns: Build initiation result

Inputs: template_id (required), force, user_id. Returns: object

bulk_vm_operationsC

Perform bulk operations on multiple VMs.

Args: operation: Operation to perform (power_on, power_off, snapshot, delete) vm_names: Optional list of VM names (defaults to all VMs) parameters: Optional operation-specific parameters user_id: Optional user ID (admin only)

Returns: Bulk operation results

Inputs: operation (required), vm_names, parameters, user_id. Returns: object

capture_network_trafficB

Capture network traffic on a VM.

Args: vm_name: VM name to capture traffic from interface: Network interface to capture on duration: Capture duration in seconds filter: Optional BPF filter expression user_id: Optional user ID (admin only)

Returns: Traffic capture result with download link

Inputs: vm_name (required), interface, duration, filter, +1 more. Returns: object

check_role_installedA

Check if a specific Ansible role is installed.

Uses the ludus CLI with --url when available for reliable remote access. Falls back to HTTP API if CLI is not available. No SSH required.

Args: role_name: Name of the role to check (e.g., "ludus-ad-content", "badsectorlabs.ludus_adcs")

Returns: Dictionary indicating if the role is installed

Example: # Check if a role is installed result = await check_role_installed(role_name="ludus-ad-content")

# If not installed, use install_role() to install it
if not result.get("installed"):
    await install_role(role_name="ludus-ad-content")

Inputs: role_name (required).

cleanup_old_rangesA

Delete all ranges EXCEPT those belonging to specified users.

Useful for cleaning up test/temporary ranges while keeping production ones.

Args: keep_user_ids: List of user IDs whose ranges should be KEPT (not deleted) confirm: Must be set to True to actually delete (safety measure)

Returns: Deletion results

Example: # Keep ranges for 'admin' and 'tjnull', delete all others result = await cleanup_old_ranges( keep_user_ids=["admin", "tjnull"], confirm=True )

Safety: - Requires confirm=True to prevent accidental deletion - Shows preview of what will be deleted - Explicitly protects specified user ranges

Inputs: keep_user_ids (required), confirm.

clear_range_accessC

Clear all range access permissions.

Args: user_id: Optional user ID (admin only)

Returns: Clear result

Inputs: user_id. Returns: object

clone_and_modify_scenarioA

Clone an existing scenario and modify it to create a new custom scenario.

This is useful for creating variations of existing scenarios (e.g., "ad-basic" with more workstations, or "web-basic" with different applications).

Args: scenario_key: Scenario to clone (e.g., "ad-basic", "kerberoasting") modifications: Modifications to apply (same as create_custom_range_from_scenario) new_name: Name for the new custom scenario siem_type: SIEM type to use

Returns: New scenario configuration with modifications

Example: # Clone "ad-basic" and add more workstations modifications = { "add_vms": [ { "vm_name": "win11-workstation-3", "hostname": "WIN11-03", "template": "win11-22h2-x64-enterprise-template", "vlan": 10, "ip_last_octet": 23, "ram_gb": 8, "cpus": 4, "domain": {"fqdn": "ludus.domain", "role": "member"} }, { "vm_name": "win11-workstation-4", "hostname": "WIN11-04", "template": "win11-22h2-x64-enterprise-template", "vlan": 10, "ip_last_octet": 24, "ram_gb": 8, "cpus": 4, "domain": {"fqdn": "ludus.domain", "role": "member"} } ] }

result = await clone_and_modify_scenario(
    scenario_key="ad-basic",
    modifications=modifications,
    new_name="ad-basic-extended",
    siem_type="wazuh"
)

Inputs: scenario_key (required), modifications (required), new_name (required), siem_type.

clone_rangeC

Clone the current range to another user.

Args: target_user_id: User ID to clone range to include_snapshots: Whether to include snapshots in clone user_id: Optional user ID (admin only)

Returns: Clone operation result

Inputs: target_user_id (required), include_snapshots, user_id. Returns: object

compliance_checkC

Check compliance against security framework.

Args: framework: Security framework to check against (nist, pci, iso27001) user_id: Optional user ID (admin only)

Returns: Compliance check results

Inputs: framework, user_id. Returns: object

configure_ssh_role_installationA

Configure SSH access for automatic role installation on Ludus server.

This allows the MCP server to automatically clone and install directory-based roles (like ludus-ad-content) directly on the Ludus server via SSH, without manual setup.

Security Note: SSH access requires appropriate permissions. Use SSH keys when possible.

Args: ssh_host: SSH hostname or IP address of the Ludus server ssh_user: SSH username (default: "root") ssh_key_path: Path to SSH private key file (preferred over password) ssh_password: SSH password (less secure, only use if key is not available) allow_ssh_install: Enable automatic SSH-based installation (default: True)

Returns: Configuration result with status

Example: # Configure with SSH key (recommended) result = await configure_ssh_role_installation( ssh_host="192.168.10.3", ssh_user="root", ssh_key_path="~/.ssh/id_rsa", allow_ssh_install=True )

# Configure with password (less secure)
result = await configure_ssh_role_installation(
    ssh_host="192.168.10.3",
    ssh_user="root",
    ssh_password="your-password",
    allow_ssh_install=True
)

Inputs: ssh_host (required), ssh_user, ssh_key_path, ssh_password, +1 more.

create_container_templateC

Create a container-based template.

Args: name: Name for the container template base_os: Base OS (e.g., "ubuntu-22.04", "debian-12") containers: List of container configurations description: Optional description user_id: Optional user ID (admin only)

Returns: Container template creation result

Inputs: name (required), base_os (required), containers (required), description, +1 more. Returns: object

create_custom_os_templateA

Create a custom OS template with specific packages and configuration.

This tool allows you to create custom Ludus templates from ANY operating system by providing an ISO URL. The OS type can be auto-detected from the ISO URL/filename, or explicitly specified. Supports Linux, Windows, BSD, macOS, and any other OS.

Args: name: Template name (e.g., "ubuntu-22.04-pentesting") os_type: OS type ("linux", "windows", "bsd", "macos") - auto-detected if None os_version: OS version (e.g., "22.04", "2022", "11") - used for default ISO lookup iso_url: Custom ISO URL (required if os_version not in defaults, supports ANY ISO) iso_checksum: Optional ISO checksum for verification (sha256) iso_checksum_type: Checksum type (default: "sha256") packages: List of packages to install (e.g., ["docker.io", "nginx", "postgresql"]) ansible_roles: List of Ansible roles to apply (e.g., ["geerlingguy.docker"]) description: Template description disk_size: Disk size (default: "40G") memory: Memory in MB (default: 4096) cores: CPU cores (default: 2) ensure_template_roles: Automatically install template roles (CommandoVM, FlareVM, REMnux) if needed auto_detect_os: Auto-detect OS type from ISO URL (default: True)

Returns: Template creation result with file paths and instructions

Example: # Create a custom Ubuntu pentesting template result = await create_custom_os_template( name="ubuntu-22.04-pentesting", os_type="linux", os_version="22.04", packages=["nmap", "metasploit-framework", "burpsuite"], description="Custom Ubuntu 22.04 with pentesting tools" )

# Create template from ANY ISO (OS auto-detected)
result = await create_custom_os_template(
    name="custom-os",
    iso_url="https://example.com/custom-linux.iso",
    iso_checksum="abc123...",
    description="Custom OS from ISO - OS type auto-detected"
)

# Create template for any operating system
result = await create_custom_os_template(
    name="arch-linux",
    iso_url="https://archlinux.org/iso/latest/archlinux-x86_64.iso",
    description="Arch Linux template"
)

Inputs: name (required), os_type, os_version, iso_url, +10 more.

create_custom_range_from_scenarioA

Create a custom range configuration based on an existing scenario.

This tool takes an existing scenario and allows you to customize it with your own modifications (add/remove VMs, change specs, modify network rules).

Args: scenario_key: Base scenario to start from (e.g., "ad-basic", "web-basic", "kerberoasting") customizations: Dictionary of customizations to apply siem_type: SIEM type to use ("wazuh", "splunk", "elastic", "security-onion", "none")

Returns: Customized range configuration ready for deployment

Customization options: - add_vms: List of VM configurations to add - remove_vms: List of VM names to remove - modify_vms: Dictionary of VM name to modifications - add_network_rules: List of network rules to add - modify_range_settings: Range-level settings to modify

Example: # Start with basic AD scenario and customize customizations = { "add_vms": [{ "vm_name": "my-web-server", "hostname": "webserver01", "template": "ubuntu-22.04-template", "vlan": 10, "ip_last_octet": 50, "ram_gb": 4, "cpus": 2 }], "modify_vms": { "ad-dc-win2022-server-x64": { "ram_gb": 16, # Increase RAM "cpus": 8 # Increase CPUs } }, "add_network_rules": [{ "name": "Allow web traffic", "vlan_src": 99, "vlan_dst": 10, "protocol": "tcp", "ports": 80, "action": "ACCEPT" }] } result = await create_custom_range_from_scenario( scenario_key="ad-basic", customizations=customizations, siem_type="wazuh" )

Inputs: scenario_key (required), customizations (required), siem_type.

create_custom_templateB

Create a custom template from scratch.

Args: name: Name for the custom template os_type: OS type (linux, windows) os_version: OS version (e.g., "22.04", "2022") packages: List of packages to install containers: List of container configurations description: Optional description user_id: Optional user ID (admin only)

Returns: Custom template creation result

Inputs: name (required), os_type (required), os_version, packages, +3 more. Returns: object

create_deployment_pipelineC

Create a deployment pipeline with multiple stages.

Args: name: Pipeline name stages: List of pipeline stages with configurations triggers: Optional trigger conditions (schedule, webhook, etc.) user_id: Optional user ID (admin only)

Returns: Pipeline creation result

Inputs: name (required), stages (required), triggers, user_id. Returns: object

create_kali_weekly_templateA

Create a Kali Linux weekly template with automatic latest ISO detection.

Automatically fetches the latest Kali Linux weekly ISO and checksum from https://cdimage.kali.org/kali-weekly/. The ISO URL and checksum change weekly, so this tool always uses the most recent version.

Args: name: Template name (default: "kali-weekly-latest") packages: Additional packages to install (e.g., ["metasploit-framework", "burpsuite"]) ansible_roles: Ansible roles to apply description: Template description disk_size: Disk size (default: "40G") memory: Memory in MB (default: 4096) cores: CPU cores (default: 2)

Returns: Template creation result with ISO information and instructions

Example: # Create latest Kali weekly template result = await create_kali_weekly_template( name="kali-weekly-pentesting", packages=["nmap", "metasploit-framework", "burpsuite"], description="Latest Kali weekly with pentesting tools" )

Inputs: name, packages, ansible_roles, description, +3 more.

create_scenario_playbookC

Create a scenario playbook for training.

Args: scenario_key: Scenario identifier title: Playbook title description: Playbook description objectives: Learning objectives steps: List of playbook steps with instructions user_id: Optional user ID (admin only)

Returns: Created playbook information

Inputs: scenario_key (required), title (required), description (required), objectives (required), +2 more. Returns: object

delete_rangeA

Delete the entire range.

Permanently removes the range and all associated VMs, snapshots, and data.

Important: If a deployment is in progress, abort it first with abort_range_deployment().

Args: confirm: Confirmation flag (must be True to proceed) user_id: Optional user ID (admin only)

Returns: Range deletion result

Example: # Delete current user's range (after aborting if needed) result = await delete_range(confirm=True)

Workflow: 1. If deployment is active: abort_range_deployment() 2. Then delete: delete_range(confirm=True)

Inputs: confirm, user_id. Returns: object

delete_range_by_userA

Delete a specific user's range (requires confirmation).

This tool allows you to selectively delete a single range by user ID, rather than destroying all ranges. Requires explicit confirmation.

Args: user_id: User ID whose range to delete confirm: Must be set to True to actually delete (safety measure)

Returns: Deletion result with confirmation details

Example: # First, check what you're deleting range_info = await get_range_by_user(user_id="testuser")

# Then confirm deletion
result = await delete_range_by_user(
    user_id="testuser",
    confirm=True
)

Safety: - Requires confirm=True to prevent accidental deletion - Shows range details before deletion - Cannot be undone

Inputs: user_id (required), confirm.

delete_ranges_by_statusA

Delete all ranges matching a specific status (requires confirmation).

Useful for cleaning up failed deployments or test ranges.

Args: status_filter: Status to filter by (e.g., "ERROR", "FAILED", "DEPLOYING") confirm: Must be set to True to actually delete (safety measure)

Returns: Deletion results for matching ranges

Example: # Delete all ranges with ERROR status result = await delete_ranges_by_status( status_filter="ERROR", confirm=True )

Safety: - Requires confirm=True to prevent accidental deletion - Shows preview of what will be deleted - Cannot be undone

Inputs: status_filter (required), confirm.

delete_templateC

Delete a template.

Args: template_id: Template ID to delete user_id: Optional user ID (admin only)

Returns: Deletion result

Inputs: template_id (required), user_id. Returns: object

deployment_timelineC

Get deployment timeline with progress tracking.

Args: user_id: Optional user ID (admin only)

Returns: Timeline with steps and progress

Inputs: user_id. Returns: object

deploy_rangeA

Deploy a range from configuration with optional filters for resuming.

IMPORTANT: For deploying predefined scenarios (redteam-lab-lite, etc.), use deploy_scenario() or smart_deploy() instead. This tool is for:

  • Custom configurations you've built manually

  • Resuming partial deployments with tags/limit

  • Deploying after you've already set the config via update_range_config()

This tool supports both full deployments and resuming partial deployments.

Full Deployment: deploy_range(config=configuration_dict)

Resume After Pause/Abort: deploy_range(tags="user,domain") # Run specific Ansible tags only deploy_range(limit="DC*") # Deploy only to matching VMs deploy_range(tags="user", limit="WS*") # Combine filters

Common Ansible Tags: - "base": Base system configuration - "domain": Domain join operations - "user": User creation and management - "configure": General configuration - "testing": Testing configuration Use get_range_tags() to see all available tags for your range

Args: config: Range configuration (required for full deployment, optional for resume) user_id: Optional user ID (admin only) tags: Ansible tags to run (comma-separated, e.g., "user,domain") limit: Limit to VMs matching pattern (e.g., "DC*", "WS*", "*-DC01") only_roles: Limit user-defined roles (comma-separated) force: Force deployment if testing is enabled

Returns: Deployment result

Use Cases: 1. Initial deployment: deploy_range(config=my_config) 2. Resume after abort: deploy_range(tags="user,domain") 3. Re-run specific tags: deploy_range(tags="configure") 4. Fix specific VM: deploy_range(limit="DC01") 5. Update workstations only: deploy_range(limit="WS*", tags="user") 6. After role installation: deploy_range(tags="configure")

Example Workflow - Resume After Failure: 1. abort_range_deployment() # Stop the failed deployment 2. get_range_tags() # See available tags 3. deploy_range(tags="user,domain") # Resume from specific step

Inputs: config, user_id, tags, limit, +2 more. Returns: object

deploy_scenarioA

Deploy a scenario with optional SIEM integration and customization.

IMPORTANT: This tool generates a FRESH configuration for each call. Each deployment builds a new scenario from scratch - no state is reused.

NO FILE UPLOAD REQUIRED: This tool automatically generates the configuration from the scenario parameters. You do NOT need to provide a config file or manual configuration.

CUSTOMIZATION AND RANDOMIZATION:

  • Use customize=True with custom parameters to deploy a customized scenario

  • Use randomize=True to deploy a randomized version with varied users/vulnerabilities

  • All customization parameters are optional - defaults used if not specified

Recommended Workflow:

  1. Use preview_scenario() first to verify what will be deployed

  2. (Optional) Abort any existing deployment: abort_range_deployment()

  3. (Optional) Delete existing range: delete_range(confirm=True)

  4. Deploy the scenario: deploy_scenario(scenario_key='redteam-lab-lite')

  5. Monitor progress: monitor_deployment() or quick_status()

Internal Workflow:

  1. Generates fresh scenario configuration based on parameters

  2. Applies customizations or randomization if requested

  3. Sets the configuration in Ludus (via PUT /range/config)

  4. Verifies the configuration was set correctly

  5. Starts deployment (via POST /range/deploy)

  6. Generates comprehensive walkthrough

  7. Returns deployment status, VM details, and walkthrough

Available scenarios:

  • redteam-lab-lite: 5 VMs (DC, 2 workstations, file server, Kali)

  • redteam-lab-intermediate: 10 VMs (DMZ, internal network, multiple servers)

  • redteam-lab-advanced: 21 VMs (2 forests with trust, DMZ, secure zone)

  • blueteam-lab-lite: 6 VMs (SOC with SIEM, detection)

  • blueteam-lab-intermediate: 11 VMs (SOC with EDR, IDS)

  • blueteam-lab-advanced: 21 VMs (Enterprise SOC, full stack)

  • purpleteam-lab-lite: 6 VMs (Red/Blue collaborative)

  • purpleteam-lab-intermediate: 10 VMs (Purple team with EDR)

  • purpleteam-lab-advanced: 13 VMs (Full SOC + adversary emulation)

  • malware-re-lab-lite: 3 VMs (Basic malware analysis)

  • malware-re-lab-intermediate: 7 VMs (Pro malware lab)

  • malware-re-lab-advanced: 18 VMs (Enterprise malware research)

  • wireless-lab: 2 VMs (WiFi pentesting)

Args: scenario_key: Scenario identifier (e.g., 'redteam-lab-lite') user_id: Optional user ID (admin only) ensure_roles: Ensure required Ansible roles are installed siem_type: SIEM type to include (wazuh, splunk, elastic, security-onion, none) resource_profile: Resource allocation profile (minimal, recommended, maximum) customize: Enable customization mode (use provided customizations) randomize: Enable randomization mode (generate random customizations) custom_users: List of custom user dicts with keys: username, password, display_name, groups (list), department (optional), title (optional), etc. vulnerability_config: Dict with keys like esc1_enabled, esc2_enabled, open_shares, etc. network_customizations: Dict with vlan_changes, additional_rules, remove_rules, etc. vm_customizations: Dict with vm_count_overrides, additional_vms, remove_vms, etc.

Returns: Deployment result with scenario details, VM list, deployment status, and walkthrough

Examples: # Simple deployment (default) deploy_scenario(scenario_key='redteam-lab-lite', siem_type='none')

# Randomized deployment
deploy_scenario(scenario_key='redteam-lab-lite', randomize=True)

# Custom users deployment
deploy_scenario(
    scenario_key='redteam-lab-lite',
    customize=True,
    custom_users=[
        {
            "username": "admin.user",
            "password": "CustomPass123!",
            "display_name": "Admin User",
            "groups": ["Domain Users", "Domain Admins"],
            "department": "IT"
        }
    ]
)

# Custom vulnerabilities
deploy_scenario(
    scenario_key='redteam-lab-lite',
    customize=True,
    vulnerability_config={
        "esc1_enabled": True,
        "esc8_enabled": True,
        "open_shares": True
    }
)

Natural Language Translation:

  • "Make a custom range using redteam-lab-lite" → customize=True

  • "Randomize redteam-lab-lite" → randomize=True

  • "Deploy with different users" → customize=True, custom_users=[...]

Note: For automated deployments with validation and monitoring, consider using smart_deploy() instead, which handles the full workflow.

Inputs: scenario_key (required), user_id, ensure_roles, siem_type, +7 more. Returns: object

diagnose_network_issuesC

Diagnose network connectivity issues.

Args: user_id: Optional user ID (admin only)

Returns: Network diagnostics report

Inputs: user_id. Returns: object

ensure_scenario_rolesA

Ensure all required roles for a scenario are installed, installing missing ones automatically.

This is the recommended MCP tool to use before deploying a scenario. It will:

  1. Check which roles are required for the scenario

  2. Check which roles are already installed

  3. Automatically install missing Galaxy roles (if auto_install=True)

  4. Automatically clone and install directory-based roles via SSH (if SSH configured)

  5. Report which roles need manual installation (if SSH not configured)

MCP Workflow:

  • Use ensure_scenario_roles() before deploying to ensure all roles are ready

  • Configure SSH access with configure_ssh_role_installation() for automatic directory-based role installation

  • Use install_role() to install individual roles as needed

Args: scenario_key: Scenario identifier (e.g., "redteam-lab-intermediate") siem_type: SIEM type if scenario uses SIEM (wazuh, splunk, elastic, security-onion, none) auto_install: Automatically install missing roles (default: True)

Returns: Dictionary with installation status for all required roles

Example: # Ensure all roles are installed before deployment result = await ensure_scenario_roles( scenario_key="redteam-lab-intermediate", siem_type="none", auto_install=True )

# Check status without installing
result = await ensure_scenario_roles(
    scenario_key="redteam-lab-intermediate",
    auto_install=False
)

Inputs: scenario_key (required), siem_type, auto_install.

explain_range_design_decisionsA

Explain the design decisions and best practices for a range configuration request.

This tool helps users understand WHY certain choices are made when building a cyber range, providing educational value beyond just generating configs.

Args: prompt: The range description or scenario you want explained

Returns: Dictionary with: - design_rationale: Why specific VMs/networks are suggested - best_practices: Industry best practices applied - learning_objectives: What skills can be practiced - alternative_approaches: Other ways to achieve similar goals - security_considerations: Security implications of design choices

Examples: # Understand AD design result = await explain_range_design_decisions( "Why do I need a domain controller AND workstations " "for an AD lab?" )

# Network segmentation rationale
result = await explain_range_design_decisions(
    "Explain why the attacker VM should be on a separate VLAN"
)

# SIEM placement
result = await explain_range_design_decisions(
    "Where should I place the SIEM server and why?"
)

Inputs: prompt (required).

export_lab_guideC

Export lab guide for training purposes.

Args: scenario_key: Optional scenario key (defaults to current deployment) format: Export format (markdown, html, pdf) include_solutions: Include solution steps user_id: Optional user ID (admin only)

Returns: Lab guide content or download link

Inputs: scenario_key, format, include_solutions, user_id. Returns: object

export_metricsC

Export metrics data.

Args: format: Export format (json, csv, prometheus) start_time: Optional start time for metrics (ISO format) end_time: Optional end time for metrics (ISO format) user_id: Optional user ID (admin only)

Returns: Exported metrics data

Inputs: format, start_time, end_time, user_id. Returns: object

export_range_backupC

Export range backup.

Args: include_vms: Include VM disk images in backup include_config: Include configuration in backup user_id: Optional user ID (admin only)

Returns: Backup export result with download link

Inputs: include_vms, include_config, user_id. Returns: object

export_range_config_to_yamlA

Export a range configuration to a YAML file for download.

This tool exports range configurations to YAML format that users can download and use with Ludus. The YAML content is provided in the response for easy copying or downloading through the chat interface.

Args: config: Range configuration dictionary filename: Optional filename (defaults to /tmp/ludus-range-config.yml) include_full_content: Whether to include full YAML content in response (default: True)

Returns: File path, YAML content, and download instructions

Example: # Export custom config to file with full content result = await export_range_config_to_yaml( config=my_config, filename="/tmp/my-custom-range.yml", include_full_content=True )

# The result includes the full YAML content that users can copy/download

Inputs: config (required), filename, include_full_content.

find_range_by_vm_nameA

Find which range contains a specific VM by name.

Args: vm_name: Name of the VM to search for

Returns: Range information containing the VM, or None if not found

Example: # Find which range contains the VM 'DC01' result = await find_range_by_vm_name(vm_name="DC01")

Inputs: vm_name (required).

generate_config_from_descriptionA

Generate a complete Ludus range configuration from natural language description.

This is an enhanced AI-powered version of build_range_from_description that provides:

  • Better natural language understanding beyond simple regex matching

  • Intelligent clarification requests for ambiguous or incomplete inputs

  • Multiple configuration suggestions and alternatives

  • Educational explanations of design decisions and best practices

Args: description: Natural language description of the desired cyber range. Can be conversational and doesn't need to follow strict formatting. include_suggestions: Whether to include enhancement suggestions (default: True) include_clarifications: Whether to request clarifications for missing info (default: True)

Returns: Dictionary containing: - status: "success" or "needs_clarification" - configuration: Complete Ludus YAML configuration dict - metadata: VM count, complexity, resource profile info - parsed_requirements: Structured understanding of the prompt - suggestions: Optional enhancements (if include_suggestions=True) - educational_notes: Explanations of design choices - clarifications: Questions to ask if critical info missing - next_steps: What to do with the generated config

Examples: # Simple Active Directory lab result = await generate_config_from_description( "I need an Active Directory lab with a domain controller " "and 3 Windows 10 workstations for practicing lateral movement" )

# Red team training environment
result = await generate_config_from_description(
    "Build a red team training lab with:
    - AD domain corp.local
    - 2 domain controllers for redundancy
    - 5 workstations (Windows 10 and 11)
    - SQL server with database
    - File server with shares
    - Exchange server for email
    - Kali Linux attacker machine
    - Wazuh SIEM for blue team practice"
)

# Web application security lab
result = await generate_config_from_description(
    "Create a web app pentest lab with Ubuntu web server, "
    "MySQL database, and Kali for attacking. Include Splunk "
    "for monitoring the attacks."
)

# Blue team SOC lab
result = await generate_config_from_description(
    "I want to build a SOC training lab with multiple endpoints "
    "to monitor, a SIEM (preferably Wazuh), and an attacker VM "
    "to simulate threats"
)

Notes: - If the description is ambiguous or missing critical info, status will be "needs_clarification" with specific questions - You can then provide answers and call this function again with more details added to the description - The generated config is ready to deploy with deploy_range() - Consider reviewing suggestions for additional capabilities

Inputs: description (required), include_suggestions, include_clarifications.

generate_range_documentationC

Generate comprehensive documentation for the range.

Args: format: Documentation format (markdown, html, pdf) include_network_diagram: Include network topology diagram include_credentials: Include credentials in documentation user_id: Optional user ID (admin only)

Returns: Documentation content or download link

Inputs: format, include_network_diagram, include_credentials, user_id. Returns: object

get_attack_path_documentationC

Generate attack path documentation for a scenario.

Args: scenario_key: Optional scenario key (defaults to current deployment) user_id: Optional user ID (admin only)

Returns: Attack path documentation with techniques and mitigations

Inputs: scenario_key, user_id. Returns: object

get_common_container_configsA

Get pre-configured container definitions for common applications.

Returns a dictionary of common application containers (Splunk, Wazuh, ELK, Nginx, PostgreSQL, Redis, Grafana) that can be used with create_container_template.

Returns: Dictionary of application name to container configuration

Example: # Get all common container configs configs = await get_common_container_configs()

# Use Splunk config to create template
splunk_config = configs["splunk"]
result = await create_container_template(
    name="ubuntu-splunk",
    base_os="ubuntu-22.04",
    containers=[splunk_config]
)

Inputs: no named parameters.

get_common_galaxy_rolesA

Get a list of commonly used Ansible Galaxy roles for Ludus scenarios.

Returns a curated list of Galaxy roles that are frequently used in security lab scenarios, along with their descriptions and example usage.

Returns: Dictionary of common roles organized by category

Example: roles = await get_common_galaxy_roles() # Then install what you need: await install_galaxy_role(role_name="geerlingguy.docker")

Inputs: no named parameters.

get_common_iso_urlsA

Get common ISO download URLs for popular operating systems.

Returns a reference of ISO download URLs for various operating systems that can be used with create_custom_os_template.

Returns: Dictionary of OS names to ISO download information

Example: # Get common ISO URLs isos = await get_common_iso_urls() # Use one of the URLs result = await create_custom_os_template( name="arch-linux", iso_url=isos["arch_linux"]["url"], description="Arch Linux template" )

Inputs: no named parameters.

get_container_configC

Get configuration for a common container.

Args: container_name: Container name

Returns: Container configuration

Inputs: container_name (required). Returns: object

get_cost_estimationC

Get cost estimation for the range.

Args: user_id: Optional user ID (admin only)

Returns: Cost estimation based on resource usage

Inputs: user_id. Returns: object

get_current_range_config_for_downloadA

Get the current range configuration and prepare it for download.

This tool retrieves your currently deployed range configuration from Ludus and provides it in YAML format for download. Users can then save this configuration file and modify/redeploy it as needed.

Args: user_id: Optional user ID (admin only - for getting other users' configs) filename: Optional filename to save to (defaults to /tmp/current-range-config.yml)

Returns: Current range configuration in YAML format ready for download

Example: # Get your current range config for download result = await get_current_range_config_for_download()

# The YAML content will be in result["yaml_content"]
# Users can copy it and save to a local file

Use Cases: - Backup your current range configuration - Download config to modify and redeploy later - Share your range configuration with team members - Version control your range configurations - Clone your current range to make variations

Inputs: user_id, filename.

get_deployment_metricsC

Get metrics for a specific deployment.

Args: deployment_id: Optional deployment ID (defaults to current) user_id: Optional user ID (admin only)

Returns: Deployment metrics

Inputs: deployment_id, user_id. Returns: object

get_deployment_statusC

Get current deployment status with detailed information.

Args: user_id: Optional user ID (admin only)

Returns: Detailed deployment status

Inputs: user_id. Returns: object

get_detection_summaryC

Get detection summary from SIEM.

Args: user_id: Optional user ID (admin only)

Returns: Detection summary with statistics

Inputs: user_id. Returns: object

get_network_topologyC

Get network topology visualization data.

Args: user_id: Optional user ID (admin only)

Returns: Network topology data

Inputs: user_id. Returns: object

get_rangeC

Get current user's range information.

Args: user_id: Optional user ID (admin only)

Returns: Range information

Inputs: user_id. Returns: object

get_range_accessC

Get range access configuration.

Args: user_id: Optional user ID (admin only)

Returns: Range access configuration

Inputs: user_id. Returns: object

get_range_ansible_inventoryB

Get Ansible inventory for the range.

Args: user_id: Optional user ID (admin only)

Returns: Ansible inventory in INI format

Inputs: user_id. Returns: result

get_range_by_userC

Get detailed information about a specific user's range.

Args: user_id: User ID whose range to retrieve

Returns: Detailed range information for the specified user

Example: # Get range information for user 'tjnull' result = await get_range_by_user(user_id="tjnull")

Inputs: user_id (required).

get_range_configC

Get range configuration.

Args: user_id: Optional user ID (admin only)

Returns: Range configuration

Inputs: user_id. Returns: object

get_range_etchostsB

Get /etc/hosts entries for the range.

Args: user_id: Optional user ID (admin only)

Returns: /etc/hosts content

Inputs: user_id. Returns: result

get_range_logsC

Get deployment logs for the range.

Args: user_id: Optional user ID (admin only)

Returns: Deployment logs

Inputs: user_id. Returns: result

get_range_metricsC

Get comprehensive metrics for the range.

Args: user_id: Optional user ID (admin only)

Returns: Range metrics (CPU, memory, disk, network usage)

Inputs: user_id. Returns: object

get_range_rdpconfigsB

Get RDP configuration files for the range.

Args: user_id: Optional user ID (admin only)

Returns: Dictionary of VM names to RDP config content

Inputs: user_id. Returns: object

get_range_skeletonA

Get a complete range skeleton configuration.

Retrieves a fully-configured range skeleton with all VMs and network rules. Some skeletons support additional customization parameters.

Args: name: Skeleton name (e.g., "basic-ad", "enterprise-ad", "red-team") domain: Custom domain name (for AD labs, default: "yourcompany.local") workstations: Number of workstations (for basic-ad, default: 2) include_attacker: Include Kali attacker VM (default: True) include_siem: Include SIEM monitoring (default: True) siem_type: SIEM type: "wazuh", "splunk", "elastic" (default: "wazuh")

Returns: Complete range configuration with VMs and network rules

Available skeletons: - basic-ad: Customizable with domain, workstations, attacker, siem - enterprise-ad: Full enterprise with CA, file server, SQL, exchange - red-team: DMZ + internal AD for red team exercises - soc-training: Monitored endpoints for SOC training - web-pentest: DVWA, Juice Shop, WebGoat - malware-analysis: Isolated RE lab

Example: # Get a basic AD lab config = await get_range_skeleton("basic-ad")

# Get a customized AD lab
config = await get_range_skeleton(
    "basic-ad",
    domain="corp.local",
    workstations=4,
    siem_type="splunk"
)

Inputs: name (required), domain, workstations, include_attacker, +2 more.

get_range_sshconfigC

Get SSH config for the range.

Args: user_id: Optional user ID (admin only)

Returns: SSH config content

Inputs: user_id. Returns: result

get_range_tagsA

Get available Ansible tags for the current range.

Use this to see what tags are available for resuming/partial deployments. Tags allow you to run specific parts of a deployment without re-running everything.

Common tags include: - base: Base system setup - domain: Domain join and AD operations - user: User and group creation - configure: Configuration tasks - testing: Testing-related tasks - vm-customize: VM customization - sysprep: Windows sysprep operations

Args: user_id: Optional user ID (admin only)

Returns: List of available Ansible tags

Example: tags = await get_range_tags() # Returns: ["base", "domain", "user", "configure", ...]

# Use tags to resume deployment
deploy_range(tags="user,domain")

Inputs: user_id. Returns: result

get_range_templateC

Get a specific range template configuration.

Args: template_id: Range template ID user_id: Optional user ID (admin only)

Returns: Range template configuration

Inputs: template_id (required), user_id.

get_recovery_recommendationC

Get recovery recommendations for failed deployments.

Args: user_id: Optional user ID (admin only)

Returns: Recovery recommendations based on failure analysis

Inputs: user_id. Returns: object

get_required_roles_for_scenarioA

Get the list of required Ansible roles for a specific scenario.

Use this MCP tool to check which roles are needed before deploying a scenario. Then use ensure_scenario_roles() to automatically install missing roles.

Args: scenario_key: Scenario identifier (e.g., "redteam-lab-intermediate") siem_type: SIEM type if scenario uses SIEM (wazuh, splunk, elastic, security-onion, none)

Returns: Dictionary with required roles and their installation status

Example: # Check required roles for a scenario result = await get_required_roles_for_scenario( scenario_key="redteam-lab-intermediate", siem_type="none" )

# Then ensure all roles are installed
await ensure_scenario_roles(
    scenario_key="redteam-lab-intermediate",
    siem_type="none",
    auto_install=True
)

Inputs: scenario_key (required), siem_type.

get_resource_quotasB

Get resource quotas and current usage.

Args: user_id: Optional user ID (admin only)

Returns: Resource quotas and usage information

Inputs: user_id.

get_role_infoA

Get information about a specific role, including installation method and requirements.

Uses the ludus CLI with --url when available for reliable remote access. No SSH required for checking role information.

Args: role_name: Name of the role to get information about

Returns: Dictionary with role information, installation method, and instructions

Example: # Get info about a Galaxy role info = await get_role_info(role_name="badsectorlabs.ludus_adcs")

# Get info about a directory-based role
info = await get_role_info(role_name="ludus-ad-vulns")

Inputs: role_name (required).

get_scenario_configD

Get scenario configuration.

Args: scenario_key: Scenario identifier siem_type: SIEM type to include

Returns: Scenario configuration

Inputs: scenario_key (required), siem_type. Returns: object

get_scenario_yamlB

Get scenario configuration as YAML.

Args: scenario_key: Scenario identifier siem_type: SIEM type to include

Returns: YAML configuration string

Inputs: scenario_key (required), siem_type. Returns: result

get_siem_agentsC

Get SIEM agents for the range.

Args: user_id: Optional user ID (admin only)

Returns: List of SIEM agents

Inputs: user_id. Returns: result

get_siem_alertsC

Get SIEM alerts for the range.

Args: user_id: Optional user ID (admin only) severity: Filter by severity level (low, medium, high, critical) limit: Maximum number of alerts to return

Returns: List of SIEM alerts

Inputs: user_id, severity, limit. Returns: result

get_siem_infoC

Get SIEM information for the range.

Args: user_id: Optional user ID (admin only)

Returns: SIEM configuration and status

Inputs: user_id. Returns: object

get_template_dependenciesB

Get template dependencies.

Args: template_id: Template ID user_id: Optional user ID (admin only)

Returns: List of template dependencies

Inputs: template_id (required), user_id. Returns: result

get_template_logsC

Get template build logs.

Args: template_id: Template ID user_id: Optional user ID (admin only)

Returns: Template build logs

Inputs: template_id (required), user_id. Returns: result

get_template_statusC

Get template build status.

Args: template_id: Template ID user_id: Optional user ID (admin only)

Returns: Template build status

Inputs: template_id (required), user_id. Returns: object

get_userC

Get information about a specific user.

Args: user_id: User ID to retrieve

Returns: User information

Inputs: user_id (required). Returns: object

get_user_apikeyC

Get API key for a user.

Args: user_id: User ID to get API key for

Returns: User's API key information

Inputs: user_id (required). Returns: object

get_vm_skeletonA

Get a specific VM skeleton template configuration.

Retrieves a pre-configured VM skeleton that can be used directly in a range configuration or customized further.

Args: name: Skeleton name (e.g., "dc-2022", "kali", "wazuh") customizations: Optional dict of fields to override (e.g., {"hostname": "mydc", "ram_gb": 8})

Returns: Complete VM configuration dictionary ready for use

Available skeletons: - dc-2022, dc-2019, secondary-dc: Domain controllers - ws-win11, ws-win10: Windows workstations - file-server, sql-server, exchange, web-iis, ca: Windows servers - ubuntu, debian, rocky, docker: Linux servers - kali, parrot, commando: Attacker VMs - wazuh, splunk, elastic, security-onion: SIEM systems - dvwa, juice-shop, metasploitable, vulnhub: Vulnerable apps

Example: # Get a Kali attacker skeleton skeleton = await get_vm_skeleton("kali")

# Get a DC with custom settings
skeleton = await get_vm_skeleton("dc-2022", {
    "hostname": "mydc01",
    "domain": {"fqdn": "corp.local", "role": "primary_dc"},
    "ram_gb": 8
})

Inputs: name (required), customizations.

get_vulnerability_scanC

Get vulnerability scan results for the range.

Args: user_id: Optional user ID (admin only)

Returns: Vulnerability scan results

Inputs: user_id. Returns: object

get_wazuh_infoC

Get Wazuh SIEM information for the range.

Args: user_id: Optional user ID (admin only)

Returns: Wazuh configuration and status

Inputs: user_id. Returns: object

get_yaml_exampleA

Get a ready-to-use YAML configuration example.

Returns the complete YAML content for a specific example configuration. The YAML can be saved directly to a file and deployed with Ludus.

Args: name: Example name ("basic_ad", "with_siem", "web_app_lab")

Returns: YAML content string ready to save to a file

Available examples: - basic_ad: Basic AD lab with DC, workstations, and Kali attacker - with_siem: AD lab with Wazuh SIEM for blue team training - web_app_lab: Web application security testing with DVWA

Example: result = await get_yaml_example("basic_ad") # result["yaml_content"] contains the full YAML configuration # Save to file and deploy: # ludus range config set -f config.yml # ludus range deploy

Inputs: name (required).

git_syncC

Sync range configurations with Git repository.

Args: action: Action to perform (configure, sync, status) repo_url: Git repository URL branch: Git branch to sync with sync_direction: Sync direction (pull, push, bidirectional) credentials: Git credentials (username, password/token) user_id: Optional user ID (admin only)

Returns: Git sync result

Inputs: action (required), repo_url, branch, sync_direction, +2 more. Returns: object

grant_range_accessC

Grant access to range for another user.

Args: target_user_id: User ID to grant access to permissions: List of permissions to grant (read, write, admin) user_id: Optional user ID (admin only)

Returns: Grant result

Inputs: target_user_id (required), permissions (required), user_id. Returns: object

handle_adws_recoveryA

Handle Active Directory Web Services (ADWS) recovery for stuck deployments.

ADWS errors are common during Active Directory deployments. This tool:

  1. Checks if deployment is stuck on ADWS errors

  2. Waits for ADWS to start (default: 10 minutes)

  3. Optionally retries the failed tasks automatically

When to use:

  • Deployment failed with "Unable to find a default server with Active Directory Web Services running"

  • Deployment is stuck on OU configuration tasks

  • DC VM is deployed but AD services haven't fully started

What this does:

  • Checks deployment logs for ADWS errors

  • Waits for ADWS to initialize (5-15 minutes typical)

  • Retries failed Ansible tasks (if auto_retry=True)

  • Provides status updates during wait

Args: wait_minutes: Minutes to wait for ADWS to start (default: 10, max: 30) auto_retry: Automatically retry failed tasks after wait (default: True) user_id: Optional user ID (admin only)

Returns: Recovery result with status and next steps

Example: # Handle ADWS recovery with auto-retry result = await handle_adws_recovery(wait_minutes=10, auto_retry=True)

# Just wait and check status (manual retry later)
result = await handle_adws_recovery(wait_minutes=15, auto_retry=False)

Inputs: wait_minutes, auto_retry, user_id. Returns: object

health_checkA

Check health of Ludus MCP server and Ludus API connectivity.

Uses the ludus CLI if available for more reliable connectivity testing.

Returns: Health status including: - Server status (healthy/unhealthy) - MCP version - Ludus API reachability - Connection latency - Number of available tools - Configuration sources - Ludus server version (if connected)

Inputs: no named parameters. Returns: object

health_checksC

Run health checks on all VMs in the range.

Args: user_id: Optional user ID (admin only)

Returns: Health check results for all VMs

Inputs: user_id. Returns: object

import_community_scenarioC

Import a scenario from the community repository.

Args: scenario_url: URL to community scenario user_id: Optional user ID (admin only)

Returns: Import result with scenario information

Inputs: scenario_url (required), user_id. Returns: object

import_range_backupC

Import and restore range from backup.

Args: backup_file: Path to backup file restore_vms: Restore VM disk images restore_config: Restore configuration user_id: Optional user ID (admin only)

Returns: Backup import result

Inputs: backup_file (required), restore_vms, restore_config, user_id. Returns: object

install_galaxy_roleA

Install an Ansible role directly from Ansible Galaxy.

This is the simplest way to install roles. Provide the Galaxy role name in the format 'namespace.role_name' and it will be installed on the Ludus server.

Args: role_name: Role name in Galaxy format (e.g., "geerlingguy.docker", "badsectorlabs.ludus_adcs") version: Optional version to install (e.g., "1.0.0")

Returns: Installation result with status

Examples: # Install a role from Ansible Galaxy result = await install_galaxy_role(role_name="geerlingguy.docker")

# Install a specific version
result = await install_galaxy_role(role_name="geerlingguy.docker", version="6.1.0")

# Install common Ludus roles
await install_galaxy_role(role_name="badsectorlabs.ludus_adcs")
await install_galaxy_role(role_name="aleemladha.wazuh_server_install")

Common Galaxy roles for Ludus: - badsectorlabs.ludus_adcs: AD Certificate Services - badsectorlabs.ludus_mssql: SQL Server - badsectorlabs.ludus_commandovm: Commando VM setup - badsectorlabs.ludus_flarevm: Flare VM setup - badsectorlabs.ludus_remnux: REMnux setup - aleemladha.wazuh_server_install: Wazuh server - aleemladha.ludus_wazuh_agent: Wazuh agent - geerlingguy.docker: Docker installation

Inputs: role_name (required), version.

install_roleA

Install an Ansible role on the Ludus server via MCP.

This MCP tool automatically handles:

  • Galaxy roles (installed directly from Ansible Galaxy, e.g., "badsectorlabs.ludus_adcs")

  • Directory-based roles (automatically cloned via SSH if configured, e.g., "ludus-ad-content")

  • Retry logic for transient failures

For directory-based roles: If SSH is configured (via configure_ssh_role_installation), the MCP server will automatically clone the repository on the Ludus server and install it. Otherwise, manual installation instructions will be provided.

Args: role_name: Name of the role to install (e.g., "badsectorlabs.ludus_adcs", "aleemladha.wazuh_server_install") role_url: Optional URL for Galaxy roles (usually not needed) max_retries: Maximum retry attempts (default: 3)

Returns: Installation result with status and details

Example: # Install a Galaxy role (works immediately) result = await install_role(role_name="badsectorlabs.ludus_adcs")

# Install a directory-based role (requires SSH config or manual setup)
result = await install_role(role_name="ludus-ad-content")

# Check installation status
status = await check_role_installed(role_name="badsectorlabs.ludus_adcs")

Inputs: role_name (required), role_url, max_retries.

install_role_from_urlA

Install an Ansible role from a custom Git repository URL.

Use this to install roles from custom Git repositories that are not on Ansible Galaxy. The repository will be cloned on the Ludus server and installed.

Args: role_name: Name to give the role when installed git_url: Git repository URL (e.g., "https://github.com/user/my-role") branch: Optional branch/tag to checkout (default: main/master)

Returns: Installation result with status and instructions

Examples: # Install a custom role from GitHub result = await install_role_from_url( role_name="my-custom-role", git_url="https://github.com/myorg/ludus-custom-role" )

# Install from a specific branch
result = await install_role_from_url(
    role_name="my-role-dev",
    git_url="https://github.com/myorg/ludus-custom-role",
    branch="develop"
)

Inputs: role_name (required), git_url (required), branch.

interactive_build_rangeC

Interactively build a range using natural language prompts.

Args: prompt: Natural language description of desired range user_id: Optional user ID (admin only)

Returns: Suggested configuration and deployment plan

Inputs: prompt (required), user_id.

jira_integrationC

Integrate with Jira for issue tracking.

Args: action: Action to perform (configure, create_issue, update_issue, link_deployment) jira_url: Jira instance URL project_key: Jira project key api_token: Jira API token issue_id: Jira issue ID (for update/link operations) user_id: Optional user ID (admin only)

Returns: Jira integration result

Inputs: action (required), jira_url, project_key, api_token, +2 more. Returns: object

list_all_ranges_detailedB

List all ranges with detailed information including identification.

This tool provides comprehensive information about all ranges in the system, making it easy to identify which range belongs to which user or purpose.

Returns: Detailed list of all ranges with: - User ID (unique identifier) - Range number/name - Range state/status - Last deployment time - VM count - Network configuration

Example: # List all ranges to see which ones exist result = await list_all_ranges_detailed()

# Output shows:
{
    "total_ranges": 3,
    "ranges": [
        {
            "user_id": "tjnull",
            "range_number": "10",
            "status": "SUCCESS",
            "vm_count": 5,
            "last_deployment": "2024-12-11T10:30:00Z",
            "identifier": "tjnull-range-10"
        },
        ...
    ]
}

Inputs: no named parameters.

list_available_profilesB

List all available adversary and defender profiles with descriptions.

Returns detailed information about all available security profiles, their capabilities, and use cases.

Returns: Dictionary containing: - adversary_profiles: Available threat levels and capabilities - defender_profiles: Available monitoring levels and capabilities - siem_types: Supported SIEM platforms - use_cases: Common use cases for each profile combination

Example: profiles = await list_available_profiles() print(profiles['adversary_profiles']['medium']['capabilities'])

Inputs: no named parameters.

list_common_containersB

List common container base images.

Returns: Dictionary of common container configurations

Inputs: no named parameters. Returns: object

list_hostsC

List all hosts in range.

Args: user_id: Optional user ID (admin only)

Returns: List of hosts

Inputs: user_id. Returns: result

list_installed_rolesA

List all installed Ansible roles on the Ludus server.

Uses the ludus CLI with --url when available for reliable remote access. Falls back to HTTP API if CLI is not available.

Returns: Dictionary with list of installed roles and their details

Example: result = await list_installed_roles() # Returns: {"installed_roles": [...], "count": 15}

Inputs: no named parameters.

list_networksC

List all networks in a range.

Args: user_id: Optional user ID (admin only)

Returns: List of networks

Inputs: user_id. Returns: result

list_rangesB

List all ranges (admin only).

Args: user_id: Optional user ID (must be admin)

Returns: List of all ranges in the system

Inputs: user_id.

list_range_skeletonsA

List all available range skeleton templates.

Returns a dictionary of complete range configurations for common scenarios. These provide fully-configured lab environments ready for deployment.

Available range skeletons:

  • basic-ad: Basic AD lab (1 DC, workstations, optional attacker/SIEM)

  • enterprise-ad: Enterprise AD with CA, servers, multiple workstations

  • red-team: Red team training with DMZ, AD, and network segmentation

  • soc-training: SOC analyst training with SIEM and monitored endpoints

  • web-pentest: Web app pentest with DVWA, Juice Shop, WebGoat

  • malware-analysis: Isolated malware RE lab with FlareVM and REMnux

Returns: Dictionary with skeleton names as keys and descriptions as values

Example: ranges = await list_range_skeletons() # Returns: {"basic-ad": "Basic AD lab...", ...}

Inputs: no named parameters.

list_range_templatesC

List available range templates from the community.

Args: user_id: Optional user ID (admin only)

Returns: List of range templates

Inputs: user_id.

list_role_repositoriesA

List all roles that are available from GitHub repositories (directory-based roles).

These roles must be cloned on the Ludus server before installation.

Returns: Dictionary with available role repositories and their GitHub URLs

Example: result = await list_role_repositories()

Inputs: no named parameters.

list_scenariosB

List all available scenarios.

Returns: Dictionary of scenario keys and descriptions

Inputs: no named parameters. Returns: object

list_snapshotsC

List all snapshots for the range.

Args: user_id: Optional user ID (admin only)

Returns: List of snapshots

Inputs: user_id. Returns: result

list_templatesC

List available templates.

Args: user_id: Optional user ID (admin only)

Returns: List of available templates

Inputs: user_id. Returns: result

list_usersB

List all users in the Ludus system.

Returns: List of all users with their information

Inputs: no named parameters. Returns: result

list_vm_skeletonsA

List all available VM skeleton templates.

Returns a dictionary of VM skeleton names and their descriptions. These skeletons can be used as starting points for building custom VMs.

Categories include:

  • Domain Controllers (dc-2022, dc-2019, secondary-dc)

  • Workstations (ws-win11, ws-win10)

  • Windows Servers (file-server, sql-server, exchange, web-iis, ca)

  • Linux Servers (ubuntu, debian, rocky, docker)

  • Attacker VMs (kali, parrot, commando)

  • SIEM/Monitoring (wazuh, splunk, elastic, security-onion)

  • Vulnerable Apps (dvwa, juice-shop, metasploitable, vulnhub)

Returns: Dictionary with skeleton names as keys and descriptions as values

Example: skeletons = await list_vm_skeletons() # Returns: {"dc-2022": "Windows Server 2022 Domain Controller", ...}

Inputs: no named parameters.

list_yaml_examplesA

List all available YAML configuration examples.

Returns ready-to-use YAML configuration examples that can be directly saved to a file and deployed with Ludus.

Available examples:

  • basic_ad: Basic AD lab with DC, workstations, and attacker

  • with_siem: AD lab with Wazuh SIEM for blue team training

  • web_app_lab: Web application security testing lab

Returns: Dictionary with example names and descriptions

Example: examples = await list_yaml_examples() # Then use get_yaml_example("basic_ad") to get the YAML content

Inputs: no named parameters.

monitor_deploymentC

Monitor deployment progress with periodic updates.

Args: user_id: Optional user ID (admin only) check_interval: Seconds between checks max_checks: Maximum number of checks

Returns: Monitoring update with progress information

Inputs: user_id, check_interval, max_checks. Returns: object

optimize_resource_allocationC

Optimize resource allocation for the range.

Args: user_id: Optional user ID (admin only)

Returns: Optimization recommendations and applied changes

Inputs: user_id.

optimize_templateC

Optimize a template for better performance.

Args: template_id: Template ID to optimize user_id: Optional user ID (admin only)

Returns: Optimization result

Inputs: template_id (required), user_id. Returns: object

power_off_rangeC

Power off all VMs in the range.

Args: user_id: Optional user ID (admin only)

Returns: Power off result

Inputs: user_id. Returns: object

power_on_rangeC

Power on all VMs in the range.

Args: user_id: Optional user ID (admin only)

Returns: Power on result

Inputs: user_id. Returns: object

preview_profile_changesA

Preview changes that would be made by applying a profile without modifying the config.

This is a dry-run tool that shows what would happen if you applied a profile, without actually modifying the configuration. Useful for understanding the impact before committing to changes.

Args: config: The Ludus range configuration to analyze profile_type: Type of profile to preview ("adversary" or "defender") profile_level: Level to preview (threat level for adversary, monitoring level for defender)

Returns: Dictionary containing: - status: "success" - profile_type: The profile type previewed - profile_level: The level previewed - affected_vms: List of VMs that would be modified - changes_summary: Summary of changes - ansible_roles_added: List of Ansible roles that would be added - estimated_impact: Estimated resource and complexity impact - recommendations: Recommendations based on the preview

Examples: # Preview medium adversary profile preview = await preview_profile_changes( config=my_config, profile_type="adversary", profile_level="medium" )

# Preview advanced defender profile
preview = await preview_profile_changes(
    config=my_config,
    profile_type="defender",
    profile_level="advanced"
)

Inputs: config (required), profile_type (required), profile_level (required).

preview_scenarioA

Preview a scenario before deployment with detailed information.

IMPORTANT: Generates a FRESH configuration preview for the specified scenario. Use this BEFORE deploy_scenario to verify what will be deployed.

Shows VMs, network topology, resource requirements, and deployment estimates. Each preview call builds the scenario from scratch with your specified parameters.

Args: scenario_key: Scenario identifier (e.g., 'redteam-lab-lite') siem_type: SIEM type to include (wazuh, splunk, elastic, security-onion, none) resource_profile: Resource allocation profile (minimal, recommended, maximum)

Returns: Preview with configuration, visualization, and estimates including: - Complete VM list with hostnames, templates, resources - Network rules and VLAN topology - Resource summary (total RAM, CPUs, disk space) - Estimated deployment time - Exact deployment command to use

Recommended workflow: 1. preview_scenario('redteam-lab-lite', 'none', 'minimal') 2. Review the VM list and resources 3. deploy_scenario('redteam-lab-lite', 'none', 'minimal')

Inputs: scenario_key (required), siem_type, resource_profile. Returns: object

publish_scenarioC

Publish a scenario to the community repository.

Args: scenario_key: Scenario to publish title: Scenario title description: Scenario description tags: Optional tags for categorization public: Make scenario publicly accessible user_id: Optional user ID (admin only)

Returns: Publish result with scenario URL

Inputs: scenario_key (required), title (required), description (required), tags, +2 more.

quick_statusB

Get one-line deployment status with emoji indicators.

Args: user_id: Optional user ID (admin only)

Returns: Formatted status string

Inputs: user_id. Returns: result

range_access_logsB

Get range access logs.

Args: user_id: Optional user ID (admin only) limit: Maximum number of log entries to return

Returns: List of access log entries

Inputs: user_id, limit. Returns: result

remove_snapshotC

Remove a snapshot.

Args: vm_name: Name of the VM snapshot_name: Name of the snapshot to remove user_id: Optional user ID (admin only)

Returns: Removal result

Inputs: vm_name (required), snapshot_name (required), user_id. Returns: object

remove_userC

Remove a user from the Ludus system.

Args: user_id: User ID to remove

Returns: Removal result

Inputs: user_id (required). Returns: object

revoke_range_accessC

Revoke range access from a user.

Args: target_user_id: User ID to revoke access from user_id: Optional user ID (admin only)

Returns: Revoke result

Inputs: target_user_id (required), user_id. Returns: object

rollback_snapshotC

Rollback to a snapshot.

Args: vm_name: Name of the VM snapshot_name: Name of the snapshot to rollback to user_id: Optional user ID (admin only)

Returns: Rollback result

Inputs: vm_name (required), snapshot_name (required), user_id. Returns: object

rotate_credentialsC

Rotate credentials for the range.

Args: user_id: Optional user ID (admin only)

Returns: Credential rotation result

Inputs: user_id. Returns: object

schedule_maintenance_windowC

Schedule a maintenance window for the range.

Args: start_time: Start time in ISO format duration_minutes: Duration in minutes operations: List of operations to perform during maintenance notify_users: Send notifications to users with access user_id: Optional user ID (admin only)

Returns: Maintenance window scheduling result

Inputs: start_time (required), duration_minutes (required), operations (required), notify_users, +1 more.

schedule_range_tasksC

Schedule recurring tasks for the range.

Args: tasks: List of tasks to schedule schedule: Cron expression for scheduling user_id: Optional user ID (admin only)

Returns: Task scheduling result

Inputs: tasks (required), schedule (required), user_id. Returns: object

schedule_snapshotsB

Schedule automatic snapshots for VMs.

Args: vm_names: List of VM names to snapshot schedule: Cron expression for snapshot schedule retention_count: Number of snapshots to retain user_id: Optional user ID (admin only)

Returns: Snapshot scheduling result

Inputs: vm_names (required), schedule (required), retention_count, user_id. Returns: object

security_auditC

Run security audit on the range.

Args: user_id: Optional user ID (admin only)

Returns: Security audit report

Inputs: user_id. Returns: object

share_range_configC

Share range configuration with other users.

Args: target_user_ids: List of user IDs to share with make_public: Make configuration publicly accessible permissions: Permissions to grant (read, clone, modify) user_id: Optional user ID (admin only)

Returns: Share result with access link

Inputs: target_user_ids, make_public, permissions, user_id. Returns: object

slack_notificationsC

Configure Slack notifications.

Args: action: Action to perform (enable, disable, test, configure) webhook_url: Slack webhook URL channel: Slack channel name events: List of events to notify on user_id: Optional user ID (admin only)

Returns: Slack integration result

Inputs: action (required), webhook_url, channel, events, +1 more. Returns: object

smart_deployA

Smart deployment with validation, optional snapshot, and auto-monitoring.

RECOMMENDED: This is the preferred method for deploying scenarios as it includes validation, error checking, and monitoring guidance.

NO FILE UPLOAD REQUIRED: This tool automatically generates the configuration from the scenario parameters. You do NOT need to provide a config file.

Workflow:

  1. Validates the scenario configuration (if auto_validate=True)

  2. Creates snapshot if requested (if auto_snapshot=True)

  3. Generates and sets the configuration in Ludus

  4. Verifies the configuration was set correctly

  5. Starts the deployment

  6. Provides monitoring guidance and commands

When to use:

  • Use smart_deploy() for most deployments (recommended)

  • Use deploy_scenario() if you need more control or don't want validation

  • Use deploy_range() only if you have a custom configuration dict

Args: scenario_key: Scenario to deploy (e.g., 'redteam-lab-lite') siem_type: SIEM type to include (wazuh, splunk, elastic, security-onion, none) auto_validate: Validate configuration before deploying (default: True) auto_snapshot: Create snapshot before deployment (default: False) auto_monitor: Enable auto-monitoring after deployment (default: True) user_id: Optional user ID (admin only)

Returns: Smart deployment result with monitoring guidance and status

Example: # Recommended: Use smart_deploy for automated deployments smart_deploy( scenario_key='redteam-lab-lite', siem_type='none', auto_validate=True, auto_monitor=True )

Inputs: scenario_key (required), siem_type, auto_validate, auto_snapshot, +2 more. Returns: object

snapshot_hostC

Create a snapshot of a host.

Args: vm_name: Name of the VM to snapshot name: Name of the snapshot description: Optional snapshot description user_id: Optional user ID (admin only)

Returns: Snapshot creation result

Inputs: vm_name (required), name (required), description, user_id. Returns: object

start_testingC

Start testing state for the range.

Args: user_id: Optional user ID (admin only)

Returns: Testing start result

Inputs: user_id. Returns: object

stop_testingC

Stop testing state for the range.

Args: user_id: Optional user ID (admin only)

Returns: Testing stop result

Inputs: user_id. Returns: object

suggest_range_enhancementsA

Suggest enhancements to improve a range configuration.

Given a basic range description, this tool suggests additional components, capabilities, and improvements to make the range more realistic, educational, or aligned with specific training goals.

Args: current_description: The current range description or configuration intent enhancement_focus: What to focus on for enhancements Options: "comprehensive", "realism", "security", "learning", "performance"

Returns: Dictionary with: - original_config: Parsed understanding of current description - suggested_additions: New VMs, services, or capabilities to add - configuration_improvements: Better network topology, resource allocation - learning_enhancements: Additional training scenarios enabled - implementation_notes: How to implement the suggestions

Examples: # Enhance basic AD lab result = await suggest_range_enhancements( "Simple AD lab with DC and 2 workstations", enhancement_focus="comprehensive" ) # Might suggest: file server, SQL server, SIEM, attacker VM, etc.

# Make lab more realistic
result = await suggest_range_enhancements(
    "Red team lab with AD and Kali",
    enhancement_focus="realism"
)
# Might suggest: multiple DCs, realistic AD misconfigs, segmentation

# Focus on learning value
result = await suggest_range_enhancements(
    "Web app testing lab",
    enhancement_focus="learning"
)
# Might suggest: vulnerable apps, varied web servers, WAF bypass scenarios

Inputs: current_description (required), enhancement_focus.

template_diffC

Compare two templates and show differences.

Args: template_id1: First template ID template_id2: Second template ID user_id: Optional user ID (admin only)

Returns: Template differences

Inputs: template_id1 (required), template_id2 (required), user_id. Returns: object

test_network_connectivityC

Test network connectivity between VMs.

Args: source_vm: Source VM name target_vm: Target VM name protocol: Protocol to test (tcp, udp, icmp) port: Optional port number for tcp/udp user_id: Optional user ID (admin only)

Returns: Connectivity test result

Inputs: source_vm (required), target_vm (required), protocol, port, +1 more. Returns: object

update_range_configC

Update range configuration.

Args: config: Range configuration object user_id: Optional user ID (admin only)

Returns: Updated configuration

Inputs: config (required), user_id. Returns: object

validate_configB

Validate range configuration before deployment.

Args: config: Range configuration to validate

Returns: Validation result with errors and warnings

Inputs: config (required). Returns: object

validate_templateB

Validate a template configuration.

Args: template_config: Template configuration to validate user_id: Optional user ID (admin only)

Returns: Validation result with errors and warnings

Inputs: template_config (required), user_id. Returns: object

visualize_rangeC

Generate visualization data for the range.

Args: user_id: Optional user ID (admin only)

Returns: Visualization data (network diagram, topology, etc.)

Inputs: user_id. Returns: object

webhook_integrationB

Manage webhook integrations.

Args: action: Action to perform (create, update, delete, list, test) webhook_url: Webhook URL (for create/update) events: List of events to trigger webhook (for create/update) webhook_id: Webhook ID (for update/delete/test) user_id: Optional user ID (admin only)

Returns: Webhook operation result

Inputs: action (required), webhook_url, events, webhook_id, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 157 tools

    Disambiguation2/5

    Many tools have overlapping purposes, causing significant ambiguity. For example, there are multiple tools for building ranges (build_range_from_description, build_range_from_prompt, build_range_from_scratch, build_range_from_skeleton, create_custom_range_from_scenario, generate_config_from_description, interactive_build_range) that are difficult to distinguish. Similarly, there are numerous tools for deleting ranges (delete_range, delete_range_by_user, delete_ranges_by_status, cleanup_old_ranges) and many batch operations that overlap with individual ones. The sheer number of tools exacerbates the confusion, making it hard for an agent to choose the right one.

    Naming Consistency3/5

    The naming follows a mostly consistent snake_case pattern, which is good. However, there are inconsistencies in verb usage and structure: some tools use 'get_' prefix (get_range, get_range_config), others use 'list_' (list_ranges, list_templates), and some use action verbs without a clear pattern (deploy_range, deploy_scenario, smart_deploy). While not chaotic, the mix of conventions reduces predictability and readability across the toolset.

    Tool Count1/5

    With 157 tools, the count is extremely high and feels overwhelming for the domain of cyber range management. Many tools appear redundant or overly specialized, such as having separate tools for batch operations on VMs (batch_power_on_hosts, batch_power_off_hosts, batch_snapshot_hosts, etc.) alongside individual and bulk counterparts. This excessive number suggests poor scoping and will likely confuse agents, making it difficult to navigate the tool surface effectively.

    Completeness5/5

    The toolset is remarkably complete for the domain of Ludus cyber range management. It covers the full lifecycle: range creation (multiple methods), deployment, configuration, monitoring, maintenance (snapshots, power operations), user management, template management, role installation, security profiles (adversary/defender), and cleanup. There are no obvious gaps; agents can perform comprehensive operations from setup to teardown with extensive customization and educational support.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables comprehensive Ansible automation management through natural language, including playbook creation and execution, inventory management, role scaffolding, and project workflows. Supports both local inventories and full project lifecycle management with syntax validation and idempotency testing.
      30
      -
    • F
      license
      C
      quality
      D
      maintenance
      Enables comprehensive management of Ansible Automation Platform Controller and Gateway through 17 specialized tools covering job execution, inventory management, workflows, credentials, user administration, and system monitoring.
      18
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables management of Proxmox Virtual Environment clusters, virtual machines, and containers through natural language interfaces. It provides 105 tools for tasks like power management, configuration, and resource monitoring with granular access control tiers.
      596 npm
      27
      MIT