netexec-mcp · engineering journal · what it is

Building a MCP for NetExec

NetExec is the tool most people reach for on an Active Directory engagement. netexec-mcp lets an AI agent drive it: 121 tools across ten protocols, behind a scope allowlist, four capability tiers, machine-readable results and an audit log.

By Martial Puygrenier (mpgn) · 12 min read · tested on nxc 1.5.1
Fig. 00 · What one tool call passes through
The ask →
Tool call
set by · the model
Names a tool and fills typed arguments. It does not write a command line.
Checkpoint 1 →
Scope
NXC_SCOPE
Every target checked against an allowlist. No scope configured means nothing runs.
Checkpoint 2 →
Mode
NXC_MODE
Read, harvest or act. An action above the configured tier is refused, not attempted.
Checkpoint 3 →
Cap
NXC_MAX_TARGETS
A ceiling on how many target entries a single call may pass. A CIDR is one entry, whatever it expands to.
Execution →
argv
set by · the server
nxc is spawned as an argument list with a hard timeout. Nothing is shell-interpreted.
What comes back
JSON + audit
set by · the server
Output parsed into records the model can act on. One JSON line written for the report.

The three checkpoints are configured by the person who launches the server, before the model exists. They are environment variables, not tool parameters, so there is no argument the model can pass to widen them.

TL;DR

nxc is built for a human at a terminal: colour-coded tables, banners, a shell you copy credentials out of by hand. A model driving it inside a harness needs none of that and trips over all of it. This MCP exists to close that gap, and it does two things a raw shell can't.

It makes nxc legible to a model. Calls are native to the harness instead of typed into a shell. Results come back as parsed JSON facts rather than tables the model has to read off a screen, so ground-truth extraction happens in deterministic code instead of the model eyeballing a green tick and guessing. Typed credentials are carried across protocol hops, so a six-hop chain never hinges on a copied character. And because the facts are compact rather than raw terminal noise, the model spends its tokens reasoning instead of parsing.

It keeps nxc bounded. Every action passes three checkpoints the model can ask past but not argue past: a fail-closed scope allowlist (no scope, nothing runs), a four-rung action-mode ladder (suggest → recon → loot → full), and a target cap, with every call written to an audit log.

It adds no new capability to nxc itself. The first half makes nxc usable by a model at all. The second makes it safe to point at a real network.

Section 01 · the loop

An engagement is not one command

An internal Active Directory test in NetExec is rarely a single invocation. It is a few dozen, and a surprising share of the operator's time goes into moving one command's output into the next command's input.

You spray a credential across a /24 and get a [+]. You enumerate shares. You find a host where that account is a local admin, dump SAM, and read an NT hash out of a scrolling, colour-coded terminal. You paste it into the next command behind -H. That gets you onto a second host, where LSA secrets hand you a gMSA blob, which is useless until you switch protocol to LDAP to resolve it into an account name, at which point you switch back to SMB and replay it.

Every one of those steps is a well-understood thing NetExec already does well. The work between them is clerical: copying a hash, remembering which flag takes it, remembering that the thing you need next lives under a different protocol. It is too structured to be interesting and too stateful to shell-script.

That gap is the whole reason an agent is appealing here. An agent is good at exactly the part a person is bad at: holding twelve intermediate facts in mind and knowing that fact number four is the input to step number nine. The question was never whether a model could be useful on an engagement. It was what you have to build so that letting one near a domain controller is a defensible thing to do.

Section 02 · the shortcut

Why not just give the model the nxc CLI?

This is the first thing anyone asks, and it is a fair question. NetExec is already a command-line program. Every agent framework ships a shell tool, and you can hand the model a skill that documents every flag. So why write 121 typed tools to wrap a CLI that already works? It looks like a lot of effort to arrive exactly where you started: at a subprocess call.

Handing over the CLI means the model writes every command itself, as free text, and from memory. NetExec is large: many protocols, many modules, a syntax that shifts between releases. So it half-remembers a flag, reaches for one that was removed two versions ago, mistypes a target. The shell runs whatever it produced, verbatim, against a live network, with nothing in between to catch it.

