Ludus FastMCP
by tjnull
- Ludus-FastMCP
- ludus_mcp
- server
- tools
- __pycache__
deployment.cpython-313.pyc•23.6 kB
�
i>i�W � �~ � S r SSKJr SSKJr SSKJr SSKJr SSK J
r
SSK J r SSK
Jr SS KJrJr S
\S \4S jrg
)z@Deployment FastMCP tools - scenarios, orchestration, monitoring.� )�Any)�FastMCP)�LudusAPIClient)�ScenarioHandler)�DeploymentHandler)�DeploymentOrchestrator)�ValidationHandler)�LazyHandlerRegistry�format_tool_response�client�returnc � ^ ^� [ S5 n[ T 5 mUR 5 S[ [ [ 4 4U4S jj5 nUR 5 S$S[ S[ S- S[
S[ S [ S
[
S [
S [ [ [ [ 4 S- S
[ [ [ 4 S- S[ [ [ 4 S- S[ [ [ 4 S- S[ 4U4S jjj5 nUR 5 S%S[ S[ S[ 4U4S jjj5 nUR 5 S%S[ S[ S[ 4U4S jjj5 nUR 5 S&S[ S[ S [ S[ 4U4S jjj5 nUR 5 S'S[ S- S[ 4U4S jjj5 nUR 5 S'S[ S- S[ 4U4S jjj5 nUR 5 S'S[ S- S[ 4U 4S jjj5 n UR 5 S(S[ S[ S[
S[
S[
S[ S- S[ 4U4S jjj5 n
UR 5 S)S[ S- S[ S [ S[ 4U4S jjj5 n UR 5 S'S[ S- S[ 4U4S jjj5 n UR 5 S [ [ [ 4 S[ 4U4S jj5 n
UR 5 S*S![ S"[
S[ S- S[ 4U4S# jjj5 nU$ )+z�Create deployment operation tools.
Args:
client: Ludus API client
Returns:
FastMCP instance with deployment tools registered
zDeployment Operationsr
c � �p ># � TR S[ 5 n U R 5 I Sh v�N nU$ N7f)zYList all available scenarios.
Returns:
Dictionary of scenario keys and descriptions
�scenarioN)� get_handlerr �list_scenarios)�handler�result�registrys ��Q/home/tjnull/Documents/scripts/Ludus-FastMCP/ludus_mcp/server/tools/deployment.pyr �/create_deployment_tools.<locals>.list_scenarios s5 �� � � �&�&�z�?�C�� �-�-�/�/���
� 0�s �*6�4�6N� scenario_key�user_id� ensure_roles� siem_type�resource_profile� customize� randomize� custom_users�vulnerability_config�network_customizations�vm_customizationsc � �v ># � T
R S[ 5 n U R XX#U5 I Sh v�N n U $ N7f)u� Deploy a scenario with optional SIEM integration and customization.
IMPORTANT: This tool generates a FRESH configuration for each call.
Each deployment builds a new scenario from scratch - no state is reused.
NO FILE UPLOAD REQUIRED: This tool automatically generates the configuration
from the scenario parameters. You do NOT need to provide a config file or
manual configuration.
CUSTOMIZATION AND RANDOMIZATION:
- Use customize=True with custom parameters to deploy a customized scenario
- Use randomize=True to deploy a randomized version with varied users/vulnerabilities
- All customization parameters are optional - defaults used if not specified
Recommended Workflow:
1. Use preview_scenario() first to verify what will be deployed
2. (Optional) Abort any existing deployment: abort_range_deployment()
3. (Optional) Delete existing range: delete_range(confirm=True)
4. Deploy the scenario: deploy_scenario(scenario_key='redteam-lab-lite')
5. Monitor progress: monitor_deployment() or quick_status()
Internal Workflow:
1. Generates fresh scenario configuration based on parameters
2. Applies customizations or randomization if requested
3. Sets the configuration in Ludus (via PUT /range/config)
4. Verifies the configuration was set correctly
5. Starts deployment (via POST /range/deploy)
6. Generates comprehensive walkthrough
7. Returns deployment status, VM details, and walkthrough
Available scenarios:
- redteam-lab-lite: 5 VMs (DC, 2 workstations, file server, Kali)
- redteam-lab-intermediate: 10 VMs (DMZ, internal network, multiple servers)
- redteam-lab-advanced: 21 VMs (2 forests with trust, DMZ, secure zone)
- blueteam-lab-lite: 6 VMs (SOC with SIEM, detection)
- blueteam-lab-intermediate: 11 VMs (SOC with EDR, IDS)
- blueteam-lab-advanced: 21 VMs (Enterprise SOC, full stack)
- purpleteam-lab-lite: 6 VMs (Red/Blue collaborative)
- purpleteam-lab-intermediate: 10 VMs (Purple team with EDR)
- purpleteam-lab-advanced: 13 VMs (Full SOC + adversary emulation)
- malware-re-lab-lite: 3 VMs (Basic malware analysis)
- malware-re-lab-intermediate: 7 VMs (Pro malware lab)
- malware-re-lab-advanced: 18 VMs (Enterprise malware research)
- wireless-lab: 2 VMs (WiFi pentesting)
Args:
scenario_key: Scenario identifier (e.g., 'redteam-lab-lite')
user_id: Optional user ID (admin only)
ensure_roles: Ensure required Ansible roles are installed
siem_type: SIEM type to include (wazuh, splunk, elastic, security-onion, none)
resource_profile: Resource allocation profile (minimal, recommended, maximum)
customize: Enable customization mode (use provided customizations)
randomize: Enable randomization mode (generate random customizations)
custom_users: List of custom user dicts with keys: username, password, display_name,
groups (list), department (optional), title (optional), etc.
vulnerability_config: Dict with keys like esc1_enabled, esc2_enabled, open_shares, etc.
network_customizations: Dict with vlan_changes, additional_rules, remove_rules, etc.
vm_customizations: Dict with vm_count_overrides, additional_vms, remove_vms, etc.
Returns:
Deployment result with scenario details, VM list, deployment status, and walkthrough
Examples:
# Simple deployment (default)
deploy_scenario(scenario_key='redteam-lab-lite', siem_type='none')
# Randomized deployment
deploy_scenario(scenario_key='redteam-lab-lite', randomize=True)
# Custom users deployment
deploy_scenario(
scenario_key='redteam-lab-lite',
customize=True,
custom_users=[
{
"username": "admin.user",
"password": "CustomPass123!",
"display_name": "Admin User",
"groups": ["Domain Users", "Domain Admins"],
"department": "IT"
}
]
)
# Custom vulnerabilities
deploy_scenario(
scenario_key='redteam-lab-lite',
customize=True,
vulnerability_config={
"esc1_enabled": True,
"esc8_enabled": True,
"open_shares": True
}
)
Natural Language Translation:
- "Make a custom range using redteam-lab-lite" → customize=True
- "Randomize redteam-lab-lite" → randomize=True
- "Deploy with different users" → customize=True, custom_users=[...]
Note: For automated deployments with validation and monitoring,
consider using smart_deploy() instead, which handles the full workflow.
r N)r r �deploy_scenario)r r r r r r r r r r! r" r r r s �r r$ �0create_deployment_tools.<locals>.deploy_scenario& s> �� � �j �&�&�z�?�C�� �.�.�|�l�_o�p�p���
� q�s �-9�7�9c � �r ># � TR S[ 5 nUR X5 I Sh v�N nU$ N7f)z�Get scenario configuration.
Args:
scenario_key: Scenario identifier
siem_type: SIEM type to include
Returns:
Scenario configuration
r N)r r �get_scenario_config�r r r r r s �r r' �4create_deployment_tools.<locals>.get_scenario_config� s8 �� � � �&�&�z�?�C�� �2�2�<�K�K���
� L�� �+7�5�7c � �r ># � TR S[ 5 nUR X5 I Sh v�N nU$ N7f)z�Get scenario configuration as YAML.
Args:
scenario_key: Scenario identifier
siem_type: SIEM type to include
Returns:
YAML configuration string
r N)r r �get_scenario_yamlr( s �r r, �2create_deployment_tools.<locals>.get_scenario_yaml� s8 �� � � �&�&�z�?�C�� �0�0� �I�I���
� J�r* c � � ># � TR S[ 5 nUR XU5 I Sh v�N n[ U5 $ N7f)aK 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')
r N)r r �preview_scenarior )r r r r r r s �r r/ �1create_deployment_tools.<locals>.preview_scenario� sB �� � �@ �&�&�z�?�C�� �/�/� �IY�Z�Z��#�F�+�+� [�s �,A�?�Ac � �r ># � TR S[ 5 nUR U 5 I Sh v�N nU$ N7f)z�Get one-line deployment status with emoji indicators.
Args:
user_id: Optional user ID (admin only)
Returns:
Formatted status string
�
deploymentN)r r � quick_status�r r r r s �r r3 �-create_deployment_tools.<locals>.quick_status� s8 �� � � �&�&�|�5F�G�� �+�+�G�4�4���
� 5�r* c � �r ># � TR S[ 5 nUR U 5 I Sh v�N nU$ N7f)z�Get current deployment status with detailed information.
Args:
user_id: Optional user ID (admin only)
Returns:
Detailed deployment status
r2 N)r r �get_deployment_statusr4 s �r r7 �6create_deployment_tools.<locals>.get_deployment_status� s8 �� � � �&�&�|�5F�G�� �4�4�W�=�=���
� >�r* c � �F ># � TR U 5 I Sh v�N nU$ N7f)zsGet deployment logs for the range.
Args:
user_id: Optional user ID (admin only)
Returns:
Deployment logs
N)�get_range_logs)r r r s �r r: �/create_deployment_tools.<locals>.get_range_logs s% �� � � �,�,�W�5�5���
� 6�s �!� �!�
auto_validate�
auto_snapshot� auto_monitorc � � ># � TR S[ 5 nUR XX#XE5 I Sh v�N n[ U5 $ N7f)a' Smart deployment with validation, optional snapshot, and auto-monitoring.
RECOMMENDED: This is the preferred method for deploying scenarios as it includes
validation, error checking, and monitoring guidance.
NO FILE UPLOAD REQUIRED: This tool automatically generates the configuration
from the scenario parameters. You do NOT need to provide a config file.
Workflow:
1. Validates the scenario configuration (if auto_validate=True)
2. Creates snapshot if requested (if auto_snapshot=True)
3. Generates and sets the configuration in Ludus
4. Verifies the configuration was set correctly
5. Starts the deployment
6. Provides monitoring guidance and commands
When to use:
- Use smart_deploy() for most deployments (recommended)
- Use deploy_scenario() if you need more control or don't want validation
- Use deploy_range() only if you have a custom configuration dict
Args:
scenario_key: Scenario to deploy (e.g., 'redteam-lab-lite')
siem_type: SIEM type to include (wazuh, splunk, elastic, security-onion, none)
auto_validate: Validate configuration before deploying (default: True)
auto_snapshot: Create snapshot before deployment (default: False)
auto_monitor: Enable auto-monitoring after deployment (default: True)
user_id: Optional user ID (admin only)
Returns:
Smart deployment result with monitoring guidance and status
Example:
# Recommended: Use smart_deploy for automated deployments
smart_deploy(
scenario_key='redteam-lab-lite',
siem_type='none',
auto_validate=True,
auto_monitor=True
)
� orchestratorN)r r � smart_deployr ) r r r< r= r> r r r r s �r rA �-create_deployment_tools.<locals>.smart_deploy sJ �� � �d �&�&�~�7M�N�� �+�+� �]�<�
�
�� $�F�+�+�
�s �-A�A �A�check_interval�
max_checksc � � ># � TR S[ 5 nUR U 5 I Sh v�N n[ U5 $ N7f)z�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
r@ N)r r �monitor_deployment_oncer )r rC rD r r r s �r �monitor_deployment�3create_deployment_tools.<locals>.monitor_deploymentL s? �� � � �&�&�~�7M�N�� �6�6�w�?�?��#�F�+�+� @�� �+A �>�A c � � ># � TR S[ 5 nUR U 5 I Sh v�N n[ U5 $ N7f)z�Get deployment timeline with progress tracking.
Args:
user_id: Optional user ID (admin only)
Returns:
Timeline with steps and progress
r@ N)r r �get_deployment_timeliner r4 s �r �deployment_timeline�4create_deployment_tools.<locals>.deployment_timeline` s? �� � � �&�&�~�7M�N�� �6�6�w�?�?��#�F�+�+� @�rI �configc � � ># � TR S[ 5 nUR U 5 I Sh v�N n[ U5 $ N7f)z�Validate range configuration before deployment.
Args:
config: Range configuration to validate
Returns:
Validation result with errors and warnings
�
validationN)r r �validate_configr )rN r r r s �r rQ �0create_deployment_tools.<locals>.validate_configp s> �� � � �&�&�|�5F�G�� �.�.�v�6�6��#�F�+�+� 7�rI � wait_minutes�
auto_retryc � �J ># � SSK nTR S[ 5 n UR R U5 I Sh v�N nUR SS5 nUR
U5 I Sh v�N n[ U[ 5 ( a UR SS5 O
[ U5 nUR 5 n SU ; =( d S U ; =( d S
U ; n
U
( d US ; a [ S S
USS.5 $ SU
U[ U S5 U/ S.n [ U S5 S- n Sn
X�- nU S R SU S35 U S R S5 U S R SU
S35 [ U5 GH
nUR U
5 I Sh v�N UR R U5 I Sh v�N nUR SS5 nUS:X a2 SU S ' S U S ' U S R S US - S!35 [ U 5 s $ UR
U5 I Sh v�N n[ U[ 5 ( a UR SS5 O
[ U5 nSUR 5 ; d M� S"U S ' U S R S#US - S!35 O U( a_ U S S":X aV U S R S$5 UR R! SUS%S&9I Sh v�N nS'U S ' UU S(' U S R S)5 U S S:X a S.U S ' S/U S ' U S R S05 / S1QU S2' [ U 5 $ GN� GN� GN� GN| GN Nj! [" aH nS*U S ' [ U5 U S+' U S R S,U 35 U S R S-5 SnAN�SnAff = f! [" a" n[ S+[ U5 S3S4.5 s SnA$ SnAff = f7f)5a� Handle Active Directory Web Services (ADWS) recovery for stuck deployments.
ADWS errors are common during Active Directory deployments. This tool:
1. Checks if deployment is stuck on ADWS errors
2. Waits for ADWS to start (default: 10 minutes)
3. Optionally retries the failed tasks automatically
**When to use:**
- Deployment failed with "Unable to find a default server with Active Directory Web Services running"
- Deployment is stuck on OU configuration tasks
- DC VM is deployed but AD services haven't fully started
**What this does:**
- Checks deployment logs for ADWS errors
- Waits for ADWS to initialize (5-15 minutes typical)
- Retries failed Ansible tasks (if auto_retry=True)
- Provides status updates during wait
Args:
wait_minutes: Minutes to wait for ADWS to start (default: 10, max: 30)
auto_retry: Automatically retry failed tasks after wait (default: True)
user_id: Optional user ID (admin only)
Returns:
Recovery result with status and next steps
Example:
# Handle ADWS recovery with auto-retry
result = await handle_adws_recovery(wait_minutes=10, auto_retry=True)
# Just wait and check status (manual retry later)
result = await handle_adws_recovery(wait_minutes=15, auto_retry=False)
r Nr2 �
rangeState�UNKNOWN�logs� z active directory web services�adwszBunable to find a default server with active directory web services)� DEPLOYING� CONFIGURING�no_action_neededzSNo ADWS errors detected. Deployment may have completed or failed for other reasons.zBCheck deployment status: quick_status() or get_deployment_status())�status�message� range_state�
suggestion�recovery_started� )r^ �adws_error_detectedr` rS rT �steps�< re zWaiting z minutes for ADWS to start...z9ADWS typically starts 5-15 minutes after domain promotionz!Checking deployment status every z seconds�READY�recovery_successr^ z5Deployment completed successfully during wait period!r_ u ✓ Deployment completed after � z minutes� adws_startedu' ✓ ADWS appears to have started after z#Attempting to retry failed tasks...zconfigure,user)rN r �tags�retry_initiated� retry_resultu0 ✓ Retry initiated - deployment should continue� retry_failed�erroru ✗ Retry failed: zCYou may need to manually retry: deploy_range(tags='configure,user')�
wait_completezCWait period completed. Check deployment status and retry if needed.z<If ADWS still not started, wait longer or check DC VM status)z'Check deployment status: quick_status()zDIf still failing, wait longer: handle_adws_recovery(wait_minutes=15)z6Or manually retry: deploy_range(tags='configure,user')z#Check DC VM is running: get_range()�
next_stepsz Failed to handle ADWS recovery)r^ ro r_ )�asyncior r r � get_range�get�
get_full_logs�
isinstance�dict�str�lowerr �min�append�range�sleep� deploy_range� Exception)rS rT r rr r �
range_infor` rX � logs_text�
logs_lower�has_adws_errorr � wait_secondsrC �checks�i� current_info�
current_state� current_logs�current_logs_textrm �er s �r �handle_adws_recovery�5create_deployment_tools.<locals>.handle_adws_recovery~ s �� � �N ��&�&�|�5F�G��f � &�~�~� 7� 7�� @�@�J�$�.�.� �y�A�K� !�.�.�w�7�7�D�0:�4��0F�0F������,�C�PT�I�I�"� � �*�J� 0�:�=� c��*�$�c�T�Xb�b�
� "�k�9U�&U�+� 0� t�#.�"f� -� � � -�'5� *� #�L�"� 5� (��
�F� �|�R�0�2�5�L� �N�!�3�F� �7�O� "� "�X�l�^�;X�#Y� Z� �7�O� "� "�#^� _� �7�O� "� "�%F�~�FV�V^�#_� `� �6�]�� �m�m�N�3�3�3� &-�^�^�%=�%=�g�%F� F� � ,� 0� 0� �y� I�
� �G�+�'9�F�8�$�(_�F�9�%��7�O�*�*�-L�Q�q�S�E�QY�+Z�[�/��7�7� &-�%:�%:�7�%C� C� �DN�|�]a�Db�Db�L�$4�$4�V�R�$@�hk�lx�hy�!�2�:K�:Q�:Q�:S�S�'5�F�8�$��7�O�*�*�-T�UV�WX�UX�TY�Ya�+b�c��' #�, �f�X� .�.� @��w��&�&�'L�M�r�)0� � �)D�)D� #� '� -� *E� *� $�L�
(9�F�8�$�-9�F�>�*��7�O�*�*�+]�^� �h� �#5�5�#2��x� �&i��y�!��w��&�&�'e�f�$�F�<� � (��/� /�{ A� 8�L 4� G� D�$�� !� r�'5�F�8�$�&)�!�f�F�7�O��7�O�*�*�-?��s�+C�D��7�O�*�*�+p�q�q�� r��( � �'�!� �Q��;�)� �
�� �s� �N#� M4 �L�*M4 �(L�)A?M4 �(N#�)BM4 �8L�9"M4 �L� A
M4 �)N#�*M4 �>L�?AM4 � AM4 � L �2L �3"L �8M4 �
N#�M4 �M4 �M4 �M4 �M4 � L �
M1�)>M,�'M4 �,M1�1M4 �4
N �>N�N �N#�N � N#)
NT�wazuh� recommendedFFNNNN)r� )r� r� )N)r� TFTN)Nrc �( )�
TN) r r
�toolrw rx �bool�listr �int)r �mcpr r$ r' r, r/ r3 r7 r: rA rG rL rQ r� r s ` @r �create_deployment_toolsr�
s� �� � �)�
*�C�"�6�*�H� �X�X�Z��$�s�C�x�.� � �� �X�X�Z� #� !� � -� � �48�6:�8<�37�v��v��t��v� �v� � v�
� v� �
v� �v� �4��S��>�*�T�1�v� #�3��8�n�t� 3�v� !%�S�#�X��� 5�v� ��S��>�D�0�v�
�v� �v�p �X�X�Z� !������
�� ��" �X�X�Z� !������
�� ��" �X�X�Z� !� -�!,��!,��!,� �!,�
� !,� �!,�J �X�X�Z� �C�$�J� �#� � � � �X�X�Z� �S�4�Z� �4� � � � �X�X�Z�
�c�D�j�
�C�
� �
� �X�X�Z� !� "� #� !� "�
5,��5,��5,� �5,� � 5,�
� 5,� �t��
5,�
�5,� �5,�n �X�X�Z� "� � �,��t��,��,� �,�
� ,� �,�& �X�X�Z� ,�3��:� ,�� ,� � ,� �X�X�Z� ,�d�3��8�n� ,�� ,� � ,� �X�X�Z� � � "�O��O��O� �t��O�
� O� �O�b �J� N)�__doc__�typingr �fastmcpr �ludus_mcp.core.clientr �#ludus_mcp.server.handlers.scenariosr �$ludus_mcp.server.handlers.deploymentr �'ludus_mcp.server.handlers.orchestrationr �$ludus_mcp.server.handlers.validationr � ludus_mcp.server.tools.utilsr
r r� � r� r �<module>r� s6 �� F� � � 0� ?� B� J� B� R�C�N� C�w� Cr�
Latest Blog Posts
- MCP Moves to the Linux Foundation: Neutral Stewardship for Agentic InfrastructureBy Om-Shree-0709 on .mcpanthropicLinux Foundation
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/tjnull/Ludus-FastMCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server