ludus-mcp/src/prompts/createLudusRange.ts

MCP server for managing Ludus cybersecurity training environments through natural language commands

import { z } from 'zod';

// Schema for prompt arguments
const CreateLudusRangeArgsSchema = z.object({
  requirements: z.string().describe('What you want to build'),
  roles: z.string().optional().describe('Optional desired Ludus roles/collections'),
  save_config: z.boolean().optional().default(false)
});

export type CreateLudusRangeArgs = z.infer<typeof CreateLudusRangeArgsSchema>;

export async function handleCreateLudusRangePrompt(args: CreateLudusRangeArgs) {
  const { requirements, roles, save_config = false } = args;

  // Convert string input to proper boolean
  const shouldSaveConfig = typeof save_config === 'string' 
    ? ['true', 'TRUE', 't', 'T', '1', 'yes', 'YES', 'y', 'Y'].includes(save_config)
    : save_config === true;

  return {
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Create a Ludus cyber range with these requirements: ${requirements}
${roles ? `\nUser-specified roles to consider: ${roles}` : ''}

COMPLETE WORKFLOW INSTRUCTIONS:
Execute the following steps in order. Maintain security throughout by redacting external credentials.

STEP 1: UNDERSTAND & CLARIFY
- Analyze the user requirements: "${requirements}"
${roles ? `- Consider user-specified roles: "${roles}"` : ''}
- Extract ALL specific components from natural language:
  * Number and types of VMs (workstations, servers, domain controllers)
  * Software/services needed (AD, SCCM, Elastic, monitoring tools)
  * Network requirements (Tailscale, VLANs, subnets)
  * Security tools (EDR, SIEM, logging)
  * Operating systems and templates
- If requirements are vague or missing critical details, ask clarifying questions
- Determine complexity level automatically based on component count and integration needs
${roles ? '- Validate user-specified roles exist and match requirements' : ''}
- Configuration save setting: ${shouldSaveConfig ? 'SAVE configuration to file after creation' : 'DO NOT save configuration (display only)'}

STEP 2: RESEARCH PHASE (Use tools in this order)
1. ludus_list_role_collection_schemas - Get inventory of available role/collection YAML files
2. ludus_read_role_collection_schema - Get comprehensive role data and variables (use file_names filtering if you only need specific roles)
3. ludus_read_range_config_schema - Understand YAML structure and validation rules  
4. ludus_roles_docs_read - Get complete roles documentation
5. ludus_networking_docs_read - Get networking configuration info
6. list_range_configs - Discover base templates in ~/.ludus-mcp/range-config-templates/base-configs/
7. read_range_config - Examine 1-3 relevant base templates for patterns
8. ludus_environment_guides_search - Get environment-specific guidance if needed

SCHEMA TOOL OPTIMIZATION:
- Use ludus_list_role_collection_schemas first to see what's available and plan your research
- For TARGETED research: Use ludus_read_role_collection_schema with file_names=["specific_role.yaml", "another_role.yaml"] 
- For COMPREHENSIVE research: Use ludus_read_role_collection_schema without filtering to get everything
- Choose filtering based on requirements complexity and confidence level

EXTERNAL ROLE HANDLING:
- If requirements not covered by official Ludus roles: ASK USER with options:
  a) Search internet for community/third-party solutions
  b) Provide alternative approaches using available roles
  c) Simplify requirements to use available roles
- MUST ask user permission before including any non-official Ludus roles found via web search
- Wait for user decision before proceeding with external roles

STEP 3: BUILD RANGE CONFIG
- Design complete VM architecture using research data
- Generate Ludus YAML configuration meeting all requirements
${roles ? `- PRIORITIZE user-specified roles: "${roles}" where applicable` : ''}
- **CRITICAL:** Use ONLY validated role variables from ludus_read_role_collection_schema
- **CRITICAL:** Follow exact YAML structure from ludus_read_range_config_schema  
- Ensure proper role variables using schema data - NO guessing or assumptions

*** ROLE EXECUTION ORDER AND DEPENDENCIES ***
IMPORTANT: Roles execute in SEQUENTIAL ORDER as listed in the configuration!
- If a role depends on another role listed BELOW it, you MUST use the depends_on parameter
- Example dependency syntax:
  roles:
    - name: badsectorlabs.ludus_elastic_agent
      depends_on:
        - vm_name: "{{ range_id }}-elastic"
          role: badsectorlabs.ludus_elastic_container