The MCP ends up in the same place. The server spawns the same binary you would, through subprocess; you land on a subprocess either way. What changes is who writes the arguments. The model stops composing command strings and starts filling named, typed fields. It says which target, which credential, which module; the server owns the exact flags, the current syntax, the assembly of the argument list. The part the model kept getting wrong is no longer the model's to write.

this guy is onto something
Section 03 · the thing

What netexec-mcp actually is

Deliberately boring at its core: a pure subprocess wrapper. It shells out to the nxc CLI as an argument list. It never uses shell=True, and it never imports NetExec as a library. It declares no dependency on nxc at all, so however you install it (PATH, uv, pipx, a container) stays entirely your business. On boot the server runs nxc --version and refuses to start if it cannot find it.

That choice matters more than it sounds. Because the server only ever produces argument lists, there is no string that a model can craft which becomes shell syntax. And because it does not import NetExec, upgrading nxc does not mean upgrading the MCP.

On top of that sit 121 tools across ten protocols. Each one is a single intent with typed parameters: smb_shares(targets, username, password) rather than a command line the model has to assemble correctly. They all share one authentication model, about seventeen parameters wide, covering passwords, NTLM hashes, Kerberos, LAPS and certificates. That shared model is what makes a credential portable: an account you recovered through SMB is replayable through LDAP, MSSQL or WinRM without the model having to relearn a single flag.

121 tools · as the catalog reports them (nxc 1.5.1)
Protocol Not a protocol
smb42
ldap24
mssql12
winrm8
nfs7
ssh5
workspace5
not a protocol
ftp4
nxc4
not a protocol
rdp4
wmi4
vnc2

Every tool is one square — 121 in all. You can count the small groups by eye; the big ones read as texture. The two hatched blocks, workspace and nxc, are the groups that are not protocols.

Total · 121 tools 12 groups
The two groups that are not protocols

workspace reads NetExec's own local database offline, and nxc reaches the long tail of -M modules that were not worth promoting to their own tool. Both are covered further down.

Alongside the tools, the server publishes a handful of MCP resources: short cheatsheets on the operating modes, the authentication model, the common workflows, the workspace database and the safety rules, plus a live inventory of every tool. An agent can read those to ground itself instead of guessing, which turns out to matter a great deal for smaller models.

One structural point worth stating plainly, because it shapes everything after it: this is a wrapper, so it is exactly as capable as NetExec and not one step more. It adds no exploits and no techniques. Everything below is about restricting what nxc is allowed to do, never about extending it.

Section 04 · problem 1

Scope is not a suggestion

The server takes an allowlist and refuses everything outside it. The checking is more careful than a string comparison, because the ways a target can be written are more varied than they look:

  • ▸CIDR. A network target must be a genuine subnet of an allowed network. Permitting 10.4.10.0/24 does not let a call through for 10.4.0.0/16, even though the allowed range sits inside it.
  • ▸Ranges. NetExec's own range syntax (10.4.10.1-20, and the last-octet shorthand) is expanded, and both ends have to land inside one allowed network.
  • ▸Hostnames. A name passes if it matches an allowed scope entry, or if it resolves to in-scope addresses. Every resolved address of a family the scope covers must be in scope, so DNS round-robin cannot slip an out-of-scope answer through.
Fig. 01 · A refusal, as the model receives it
→ the model widens the search on its own initiative
smb_enum_hosts({"targets": ["10.4.0.0/16"]})
← nothing ran
target(s) out of scope: 10.4.0.0/16 (allowed: 10.4.10.0/24)
Section 05 · problem 2

"Can the agent do this" is a ladder, not a switch

The instinct is a boolean: the agent is either allowed to run offensive tooling or it is not. That framing falls apart within about an hour of real use, because the interesting question is not whether the agent acts, it is how far a given action reaches. Enumerating shares, dumping a SAM hive and running a command on a domain controller are three different kinds of risk, and lumping them together means picking between an agent that cannot do its job and one you would not leave alone with a DC.

