Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| LUDUS_API_KEY | Yes | Your Ludus API key for authentication | |
| LUDUS_API_URL | Yes | The URL of your Ludus server instance |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_range | Get current user's range information. Args: user_id: Optional user ID (admin only) Returns: Range information |
| get_range_config | Get range configuration. Args: user_id: Optional user ID (admin only) Returns: Range configuration |
| update_range_config | Update range configuration. Args: config: Range configuration object user_id: Optional user ID (admin only) Returns: Updated configuration |
| deploy_range | 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:
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: 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 |
| get_range_tags | 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") |
| abort_range_deployment | 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: 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="...") |
| snapshot_host | 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 |
| list_snapshots | List all snapshots for the range. Args: user_id: Optional user ID (admin only) Returns: List of snapshots |
| rollback_snapshot | 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 |
| remove_snapshot | 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 |
| power_on_range | Power on all VMs in the range. Args: user_id: Optional user ID (admin only) Returns: Power on result |
| power_off_range | Power off all VMs in the range. Args: user_id: Optional user ID (admin only) Returns: Power off result |
| list_templates | List available templates. Args: user_id: Optional user ID (admin only) Returns: List of available templates |
| list_hosts | List all hosts in range. Args: user_id: Optional user ID (admin only) Returns: List of hosts |
| list_networks | List all networks in a range. Args: user_id: Optional user ID (admin only) Returns: List of networks |
| start_testing | Start testing state for the range. Args: user_id: Optional user ID (admin only) Returns: Testing start result |
| stop_testing | Stop testing state for the range. Args: user_id: Optional user ID (admin only) Returns: Testing stop result |
| health_check | 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) |
| list_scenarios | List all available scenarios. Returns: Dictionary of scenario keys and descriptions |
| deploy_scenario | 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:
Recommended Workflow:
Internal Workflow:
Available scenarios:
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:
Note: For automated deployments with validation and monitoring, consider using smart_deploy() instead, which handles the full workflow. |
| get_scenario_config | Get scenario configuration. Args: scenario_key: Scenario identifier siem_type: SIEM type to include Returns: Scenario configuration |
| get_scenario_yaml | Get scenario configuration as YAML. Args: scenario_key: Scenario identifier siem_type: SIEM type to include Returns: YAML configuration string |
| preview_scenario | 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') |
| quick_status | Get one-line deployment status with emoji indicators. Args: user_id: Optional user ID (admin only) Returns: Formatted status string |
| get_deployment_status | Get current deployment status with detailed information. Args: user_id: Optional user ID (admin only) Returns: Detailed deployment status |
| get_range_logs | Get deployment logs for the range. Args: user_id: Optional user ID (admin only) Returns: Deployment logs |
| smart_deploy | 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:
When to use:
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 ) |
| monitor_deployment | 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 |
| deployment_timeline | Get deployment timeline with progress tracking. Args: user_id: Optional user ID (admin only) Returns: Timeline with steps and progress |
| validate_config | Validate range configuration before deployment. Args: config: Range configuration to validate Returns: Validation result with errors and warnings |
| handle_adws_recovery | Handle Active Directory Web Services (ADWS) recovery for stuck deployments. ADWS errors are common during Active Directory deployments. This tool:
When to use:
What this does:
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) |
| list_users | List all users in the Ludus system. Returns: List of all users with their information |
| get_user | Get information about a specific user. Args: user_id: User ID to retrieve Returns: User information |
| add_user | 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 |
| remove_user | Remove a user from the Ludus system. Args: user_id: User ID to remove Returns: Removal result |
| get_user_apikey | Get API key for a user. Args: user_id: User ID to get API key for Returns: User's API key information |
| get_siem_info | Get SIEM information for the range. Args: user_id: Optional user ID (admin only) Returns: SIEM configuration and status |
| get_siem_alerts | 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 |
| get_siem_agents | Get SIEM agents for the range. Args: user_id: Optional user ID (admin only) Returns: List of SIEM agents |
| get_detection_summary | Get detection summary from SIEM. Args: user_id: Optional user ID (admin only) Returns: Detection summary with statistics |
| get_wazuh_info | Get Wazuh SIEM information for the range. Args: user_id: Optional user ID (admin only) Returns: Wazuh configuration and status |
| get_range_access | Get range access configuration. Args: user_id: Optional user ID (admin only) Returns: Range access configuration |
| grant_range_access | 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 |
| revoke_range_access | 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 |
| clear_range_access | Clear all range access permissions. Args: user_id: Optional user ID (admin only) Returns: Clear result |
| range_access_logs | 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 |
| security_audit | Run security audit on the range. Args: user_id: Optional user ID (admin only) Returns: Security audit report |
| compliance_check | 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 |
| rotate_credentials | Rotate credentials for the range. Args: user_id: Optional user ID (admin only) Returns: Credential rotation result |
| get_vulnerability_scan | Get vulnerability scan results for the range. Args: user_id: Optional user ID (admin only) Returns: Vulnerability scan results |
| add_template | 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 |
| build_template | 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 |
| delete_template | Delete a template. Args: template_id: Template ID to delete user_id: Optional user ID (admin only) Returns: Deletion result |
| get_template_status | Get template build status. Args: template_id: Template ID user_id: Optional user ID (admin only) Returns: Template build status |
| get_template_logs | Get template build logs. Args: template_id: Template ID user_id: Optional user ID (admin only) Returns: Template build logs |
| abort_template_build | Abort a template build. Args: template_id: Template ID user_id: Optional user ID (admin only) Returns: Abort result |
| apply_template | 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 |
| create_custom_template | 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 |
| create_container_template | 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 |
| list_common_containers | List common container base images. Returns: Dictionary of common container configurations |
| get_container_config | Get configuration for a common container. Args: container_name: Container name Returns: Container configuration |
| template_diff | 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 |
| validate_template | 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 |
| get_template_dependencies | Get template dependencies. Args: template_id: Template ID user_id: Optional user ID (admin only) Returns: List of template dependencies |
| optimize_template | Optimize a template for better performance. Args: template_id: Template ID to optimize user_id: Optional user ID (admin only) Returns: Optimization result |
| get_range_metrics | Get comprehensive metrics for the range. Args: user_id: Optional user ID (admin only) Returns: Range metrics (CPU, memory, disk, network usage) |
| get_deployment_metrics | 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 |
| get_cost_estimation | Get cost estimation for the range. Args: user_id: Optional user ID (admin only) Returns: Cost estimation based on resource usage |
| export_metrics | 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 |
| get_range_ansible_inventory | Get Ansible inventory for the range. Args: user_id: Optional user ID (admin only) Returns: Ansible inventory in INI format |
| get_range_sshconfig | Get SSH config for the range. Args: user_id: Optional user ID (admin only) Returns: SSH config content |
| get_range_rdpconfigs | Get RDP configuration files for the range. Args: user_id: Optional user ID (admin only) Returns: Dictionary of VM names to RDP config content |
| get_range_etchosts | Get /etc/hosts entries for the range. Args: user_id: Optional user ID (admin only) Returns: /etc/hosts content |
| test_network_connectivity | 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 |
| get_network_topology | Get network topology visualization data. Args: user_id: Optional user ID (admin only) Returns: Network topology data |
| diagnose_network_issues | Diagnose network connectivity issues. Args: user_id: Optional user ID (admin only) Returns: Network diagnostics report |
| capture_network_traffic | 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 |
| visualize_range | Generate visualization data for the range. Args: user_id: Optional user ID (admin only) Returns: Visualization data (network diagram, topology, etc.) |
| health_checks | Run health checks on all VMs in the range. Args: user_id: Optional user ID (admin only) Returns: Health check results for all VMs |
| create_deployment_pipeline | 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 |
| schedule_range_tasks | 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 |
| auto_scaling | 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 |
| schedule_snapshots | 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 |
| clone_range | 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 |
| export_range_backup | 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 |
| import_range_backup | 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 |
| bulk_vm_operations | 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 |
| delete_range | 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 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) |
| abort_and_remove_range | 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:
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) |
| get_recovery_recommendation | Get recovery recommendations for failed deployments. Args: user_id: Optional user ID (admin only) Returns: Recovery recommendations based on failure analysis |
| webhook_integration | 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 |
| slack_notifications | 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 |
| jira_integration | 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 |
| git_sync | 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 |
| generate_range_documentation | 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 |
| get_attack_path_documentation | 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 |
| export_lab_guide | 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 |
| create_scenario_playbook | 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 |
| share_range_config | Share range configuration with other users. Args: target_user_ids: List of user IDs to share with make_public: Make configuration publicly accessible permissions: Permissions to grant (read, clone, modify) user_id: Optional user ID (admin only) Returns: Share result with access link |
| import_community_scenario | 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 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |