netexec-mcp

An MCP server that lets an AI agent drive NetExec (nxc) for authorized security testing only.

It is a pure subprocess wrapper: it shells out to the nxc CLI as an argv list (never shell=True, never importing NetExec as a library) and declares no nxc dependency. How nxc itself is installed (PATH / uv / pipx / docker) is entirely up to you.

With recon mode:

With full mode:

Status

v1 — all 10 nxc protocols, 128 tools (114 protocol tools + 9 discovery/meta-tools + 5 offline workspace-DB readers). SMB, LDAP, WinRM, MSSQL, SSH, RDP, WMI, FTP, NFS, and VNC are built out (native flags, credential dumping/gathering, command exec, file transfer, promoted high-value -M modules, and structured output). The first seven are validated end-to-end against a live AD lab; FTP/NFS/VNC are source-verified + unit-tested (no lab yet). A 3-level safety model gates everything; the long tail of nxc -M modules is reachable via meta-tools.

Built for small / local models

With 128 tools, listing every one to the model would spend ~46k tokens of context before any work starts enough to overflow a small-context (≤8B / 32k) model and to make every call on a large one needlessly expensive. So the default NXC_TOOL_MODE is dynamic: only a handful of meta-tools are exposed (nxc_catalog, nxc_find_tool, nxc_describe_tool, nxc_call, nxc_health), and the model discovers and dispatches the real tools on demand. This keeps the tool surface out of the context window required to run on small local models, and cheaper (same quality) on large ones. Set NXC_TOOL_MODE=static to opt out and list every tool. See the NXC_TOOL_MODE row under Configuration and the step-budget note beneath it.

Requirements

• Python ≥ 3.10, uv or pipx
• NetExec installed separately — it is not a pip dependency and is not on PyPI. See the official install guide. Any install works as long as nxc / netexec is reachable on PATH or via NXC_COMMAND; the server runs nxc --version on boot and refuses to start if it can't find it.

Quick start

Option A: uv (run from a source checkout)

uv sync

# Point at your nxc install (example: a uv-managed source checkout)
export NXC_COMMAND="uv run --directory ~/NetExec netexec"
export NXC_SCOPE="10.0.0.0/24"          # required to target anything (fail-closed)

uv run netexec-mcp

MCP client config (command/args launch the server itself):

{
  "command": "uv",
  "args": ["run", "--directory", "/path/to/netexec-mcp", "netexec-mcp"]
}

Option B: install from PyPI (standalone netexec-mcp CLI)

# Pick one installer — all put `netexec-mcp` on PATH:
pipx install netexec-mcp                 # pipx
uv tool install netexec-mcp              # uv
# or run without installing:
uvx netexec-mcp                          # uv, one-shot

export NXC_COMMAND="nxc"                 # or however your nxc install is invoked
export NXC_SCOPE="10.0.0.0/24"

netexec-mcp

MCP client config — netexec-mcp is on PATH, so no uv/--directory wrapper:

{
  "command": "netexec-mcp",
  "args": []
}

On boot the server runs <base> --version and refuses to start if it fails (unless mode suggest, which downgrades that to a warning). See .mcp.json.example for a ready-to-edit MCP client config (uv variant).

Operating modes (NXC_MODE)

Four escalating levels of how much the server is allowed to do:

NXC_MODE is the canonical control; it defaults to recon when unset.

Configuration (env vars)

Dynamic mode needs a bigger client-side step budget. max_steps (how many tool calls the agent may make) is not an MCP setting — the server can't see or set it. It lives in your client's agent loop. In dynamic mode each action costs ~2 calls (nxc_find_tool → nxc_call), so a chain that needs 4 calls in full needs ~10 in dynamic. Set the budget high enough there, e.g. mcp-use:

MCPAgent(llm=ChatOllama(model="qwen3:14b"), client=client, max_steps=30)  # default is 5 — too low

Other clients (Claude Desktop, Cursor, Cline, …) have their own max-iterations setting. The MCP can only hint this via its startup instructions; it can't enforce it.

Resources

The server publishes cheatsheets as MCP resources so an agent can ground itself:

• netexec://guide/operating-modes
• netexec://guide/auth
• netexec://guide/workflows (incl. the cross-protocol gMSA chain)
• netexec://guide/workspace (cached recall vs. live — when to use which)
• netexec://guide/safety
• netexec://catalog/tools (live, auto-generated tool inventory)
• netexec://workspace/credentials, /admins, /loggedin, /hosts (workspace DB data, same source as the workspace_* tools, filterless)

Safety & guardrails

Enforced at a single choke point before any command runs:

• Scope allowlist (NXC_SCOPE) — every target checked; fail-closed.
• Mode gating (NXC_MODE) — offensive actions refused outside full.
• Target cap + per-call timeout.
• Audit log — every command (executed / dry-run / rejected) appended as JSON.
• No shell — nxc is invoked as an argv list; nothing is shell-interpreted.

Example: the gMSA credential chain

smb_lsa (full)            -> secrets[] incl. { type: "gmsa_id", gmsa_id, ntlm }
ldap_gmsa_convert_id      -> resolves the gmsa_id to an account name (gmsa-robin$)
<any tool>                -> replay with username="gmsa-robin$", ntlm_hash=<nt>

Development

uv run pytest -q          # mocked-subprocess unit tests (no nxc/network needed)

Architecture and milestone history live in PLAN.md. Tools/flags are verified against the nxc source (nxc/protocols/<proto>/proto_args.py) — --help lists args the handlers reject.

nxc version

This MCP is a subprocess wrapper and pins no nxc dependency, but its tools/flags are verified against a specific nxc build:

nxc 1.5.1 "Yippie-Ki-Yay", commit 2bdc7e5e (2bdc7e5e…, 2026-08-30, build 677)

Check your local build with nxc --version (it prints version - codename - commit - build). nxc moves fast and occasionally moves/removes flags, so when you bump nxc, re-verify the affected protocol's proto_args.py + handler and re-run the tests.