So there are four levels, set by one environment variable.

Fig. 02 · NXC_MODE, from planning to acting
suggest
nothing executes

Every tool returns the exact nxc command it would have run, resolved and ready, for a human to paste. The scope check still applies. The agent plans; you press the button. This is the mode for the day you want the help but not the autonomy.

recon
the default

Read-only enumeration runs. Hosts, shares, users, groups, computers, sessions, policies. Anything that dumps credential material or changes state on the target is refused. This is where most of an engagement actually lives, and it is the default precisely because it is the level you would pick if you had to pick without thinking.

loot
read-only, but it harvests

Recon, plus read-only credential collection: SAM, LSA, NTDS, GPP passwords, Kerberoasting and AS-REP roasting. Nothing on the target changes. Secrets leave the building.

full
state-changing

Everything: command execution, file writes, password spraying, coercion with a listener, the exploit modules. Assume anything here is visible to a defender and reversible only by hand. My favorite mode but don't copy me ^^

One function decides this for every tool in the server, so a new tool is gated the moment it is tagged, and there is no path that reaches nxc without passing it.

Every outcome is written down

Executed, previewed or refused, each command is appended as one JSON object to the audit log, with the tool that issued it, the resolved argument list, the outcome and a timestamp. That log lives on disk, so it outlasts the model's own memory, which makes it the only trustworthy account of what was actually run. It is also the artefact you hand a client who asks.

Section 06 · problem 3

Making NetExec legible to a machine

nxc prints results as aligned columns with colour codes and a status marker. Handing that to a model and asking it to extract the permissions on a share works most of the time, which is the worst possible reliability profile for a security tool. So the server parses, and returns facts.

The alternative is not hypothetical. In an earlier benchmark run, with the lab accidentally offline, every command returned empty output, and a 30B model read that emptiness and produced a plausible-looking set of NTDS hashes for a domain controller that was not even powered on. Nothing errored. Every hop looked like it had worked. A silent empty result is far more dangerous than a loud failure.

Fig. 03 · The same result, twice (smb_shares)
What nxc prints, for a person
SMB  10.4.10.10  445  WINTERFELL  [*] Windows 10 / Server 2019
SMB  10.4.10.10  445  WINTERFELL  [+] north.sevenkingdoms.local\jon.snow
SMB  10.4.10.10  445  WINTERFELL  [*] Enumerated shares
SMB  10.4.10.10  445  WINTERFELL  Share      Permissions  Remark
SMB  10.4.10.10  445  WINTERFELL  -----      -----------  ------
SMB  10.4.10.10  445  WINTERFELL  ADMIN$                  Remote Admin
SMB  10.4.10.10  445  WINTERFELL  C$                      Default share
SMB  10.4.10.10  445  WINTERFELL  public     READ,WRITE

Alignment carries the meaning. An empty permissions column is not a missing value, it means the account cannot touch that share. A model reading this as text has to infer that from whitespace.

What the tool returns, for a model
{
  "authenticated": true,
  "admin": false,
  "shares": [
    {"share": "ADMIN$", "permissions": [], "remark": "Remote Admin"},
    {"share": "C$",     "permissions": [], "remark": "Default share"},
    {"share": "public", "permissions": ["READ","WRITE"], "remark": ""}
  ]
}

An empty list is an explicit fact. The model does not have to decide what the blank space meant, and the next tool call can take a share name from a field rather than from a substring.

Three details in that parser are worth pulling out, because they are the argument for writing a typed wrapper at all.

The shares table has no status marker

Which means the generic parser skips it entirely. It is read positionally instead, by anchoring on the header row to learn the column offsets and slicing every following line at those offsets. That is what correctly produces an empty permissions list for ADMIN$ instead of an absent key or a guess. Getting this wrong does not throw an error. It quietly reports that you have no access to a share you have access to, or the reverse.

