Content
# netexec-mcp
An [MCP](https://modelcontextprotocol.io) server that lets an AI agent drive
**[NetExec](https://github.com/Pennyw0rth/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:
<img src="https://raw.githubusercontent.com/mpgn/NetExec-mcp/main/netexec-mcp-recon-shares.svg"
width="100%" alt="NetExec-MCP recon mode">
With full mode:
<img src="https://raw.githubusercontent.com/mpgn/NetExec-mcp/main/netexec-mcp-full-gmsa.svg"
width="100%" alt="NetExec-MCP gmsa mode">
## Status
**v1 — all 10 nxc protocols, 135 tools** (121 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 135 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](#configuration-env-vars) and the
step-budget note beneath it.
## Requirements
- Python ≥ 3.10, [`uv`](https://docs.astral.sh/uv/) or [`pipx`](https://pipx.pypa.io/)
- **NetExec installed separately** — it is not a pip dependency and is not on PyPI.
See the [official install guide](https://www.netexec.wiki/getting-started/installation).
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)
```bash
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):
```json
{
"command": "uv",
"args": ["run", "--directory", "/path/to/netexec-mcp", "netexec-mcp"]
}
```
### Option B: install from PyPI (standalone `netexec-mcp` CLI)
```bash
# 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:
```json
{
"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*:
| Mode | What runs | Use when |
| --- | --- | --- |
| `suggest` | **Nothing executes.** Tools return the resolved nxc command for a human (the auditor) to run. Scope still enforced; offensive commands *can* be previewed. | You want the agent to plan commands you run yourself. |
| `recon` _(default)_ | Read-only enumeration; executes, credential-dumping and state-changing actions are refused. | Day-to-day authorized recon. |
| `loot` | Recon **plus** read-only credential-dumping (sam/lsa/ntds/gpp/roasting) — no state change on the target, but it harvests credential material. | Authorized credential-harvesting. |
| `full` | Everything executes, including state-changing / privilege-escalation actions (exec, write, spray, coercion-with-listener, exploits). | Authorized active testing. |
`NXC_MODE` is the canonical control; it defaults to `recon` when unset.
## Configuration (env vars)
| Var | Purpose | Default |
| --- | --- | --- |
| `NXC_COMMAND` | Base command (shlex-parsed). Falls back to `nxc`/`netexec` on `PATH`. | autodetect |
| `NXC_PROTOCOLS` | Comma-separated protocols to enable (e.g. `smb,ldap`). | all implemented |
| `NXC_TOOL_MODE` | Tool-surface presentation — `dynamic` (**default**: expose only meta-tools; the ~100-tool surface is discovered via `nxc_find_tool`/`nxc_catalog` and run via `nxc_call`) or `static` (list every tool). Dynamic keeps the ~46k-token surface out of the context window — required for small-context models, ~8× cheaper (same quality) on large ones. Set `static` to opt out (best for a decisive model, or to avoid discovery round-trips on a big-context model). | `dynamic` |
| `NXC_SCOPE` | Comma-separated target allowlist (IP/CIDR/range/hostname). **Fail-closed**: targets with no scope are rejected. | _(none)_ |
| `NXC_MODE` | Operating level — `suggest` / `recon` / `loot` / `full`. | `recon` |
| `NXC_TIMEOUT` | Per-call timeout (seconds). | `300` |
| `NXC_MAX_TARGETS` | Max target tokens per call. | `256` |
| `NXC_AUDIT_LOG` | Path to an append-only JSONL audit log. | _(none)_ |
| `NXC_WORKSPACE` | nxc workspace to read for richer results. | _(none — reads nxc.conf's `workspace`, else `default`)_ |
| `NXC_PATH` | Override nxc's home dir (mirrors nxc's own `NXC_PATH`); where `nxc.conf` and `workspaces/` are read from. | `~/.nxc` |
> **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:
> ```python
> 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
```bash
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 `4134e689`** (`4134e689…`, 2026-09-23, build 881)
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.
Connection Info
You Might Also Like
No recommendations available