Skip to content
Back to search

NetExec-mcp

NetExec MCP

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mpgn--netexec-mcp/badge.svg)](/listings/mpgn--netexec-mcp)

HTML

<a href="/listings/mpgn--netexec-mcp"><img src="/api/listings/mpgn--netexec-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

NetExec is not a dependency: install it first ([installation guide](https://www.netexec.wiki/getting-started/installation)). Then, with Python 3.10 or later:

pipx install netexec-mcp
# or
uv tool install netexec-mcp

On startup the server runs `nxc --version` and refuses to start if NetExec is not found. If `nxc` is not on your `PATH`, set `NXC_COMMAND`, e.g. `NXC_COMMAND="uv run --no-sync --directory /opt/NetExec netexec"`.

From source

git clone https://github.com/mpgn/NetExec-mcp && cd NetExec-mcp
uv sync
NXC_SCOPE=10.0.0.0/24 uv run --no-sync netexec-mcp

In your agent's config, launch it with `uv` and the arguments `run --no-sync --directory /path/to/NetExec-mcp netexec-mcp` (see `.mcp.json.example`). With `--no-sync`, uv does not check the environment at each start, so run `uv sync` again after each `git pull`. If NetExec also runs from a source checkout, keep `--no-sync` in `NXC_COMMAND` too: without it, each nxc call re-syncs NetExec's environment under a lock, so parallel calls run one after another and the server starts more slowly. Run `uv sync` in the NetExec checkout after each update.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 234 lines
  1. # netexec-mcp
  2. An [MCP](https://modelcontextprotocol.io) server that plugs [NetExec](https://github.com/Pennyw0rth/NetExec) (`nxc`) into an AI agent: Claude Code, Cursor, opencode, or your own. The agent calls NetExec as one of its tools, inside the scope and mode you set. **For authorized security testing only.**
  3. Recon mode:
  4. <img src="https://raw.githubusercontent.com/mpgn/NetExec-mcp/main/netexec-mcp-recon-shares.svg"
  5. width="100%" alt="NetExec-MCP recon mode">
  6. Full mode:
  7. <img src="https://raw.githubusercontent.com/mpgn/NetExec-mcp/main/netexec-mcp-full-gmsa.svg"
  8. width="100%" alt="NetExec-MCP gmsa mode">
  9. ## Why
  10. Instead of letting the agent type `nxc` commands in a shell:
  11. - **Fewer tokens.** The agent sees 5 small meta-tools (about 1k tokens) and looks up the tool it needs, instead of parsing the `nxc` help to work out the right command. Small local models fit, and big ones cost less.
  12. - **Scope enforced.** Every target is checked against `NXC_SCOPE`. Anything outside is refused.
  13. - **Actions under control.** `NXC_MODE` decides what the agent may run, from suggesting commands only to full exploitation.
  14. - **Structured results.** Shares, hashes and admin rights come back as JSON fields, not terminal text.
  15. - **Audit log.** Every command, whether it ran, was previewed or was refused, is logged.
  16. It covers the 10 nxc protocols and NetExec's `-M` modules. SMB, LDAP, WinRM, MSSQL, SSH, RDP and WMI are tested against a live Active Directory lab; FTP, NFS and VNC are unit-tested only.
  17. ## Install
  18. NetExec is not a dependency: install it first ([installation guide](https://www.netexec.wiki/getting-started/installation)). Then, with Python 3.10 or later:
  19. ```bash
  20. pipx install netexec-mcp
  21. # or
  22. uv tool install netexec-mcp
  23. ```
  24. On startup the server runs `nxc --version` and refuses to start if NetExec is not found. If `nxc` is not on your `PATH`, set `NXC_COMMAND`, e.g. `NXC_COMMAND="uv run --no-sync --directory /opt/NetExec netexec"`.
  25. ### From source
  26. ```bash
  27. git clone https://github.com/mpgn/NetExec-mcp && cd NetExec-mcp
  28. uv sync
  29. NXC_SCOPE=10.0.0.0/24 uv run --no-sync netexec-mcp
  30. ```
  31. In your agent's config, launch it with `uv` and the arguments `run --no-sync --directory /path/to/NetExec-mcp netexec-mcp` (see `.mcp.json.example`). With `--no-sync`, uv does not check the environment at each start, so run `uv sync` again after each `git pull`. If NetExec also runs from a source checkout, keep `--no-sync` in `NXC_COMMAND` too: without it, each nxc call re-syncs NetExec's environment under a lock, so parallel calls run one after another and the server starts more slowly. Run `uv sync` in the NetExec checkout after each update.
  32. ## Configure
  33. The server is configured with environment variables, passed by your agent (see below).
  34. <a id="configuration-env-vars"></a>
  35. | Variable | What it does | Default |
  36. | --- | --- | --- |
  37. | `NXC_SCOPE` | **Required.** Allowed targets: IPs, CIDRs, ranges or hostnames, comma-separated. Fail-closed: with no scope, every target is refused. | _none_ |
  38. | `NXC_MODE` | `suggest`, `recon`, `loot` or `full` (see below). | `recon` |
  39. | `NXC_AUDIT_LOG` | Audit log, one JSON line per command: run, previewed or refused. Strongly recommended. | _none_ |
  40. | `NXC_PATH` | NetExec home: `nxc.conf`, workspace databases, logs and retrieved files. Passed on to nxc. Use one per engagement, as an absolute path (see [below](#keep-the-agents-netexec-apart-from-yours)). | `~/.nxc` |
  41. | `NXC_COMMAND` | How to launch NetExec, parsed like a shell command, e.g. `uv run --no-sync --directory ~/NetExec netexec`. | `nxc` or `netexec` on `PATH` |
  42. | `NXC_PROTOCOLS` | Protocols to expose, comma-separated, e.g. `smb,ldap`. | all 10 |
  43. | `NXC_TOOL_MODE` | `dynamic`: the agent sees 5 meta-tools and looks up the others. `static`: every tool is listed up front, which costs tens of thousands of tokens of context; use it only with a large-context model that should skip the lookup. | `dynamic` |
  44. | `NXC_MODULE_CATALOG` | Where dynamic mode finds the `-M` modules: `static` (the list shipped with the server) or `live` (`nxc <proto> -L` at startup, for custom modules or an nxc newer than the list). The mode gate always reads the installed nxc. | `static` |
  45. | `NXC_TIMEOUT` | Timeout of one call, in seconds. | `300` |
  46. | `NXC_MAX_TARGETS` | Maximum targets in one call. | `256` |
  47. | `NXC_LOG_DIR` | One nxc log file per executed call, with the full raw output even when the agent's view of it is capped. Holds secrets: files are created `0600`. | _none_ |
  48. | `NXC_WORKSPACE` | Workspace the `workspace_*` readers look in. Read side only: nxc keeps writing to the workspace set in its `nxc.conf`. | `nxc.conf`'s, else `default` |
  49. | `NXC_DOWNLOADS_DIR` | Where retrieved files land (e.g. `smb_get_file`) when the call gives no absolute path. | `<NXC_PATH>/downloads` |
  50. Each mode includes the previous one:
  51. | Mode | What the agent can run |
  52. | --- | --- |
  53. | `suggest` | Nothing. Tools return the `nxc` command they would run, for you to run. |
  54. | `recon` _(default)_ | Read-only enumeration: hosts, shares, users, groups, policies... |
  55. | `loot` | + credential collection: SAM, LSA, NTDS, GPP, the Kerberos tickets cached on a host, Kerberoasting, AS-REP roasting. |
  56. | `full` | + everything else: command execution, uploads, spraying, coercion, exploits. |
  57. Scope and mode are read once at startup. The agent cannot change them; to raise them, edit the config and restart the server.
  58. ### Keep the agent's NetExec apart from yours
  59. NetExec keeps its settings, its workspace databases (with every credential it finds), its logs and the files it retrieves in one home folder, `~/.nxc` by default. If the agent shares that folder with you, it can read the credentials of your other engagements, and its results mix with yours. So give the server its own folder with `NXC_PATH`, one per engagement:
  60. ```bash
  61. mkdir -p ~/.netexec-mcp/acme
  62. ```
  63. ```json
  64. "env": {
  65. "NXC_SCOPE": "10.0.0.0/24",
  66. "NXC_PATH": "/home/you/.netexec-mcp/acme",
  67. "NXC_AUDIT_LOG": "/home/you/.netexec-mcp/acme/audit.jsonl"
  68. }
  69. ```
  70. The server passes `NXC_PATH` on to every nxc it runs, so everything the agent's calls produce stays in that folder, while your own `nxc` keeps using `~/.nxc`. To look at what the agent found, run your own tools with the same folder, for example `NXC_PATH=$HOME/.netexec-mcp/acme nxcdb`.
  71. - **The server fixes the path before NetExec reads it.** NetExec does not expand `~` in `NXC_PATH` and cannot create a missing parent folder, so when the server starts, it turns the value into a full path, expands `~` and creates the folder. Without this, a relative path would point to one folder for the server and to another one for NetExec.
  72. - **Relative file paths start from that folder.** When a call names a file that NetExec reads (a Kerberos ticket cache, a certificate or key, a file to upload), a relative path is looked up in `NXC_PATH`, then in its `output`, `downloads` and `loot` folders, where the tools write their files. If the file is not there, the call is refused before NetExec runs, so use a full path for a file kept anywhere else.
  73. - **`NXC_WORKSPACE` does not separate engagements.** It only changes the workspace the server reads, while nxc keeps writing to the workspace set in its `nxc.conf`.
  74. To choose which NetExec the server runs, set `NXC_COMMAND`. By default, it is the `nxc` (or `netexec`) on your `PATH`; for a source checkout of NetExec, see [From source](#from-source).
  75. ## Plug it into your agent
  76. ### Claude Code
  77. ```bash
  78. claude mcp add netexec \
  79. -e NXC_SCOPE=10.0.0.0/24 \
  80. -e NXC_MODE=recon \
  81. -e NXC_PATH=$HOME/.netexec-mcp/acme \
  82. -e NXC_AUDIT_LOG=$HOME/.netexec-mcp/acme/audit.jsonl \
  83. -- netexec-mcp
  84. ```
  85. Check with `claude mcp list`, or `/mcp` inside Claude Code.
  86. ### Cursor, Claude Desktop
  87. For Cursor, add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project). For Claude Desktop, open **Settings > Developer > Edit Config**, add it to `claude_desktop_config.json` and restart.
  88. ```json
  89. {
  90. "mcpServers": {
  91. "netexec": {
  92. "command": "netexec-mcp",
  93. "env": {
  94. "NXC_SCOPE": "10.0.0.0/24",
  95. "NXC_MODE": "recon",
  96. "NXC_PATH": "/home/you/.netexec-mcp/acme",
  97. "NXC_AUDIT_LOG": "/home/you/.netexec-mcp/acme/audit.jsonl"
  98. }
  99. }
  100. }
  101. }
  102. ```
  103. Desktop apps may not see your shell `PATH`. If the server does not start, use the absolute path of `netexec-mcp` (`which netexec-mcp`) and set `NXC_COMMAND` to the full path of `nxc`.
  104. ### opencode + Ollama (local)
  105. Add to `opencode.json`, next to your Ollama provider:
  106. ```json
  107. {
  108. "$schema": "https://opencode.ai/config.json",
  109. "mcp": {
  110. "netexec": {
  111. "type": "local",
  112. "command": ["netexec-mcp"],
  113. "environment": {
  114. "NXC_SCOPE": "10.0.0.0/24",
  115. "NXC_MODE": "recon",
  116. "NXC_PATH": "/home/you/.netexec-mcp/acme",
  117. "NXC_AUDIT_LOG": "/home/you/.netexec-mcp/acme/audit.jsonl"
  118. }
  119. }
  120. }
  121. }
  122. ```
  123. Use a model with solid tool calling (Qwen3 14B is a good start) and at least 32k tokens of context.
  124. ### Your own agent (Python)
  125. Any MCP SDK works. With [Pydantic AI](https://github.com/pydantic/pydantic-ai) (`pip install pydantic-ai`):
  126. ```python
  127. import os
  128. from fastmcp.client.transports import StdioTransport
  129. from pydantic_ai import Agent
  130. from pydantic_ai.mcp import MCPToolset
  131. netexec = MCPToolset(
  132. StdioTransport(
  133. command="netexec-mcp",
  134. args=[],
  135. env={
  136. "NXC_SCOPE": "10.0.0.0/24",
  137. "NXC_MODE": "recon",
  138. "NXC_PATH": os.path.expanduser("~/.netexec-mcp/acme"), # created beforehand
  139. },
  140. ),
  141. include_instructions=True, # give the agent the server's instructions (off by default)
  142. )
  143. # Any Pydantic AI model works. "ollama:" reads OLLAMA_BASE_URL (e.g. http://localhost:11434/v1)
  144. agent = Agent("ollama:qwen3:14b", toolsets=[netexec])
  145. result = agent.run_sync("Which hosts in scope don't require SMB signing?")
  146. print(result.output)
  147. ```
  148. Each action takes about two tool calls (find the tool, then run it). If your agent caps the number of steps per answer, raise it.
  149. ## Use it
  150. Ask the agent to "run a NetExec health check": it should answer with your NetExec version and its home folder (`nxc_home`), which should be your `NXC_PATH`. Then give it tasks:
  151. - _"Which hosts in 10.0.0.0/24 don't require SMB signing?"_
  152. - _"With robin / Summer2026!, which shares can I write to?"_
  153. - _"Kerberoast the domain with these credentials."_ (needs `loot`)
  154. - _"Dump LSA on 10.0.0.12 and see if anything lets me move further."_ (needs `loot`, `full` to run commands)
  155. Before you start:
  156. - **One `NXC_PATH` per engagement.** The agent can read credentials stored in NetExec's workspace database, including ones from a previous engagement (see [Keep the agent's NetExec apart from yours](#keep-the-agents-netexec-apart-from-yours)).
  157. - **Cloud models see your results.** Usernames, hashes and hostnames are sent to the model provider. Use a local model if the rules of engagement require it.
  158. - **For authorized testing only.**
  159. ## Learn more
  160. - [Building a MCP for NetExec](https://mpgn.fr/building-a-mcp-for-netexec/): how netexec-mcp works, in depth.
  161. - [You're Building Your MCP Wrong](https://mpgn.fr/youre-building-your-mcp-wrong/): why the dynamic mode exists, with benchmarks.
  162. ## Reference
  163. ### Resources
  164. The server also publishes guides and data as MCP resources:
  165. - `netexec://guide/operating-modes`, `netexec://guide/auth`, `netexec://guide/workflows` (including the cross-protocol gMSA chain), `netexec://guide/workspace`, `netexec://guide/safety`
  166. - `netexec://catalog/tools`: the tool inventory
  167. - `netexec://workspace/credentials`, `/admins`, `/loggedin`, `/hosts`: the NetExec workspace database, like the `workspace_*` tools
  168. ### Safety
  169. Every command goes through one checkpoint before it runs: the scope allowlist (fail-closed), the mode gate, the target cap and the timeout. Each command is written to the audit log, whether it ran, was previewed or was refused. nxc is run as an argument list, never through a shell, and NetExec is never imported as a library.
  170. ### nxc version
  171. The tools and their flags are checked against **nxc 1.5.1 "Yippie-Ki-Yay", commit `df95344d`** (2026-11-16, build 1239). Check yours with `nxc --version`. NetExec moves fast and sometimes renames or removes flags. An older nxc rejects a flag it does not know yet. A newer nxc usually keeps a flag it has removed and answers it with a `[REMOVED]` line instead of doing the work, and the server reports that answer as an error (`removed_option`) rather than as a result that came back empty.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.