Do not match on "Pwn3d!"

NetExec marks administrative access with a label that is configurable in nxc.conf. Plenty of people change it. So the server reads your actual nxc configuration and keys admin detection on the success marker plus the configured label, never on the literal string. A wrapper that hardcodes it works on your machine and silently reports "not admin" on someone else's.

The blank-LM hash

NetExec stores a pass-the-hash secret in its database as LM:NT, and for a modern account the LM half is a well-known constant. Replaying the full pair can fail against a domain controller that refuses LM, while the bare NT half succeeds. I watched exactly that: an NTDS dump returning STATUS_LOGON_FAILURE with a hash that was completely correct. The server now reduces a blank-LM pair to the NT half before it builds the command.

A model would have reported, accurately and uselessly, that the credential did not work. The wrapper is where that kind of hard-won operator knowledge gets to live, once, instead of being rediscovered by every operator and every agent.

Section 07 · problem 4

The chain is the product

Everything up to here is about making one call safe and legible. The reason to build any of it is the chain: an engagement is a graph where each access grants a credential that unlocks the next access, and the hard part has never been the individual commands. It is carrying state between them.

The gMSA chain is a good example, because it crosses protocols and no single command can do it.

Fig. 04 · One credential, two protocols (gMSA recovery, full mode)
AGENTEXTRACTsmbSECRETSRESOLVEldapTHE AGENTorchestrates the chain · carries the loot between toolsSMBsmb_lsagmsa_id + ntlmreadable, but opaque_SC_GMSA_ blobencrypted managed pwdmachine acct$aad3b4…:8846f7…dcc2 · kerberos keymore cached secretsLDAPldap_gmsa_convert_idgmsa_id → account name · reconldap_gmsa_decrypt_lsa_SC_GMSA_ blob → managed password · offensivesvc_gmsa$NT hash + managed password · usable nowid_SC_GMSA_ blobnamepassword
The MCP ships granular tools, not a gMSA macro; the agent runs the chain. smb_lsa dumps LSA secrets on a member server, so the gmsa_id and _SC_GMSA_ blob come back readable but opaque. Over LDAP, ldap_gmsa_convert_id turns the id into an account name and ldap_gmsa_decrypt_lsa turns the blob into the managed password. The recovered svc_gmsa$ hash is reused by pass-the-hash on any protocol: one credential, two protocols to recover it, replayable on any, zero hardcoded workflow.

Three mechanisms make that hand-off work, and each one exists because the naive version failed in testing.

Secrets come back as fields

Credential-dumping tools return typed entries rather than lines. The next call's argument is read from a key, not cut out of a terminal by a model that might drop a character. In a chain that is six hops deep, one truncated hash is the difference between a domain admin and a dead end.

The server refuses to run a doomed command

Call a tool with a named account and no secret, and nxc will attempt an empty-password bind that is guaranteed to fail for a real account. Rather than run it, the server first checks NetExec's own credential database. If a credential for that account is already stored, it returns it instead of executing, so the caller can retry with real authentication. That is a local database read, so it applies in every mode, including suggest.

Recall beats re-scanning

NetExec writes what it finds to a local SQLite workspace, and five tools read it back offline: no target is contacted, no credentials are needed, nothing executes. They answer questions stdout cannot: who is administrator where, who is logged in where, and what one account's reach looks like across SMB, LDAP, MSSQL, WinRM and SSH at once.

That last one is the shape of a lateral movement decision, and it is a relation, not a line of output. Re-touching a host to relearn something you already collected is slow, and on a monitored network it is loud. Every result carries a collection timestamp so the model can tell when it is looking at something stale and go back to the live tools.

Section 08 · limits

What it deliberately does not do

