Ludus FastMCP
Ludus FastMCP is an AI-powered MCP server that automates Ludus cyber range environments through natural language commands, exposing 157 tools across 15 modules for comprehensive lab management.
Core Capabilities:
Range Lifecycle Management: Create, configure, deploy, abort, power on/off, clone, and delete cyber ranges with bulk VM operations and testing mode controls
Scenario Deployment: Deploy 13 pre-built scenarios (red/blue/purple team, malware analysis, wireless labs) with customization, randomization, and SIEM integration (Wazuh, Splunk, Elastic Stack, Security Onion)
Template Management: Build, validate, optimize, and manage custom OS and container templates with dependency tracking and build logs
Snapshot Management: Create, list, rollback, and remove VM snapshots with scheduled automation and retention policies
SIEM Integration: Alert management, agent monitoring, detection summaries, and security event analysis across multiple SIEM platforms
User & Access Control: Manage users, API keys, and granular range access permissions
Network Operations: Visualize topology, test connectivity, diagnose issues, capture traffic with BPF filtering, and export SSH/RDP configurations
Deployment Control: Smart deployment with validation, monitoring, recovery tools, and Ansible tag-based resumption (base, domain, user, configure)
Security & Compliance: Run audits, compliance checks (NIST, PCI, ISO27001), vulnerability scans, and credential rotation
Metrics & Reporting: Monitor CPU, memory, disk, network usage with cost estimations; export in JSON, CSV, or Prometheus formats
Automation & Integration: Create deployment pipelines, schedule tasks with cron, configure auto-scaling, and integrate with webhooks, Slack, Jira, and Git repositories
Backup & Recovery: Export/import range backups, clone ranges with snapshots, and access recovery recommendations for failed deployments
Documentation & Training: Generate range documentation (markdown, HTML, PDF), attack path analysis, lab guides with solutions, and scenario playbooks
Community & Sharing: Import community scenarios and share range configurations publicly or with specific users
Provides Ansible role management capabilities including Ansible Galaxy integration and custom role installation for configuring Ludus cyber range environments.
Enables SIEM integration with Elastic Stack for security monitoring and logging within Ludus cyber range deployments.
Supports configuration of local LLM through Ollama for AI-powered management of Ludus environments via the ludus-ai CLI tool.
Enables SIEM integration with Splunk for security monitoring and event management in Ludus cyber range environments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ludus FastMCP deploy an Active Directory lab with Wazuh monitoring"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ludus FastMCP
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 --setupThe 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 serviceClient 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 directlyExample 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 membersExamples of using Ludus-FastMCP with grok code through Opencode.




Documentation
Document | Description |
Installation, setup, and first deployment | |
Environment variables and MCP client setup | |
Complete documentation for all 231 tools | |
Pre-built deployment scenarios | |
Common issues and solutions | |
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 | |
Ludus API Reference | |
Ludus GitHub | |
FastMCP Framework | |
MCP Specification |
Support
GitHub Issues - Bug reports and feature requests
GitHub Discussions - Questions and community discussion
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
Credits
Available Tools
157 toolsabort_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:
ludus range abortludus 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 segmentationNotes: ⚠️ 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:
Use preview_scenario() first to verify what will be deployed
(Optional) Abort any existing deployment: abort_range_deployment()
(Optional) Delete existing range: delete_range(confirm=True)
Deploy the scenario: deploy_scenario(scenario_key='redteam-lab-lite')
Monitor progress: monitor_deployment() or quick_status()
Internal Workflow:
Generates fresh scenario configuration based on parameters
Applies customizations or randomization if requested
Sets the configuration in Ludus (via PUT /range/config)
Verifies the configuration was set correctly
Starts deployment (via POST /range/deploy)
Generates comprehensive walkthrough
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:
Check which roles are required for the scenario
Check which roles are already installed
Automatically install missing Galaxy roles (if auto_install=True)
Automatically clone and install directory-based roles via SSH (if SSH configured)
Report which roles need manual installation (if SSH not configured)
MCP Workflow:
Use
ensure_scenario_roles()before deploying to ensure all roles are readyConfigure SSH access with
configure_ssh_role_installation()for automatic directory-based role installationUse
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/downloadInputs: 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 fileUse 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:
Checks if deployment is stuck on ADWS errors
Waits for ADWS to start (default: 10 minutes)
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
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:
Validates the scenario configuration (if auto_validate=True)
Creates snapshot if requested (if auto_snapshot=True)
Generates and sets the configuration in Ludus
Verifies the configuration was set correctly
Starts the deployment
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 scenariosInputs: 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
Scored across 157 tools
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.
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.
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.
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
Related MCP Connectors
AI-callable tools for API mocking, testing, monitoring, security, and automation.
Email inboxes, webhooks, mock APIs, 2FA codes, approvals and 170 tools for AI agents.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
34 security tools for AI agents: phishing links, exposure maps, DNS, SSL, PQC, history, pivots.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityDmaintenanceEnables management of Cobalt Strike red team operations through natural language commands, providing access to 200+ tools for beacon control, listener management, credential operations, and payload generation.1GPL 3.0
- FlicenseCqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm27MIT