vm-lab-agent

🚧 Status: Work in Progress

This is an active, incomplete project — parts of it are tested and working, parts are unverified against a real server, and there's a known dependency bug not yet fixed (see Known Issues below). Read SECURITY.md before running this against a lab you care about.

A small, sandboxed MCP server for students running network engineering / SOC analyst home labs (PNETLab, VMware Workstation, Wazuh, Kali, etc.). It lets an AI agent power VMs on/off, manage snapshots, build and control PNETLab topologies, and verify device configuration -- within an explicit allowlist you control, with every destructive action gated behind a confirmation step and every action logged.

Built for hands-on CCNP / Security+ / SOC-analyst practice: spin up a topology, configure it yourself in PNETLab's own console (the actual exam-relevant skill), and let the agent check your work with real show command output afterward.

Compatible with any MCP client -- Claude Code, or any other tool that speaks the Model Context Protocol. Not locked to a single AI provider.

This project was designed and built with the assistance of Claude (Anthropic). See CREDITS.md. It is not an official Anthropic product and isn't endorsed by Anthropic.

Known issues (honest, not hidden)

• requirements.txt has a real, currently-unresolved dependency conflict. netmiko==4.7.0 requires paramiko<5.0; the two aren't simultaneously installable as currently pinned in this repo without manual adjustment. Workaround until fixed: pin paramiko==4.0.0 instead of whatever's currently in the file.
• pnetlab_lab_add_network and pnetlab_lab_connect_interface are built from an inferred API pattern, not a directly-observed working trace -- see SECURITY.md.
• dynamips and docker image types aren't supported by pnetlab_delete_image -- their directory layout wasn't confirmed with enough confidence to build against safely.
• VMware control tools aren't containerized the way the PNETLab SSH tools are -- vmrun needs to talk to VMware Workstation running on your actual host. See SECURITY.md for the full explanation.

None of these block basic use (VM power/snapshot/backup, PNETLab image search/install/delete, and node power/status on an existing topology all work and are tested) -- they're specifically the rough edges left from finishing this in one long build session.

Before you do anything else: read SECURITY.md

Seriously. SECURITY.md explains exactly what this agent can and can't touch. It also covers a real, dated MCP vulnerability (OX Security's April 2026 disclosure) and exactly why this project's design does and doesn't fall inside that exposure.

See REFERENCES.md for the primary sources behind every non-obvious design decision, and LEARNING.md if you want this project to double as CCNP/Security+/SOC-analyst study material rather than just a tool you install and forget.

What it does

Tool	Confirm required?	What it does
list_managed_vms	No (read-only)	Lists VMs on your allowlist
vm_status	No (read-only)	Checks if a VM is running
vm_power_on	Yes	Powers on a VM
vm_power_off_soft	Yes	Graceful guest OS shutdown
vm_power_off_hard	Yes, + per-VM allow_destructive	Force power-off
vm_snapshot_create	Yes	Takes a snapshot
vm_snapshot_revert	Yes, + per-VM allow_destructive	Reverts to a snapshot
vm_clone_create	Yes	Creates a new VM by cloning an allowlisted one; new VM is not auto-allowlisted
vm_backup_to_location	Yes	Copies a VM's entire folder to a location you choose
vm_delete_permanently	Yes, + 3 more gates	Permanently deletes a VM. Not registered as a tool unless enable_vm_deletion: true.
pnetlab_search_image	No (read-only)	Searches PNETLab's ishare2 catalog
pnetlab_list_installed	No (read-only)	Lists images already installed, by type
pnetlab_pull_image	Yes	Downloads/installs an image
pnetlab_delete_image	Yes	Deletes an installed image (qemu + iol/bin only)
pnetlab_fix_permissions	Yes	Runs the standard post-install permission fix
device_read_config	No (read-only)	Runs a show command against a lab device -- only show commands accepted
pnetlab_lab_topology	No (read-only)	Reads a managed lab's current nodes
pnetlab_lab_node_status	No (read-only)	Reads running/stopped status of every node
pnetlab_lab_node_power	Yes	Starts or stops a specific node
pnetlab_lab_create	Yes	Creates a new empty lab; not auto-allowlisted
pnetlab_lab_add_node	Yes	Adds a router/switch/etc. to a lab's topology
pnetlab_lab_add_network	Yes	Adds a network/switch object (moderate confidence)
pnetlab_lab_connect_interface	Yes	Connects a node's interface to a network (moderate confidence)

Setup

1. Prerequisites

• Python 3.12+
• VMware Workstation Pro/Player with vmrun installed
• A PNETLab server (optional -- only needed for PNETLab-related tools)

2. Install

git clone https://github.com/vikramjeet8105-engg/vm-lab-agent.git
cd vm-lab-agent
pip install -r requirements.txt

If this fails on a paramiko/netmiko conflict, open requirements.txt and change the paramiko line to paramiko==4.0.0, then retry.

3. Configure

cp config.example.yaml config.yaml
cp .env.example .env

Edit config.yaml: list the exact VMs (and optionally labs) you want the agent to touch. Anything not listed here is invisible to the agent -- read SECURITY.md for why this matters.

4. Test it locally

python -m pytest tests/ -v

5. Connect it to your MCP client

claude mcp add --transport stdio vm-lab-agent -- python -m src.server

Contributing

Issues and PRs welcome, especially fixes for anything in Known Issues above.

License

MIT -- see LICENSE.