A tool like this is defined as much by its refusals as its features, so here they are stated rather than implied.

  • ▸It does not crack anything. Roasting returns hashes. Cracking them is a human step, off the agent's path, on purpose. That is a natural handoff point where a person looks at what was collected before the chain continues, and it is worth keeping even though it would be easy to automate.
  • ▸It cannot escalate itself. Scope and mode are read from the environment at launch. No tool raises them, no argument overrides them, and there is no negotiation. If the agent needs more reach, a human changes a variable and restarts the server, which is exactly the friction that decision deserves.
  • ▸It is not autonomy. Every guardrail here assumes a person chose the scope, chose the mode, and reads the audit log. The server makes an agent safe to point at a network you are authorised to test. It does not make an agent responsible for the engagement.
  • ▸It does not know when the model is wrong. A model can drive a chain it cannot judge. It will report a finding from an empty result if nothing stops it, and I have watched that happen on a lab that was switched off. Structured output and loud failures make it much harder. They do not make it impossible.
  • ▸It needs upkeep. The typed tools and parsers track a fast-moving CLI, so they lag when NetExec changes, and a parser can fail silently when the text output shifts under it. A differential audit against a live lab on every update is the counter, because a parser that has quietly stopped parsing is invisible until you look.
  • ▸Authorised testing only. Not a disclaimer in small type at the bottom. It is the reason the scope check is fail-closed and the reason the audit log exists at all. A server that could not prove what it did against whom would have no business existing.
Fig. 05 · The find → call loop (the full path a model takes through the meta-tools)
MODELDISCOVERDISPATCHGATEAUDITREGISTRYTHE MODELreads each result · drives the loopalso listed, off the loop:nxc_healthliveness · versionnxc_catalogorientation · protocol counts ·redirects a bad guessnxc_find_toolkeyword search ·ranked →suggested_callsignature not enough?nxc_describe_toolfull schema · every param ·on demandnxc_callmcp.call_toolGATEdecides · recon < loot < full · every argument validated · unchanged by dynamic modeAUDIT LOGrecords · one JSONL line per call: ts, tool, argv, tier, outcome ·even rejected calls · NXC_AUDIT_LOGSMB· 42 toolsLDAP· 24 toolsWINRM· 8 toolsMSSQL· 12 toolsSSH· 5 tools-M moduleslong-tail+ rdp · wmi · ftp · nfs · vnc · 10 protocols · ~100+ real tools,hidden from tools/list, reached only through nxc_callorient (optional)then searchor call a name you already saweach result → the next step
Two ways in: nxc_catalog orients (protocol counts, a nudge on a bad guess), or nxc_find_tool searches; a name from the catalog can go straight to nxc_call. The spine is find → call, with nxc_describe_tool pulled in only when the compact signature isn't enough. Every call clears the same gate, is written to the audit log, and flows back to drive the next turn. The full registry (~100+ tools) stays hidden from tools/list, reachable only here.
Section 09 · where it runs

Built for the models you can run yourself

One design constraint shaped more of this than any other: it had to work with a local model.

Not because a frontier model is not better at the job. It plainly is. But a lot of this work happens on air-gapped networks, under NDAs, on engagements where "just send the client's Active Directory structure to an API" ends the conversation. An MCP server that only works with a cloud model only works for some of the people who need it.

That constraint is where my previous post came from. Listing 121 tools to a model costs roughly 46,000 tokens before it reads a word of the task, which is more than the entire context window of the models this was built for. The default is therefore dynamic mode: the server advertises a handful of meta-tools, and the model searches for what it needs and dispatches to it on demand. The full surface is never removed, only delivered later. An 8B model can drive the result.

The other half of the story
You're Building Your MCP Wrong

The benchmark numbers, and the ways the measurement nearly lied to me.

Read that post

NetExec already knew how to enumerate a domain, dump a hive and replay a hash. None of that is what an MCP server adds.

What it adds is a shape the work can be handed over in: one intent per call, arguments that are typed instead of typed out, results that are facts instead of paragraphs, state that survives between steps, and a record of every one of them. And underneath all of it, three checkpoints that a model can ask past but cannot argue past.

An agent that can run any command is a liability. An agent that can run exactly the commands you authorised, against exactly the hosts you authorised, and hands you the log afterwards, is one you can answer for.