- Common dependency patterns:
  * Domain controllers before domain-joined machines
  * SQL servers before SCCM site servers
  * Parent services before agents/clients
- Check schema files for role-specific usage_notes and dependency_examples
- Reference master-range-config-template.yaml for complete dependency examples

- Apply correct credential handling:
  * EXTERNAL service credentials: Use {{LudusCredName-<user>-<credName>}} placeholders
  * RANGE-INTERNAL credentials: Include directly (AD passwords, SCCM passwords, domain accounts)
- SECURITY: When showing config content, REDACT any external service credentials
- **VALIDATION PREVIEW:** Double-check your config against both schemas BEFORE proceeding to validation

DETAILED CREDENTIAL GUIDANCE:
EXTERNAL SERVICE CREDENTIALS (use {{LudusCredName-<user>-<credName>}} placeholders):
- Third-party API keys (Tailscale, cloud services, SaaS platforms)
- External service tokens (GitHub, Docker Hub, monitoring services)  
- Cloud provider credentials (AWS, Azure, GCP access keys)
- External database connection strings to hosted services

RANGE-INTERNAL CREDENTIALS (include directly in YAML config):
- Domain Administrator passwords: "ClientPushPassword": "P@ssw0rd123!"
- Active Directory passwords (Administrator, domain users, service accounts)
- SCCM passwords (SCCM service accounts, SQL service accounts for SCCM)
- Local Windows/Linux user account passwords within the range
- Database passwords for databases running INSIDE the range VMs
- Service account passwords for internal range services (IIS, Apache, domain services)
- Local application passwords (web apps, monitoring tools running on range VMs)

WHEN UNCERTAIN: Ask user "Is this credential for an external service or internal to the range?"

STEP 4: COMPREHENSIVE VALIDATION - MANDATORY SCHEMA VALIDATION
**CRITICAL:** Use BOTH schemas to validate BEFORE writing any configuration files

ROLE/COLLECTION VALIDATION:
- MANDATORY: Run ludus_list_role_collection_schemas to see all available roles/collections
- MANDATORY: Run ludus_read_role_collection_schema to get complete role definitions
- Cross-check EVERY role and variable in your configuration against the schema
- Verify all required variables are present and correctly formatted
- Ensure variable types match schema specifications (string, boolean, array, etc.)
- Confirm default values are appropriate or properly customized

RANGE CONFIGURATION VALIDATION:
- MANDATORY: Run ludus_read_range_config_schema to validate YAML structure
- Verify your configuration follows proper Ludus range config format
- Check all required sections are present (ludus:, vm_name, template, etc.)
- Validate network configuration follows schema requirements
- Ensure domain configurations match schema patterns

COMPREHENSIVE VALIDATION:
- Run ludus_range_config_check_against_plan with:
  * user_requirements: "${requirements}"
  * roles_used: [list of roles used]
  * validated_variables_summary: [research summary from schemas/docs]
- Address ALL validation failures before proceeding
- DO NOT proceed to Step 5 until all schema validations pass

STEP 5: SYNTAX VALIDATION
- Run validate_range_config to check YAML syntax and structure
- Fix any validation errors found
- Confirm configuration is deployment-ready
- FINAL CHECK: Re-verify role variables against ludus_read_role_collection_schema

STEP 6: SAVE & NEXT STEPS
- Only after ALL validations pass: ${shouldSaveConfig ? 'Use write_range_config to save configuration to file' : 'Display configuration content without saving'}
- Provide clear next steps for user:
  * Configuration summary
  * Deployment instructions (set_range_config, then deploy_range)
  * Any credential requirements identified
- Ask user for additional instructions

CRITICAL USER PERMISSIONS:
- MUST ask user permission before using set_range_config (specify target user)
- MUST ask user permission before injecting credentials with insert_creds_range_config
- DON'T automatically deploy ranges - only when user explicitly confirms
- DON'T automatically set range configs - only when user explicitly requests

SECURITY REQUIREMENTS:
- NEVER display external service credentials (API keys, SaaS tokens) in responses
- REDACT with "REDACTED-CREDENTIAL" when showing configs
- Range-internal passwords (AD, SCCM, domain accounts) can be shown directly
- When uncertain about credential type, ask user

COMPLETION CRITERIA:
- All user requirements met
- Configuration validates successfully
- Role variables verified against schema
- Security guidelines followed
- Clear next steps provided`
        }
      }
    ]
  };
}