Give an AI agent scriptable access to Process Monitor on Windows — without giving the agent admin rights.
Status: v0.1.0. The 11-test unit suite is green, and the full loop — live capture → CSV export → query — has been exercised with
scripts/E2E-Capture.ps1against Procmon 4.01. The three presets were load-tested separately (seepresets/manifest.json).
Procmon is one of the most useful tools in Windows security research, but it is
painful to drive from an agent: the kernel driver needs elevation, and every MCP
server inherits the integrity level of the client that spawns it. A normal
(Medium-integrity) agent can launch Procmon64.exe, but the driver load fails.
Procmon MCP splits the problem in two:
- a small daemon that you start elevated once per boot and that owns Procmon;
- a stdio MCP server that runs at normal integrity and only forwards validated requests to the daemon over loopback, authenticated with a bearer token.
The agent gets start → exercise target → stop → export CSV → query → rank candidates. You get exactly one UAC prompt per boot, no admin shell for the
agent, and no custom service or driver.
┌──────────────────────────┐ HTTP 127.0.0.1 + bearer token
│ MCP client (Medium) │ ┌──────────────────────────────┐
│ └─ procmon-mcp (stdio) │ ─────► │ procmon-daemon (High) │
└──────────────────────────┘ │ └─ Procmon64.exe (High) │
│ └─ .pml / .csv on disk │
└──────────────────────────────┘
You can, but then every tool the agent can reach — shell, browser, HTTP fetch — also runs elevated. That is a large blast radius for a convenience feature. Keeping the MCP shim unprivileged means a prompt-injected or buggy agent can only call the daemon endpoints, with a fixed binary, a fixed flag allowlist, basename-only file arguments, and a per-boot bearer token. See docs/security.md for the threat model.
- One UAC prompt per boot. Manual
.batlauncher or an opt-in logon task. - No UAC bypass. The daemon refuses to start at Medium integrity.
- Loopback only. Binds
127.0.0.1; no LAN exposure, no CORS, no auth-off mode. - Token auth. 256-bit token, timing-safe comparison, user-only token file ACL.
- Fixed binary + flag allowlist.
spawn(argv), never a shell string. - Path jail. Every file argument is a bare basename validated against a strict regex, then resolved inside the capture directory.
- Streaming CSV query. Case-insensitive filters, paging up to 5000 rows, never loads a whole capture into memory.
- Heuristic analysis. Ranks missing DLL/EXE loads, denied writes, and persistence/system paths into a copy-pasteable candidate list.
- Reproducible presets. Three
.pmcfilters generated by script, with a SHA-256 manifest. - Disk guard. Refuses to start under 512 MB free and stops a capture that
exceeds
PROCMON_MAX_BACKING_MB(default 2048).
- Windows 10 or 11, an admin account, UAC enabled.
- Node.js 22 or newer (tested on 24).
- Sysinternals Process Monitor.
- An MCP client that supports local stdio servers (opencode, Claude Desktop, VS Code, and others).
Procmon is not on PATH by default. The daemon probes the usual install
locations; if yours is elsewhere, set PROCMON_BIN to the full path of
Procmon64.exe.
git clone https://github.com/cobaltcub/ProcmonMCP.git
cd ProcmonMCP
npm ci
npm run build
npm run check # build + lint + format + 11 unit tests
# Creates %APPDATA%\procmon-mcp\token with a user-only ACL and prints it once.
powershell -ExecutionPolicy Bypass -File scripts\New-Token.ps1Start the daemon:
- Right-click
scripts\Start-Daemon-Elevated.bat→ Run as administrator. - Approve the single UAC prompt.
- The console should print:
procmon-daemon listening 127.0.0.1:37771 integrity=High ...
Then point your MCP client at packages/mcp/dist/index.js. The shim needs only
the port and the token; the daemon holds all capture settings.
Generic mcpServers config (Claude Desktop, VS Code, ...)
{
"mcpServers": {
"procmon": {
"command": "node",
"args": ["C:/tools/ProcmonMCP/packages/mcp/dist/index.js"],
"env": {
"PROCMON_DAEMON_PORT": "37771",
"PROCMON_DAEMON_TOKEN": "<token printed by New-Token.ps1>"
}
}
}
}opencode config
{
"mcp": {
"procmon": {
"type": "local",
"command": ["node", "C:/tools/ProcmonMCP/packages/mcp/dist/index.js"],
"environment": {
"PROCMON_DAEMON_PORT": "37771",
"PROCMON_DAEMON_TOKEN": "<token printed by New-Token.ps1>"
}
}
}
}Verify the wiring by asking the agent to call procmon_status. A healthy
response looks like:
{ "ok": true, "data": { "state": "idle", "activePreset": "hijack-privesc",
"procmonProcess": false, "backingBytes": 0, "maxBackingMb": 2048 } }If you get DAEMON_UNREACHABLE, the elevated daemon is not running — start the
.bat again. Do not retry in a loop and do not ask the agent to elevate itself.
All eight tools return the same envelope: { ok: true, data } or
{ ok: false, error: { code, message, hint? } }.
| Tool | What it does |
|---|---|
procmon_status |
Reports idle / capturing / stopped, the active preset, backing size, and whether a Procmon process is alive. Call this first. |
procmon_start |
Starts a capture with a preset and a bare backingName. Requires idle. Archives a previous .pml instead of deleting it. |
procmon_stop |
Sends /Terminate and waits up to 15 s. Requires capturing. |
procmon_save |
Exports the stopped capture as csv, xml, or pml-copy. CSV/XML above 200 MB returns EXPORT_TOO_LARGE. |
procmon_query |
Streams a saved .csv with process / pathContains / operation / result filters and limit + offset paging. |
procmon_analyze |
Ranks hijack and privilege-escalation candidates with process, path, count, reasons, and score. |
procmon_set_filter |
Sets the preset used by the next start when preset is omitted. |
procmon_cleanup |
Deletes old captures, keeping the N newest. Dry-run by default. |
The daemon enforces a small state machine, so the tool descriptions stay short and the agent cannot save a live capture by accident:
idle --start--> capturing --stop--> stopped --start--> capturing
procmon_statusprocmon_start { preset, backingName }- Exercise the target (launch the app / installer) — this is the agent's own shell, not a Procmon tool. Nothing is captured until the target runs.
procmon_stopprocmon_save { format: "csv", name }procmon_analyze { file: "<name>.csv" }, thenprocmon_queryto drill in.
A real session looks like this:
procmon_start { preset: "installer", backingName: "acme-setup" }
<run acme-setup.exe>
procmon_stop
procmon_save { format: "csv", name: "acme-setup" }
procmon_analyze { file: "acme-setup.csv", top: 20 }
→ vulnapp.exe C:\Program Files\Acme\helper.dll 2× missing-binary, system-path
procmon_query { file: "acme-setup.csv", pathContains: "helper.dll" }
analyze returns leads, not findings. A missing DLL is only a
vulnerability if a low-privileged user can actually write to that directory;
verify the ACL before reporting it.
More detail: docs/usage.md.
| Preset | Filter | Use it for |
|---|---|---|
hijack-privesc |
NOT FOUND, DENIED, .dll, .exe |
Default: unknown binary, DLL hijack, priv-esc triage. |
installer |
msiexec / setup, CreateFile, WriteFile |
Installer and update flows. |
dll-planting |
Load Image, NOT FOUND, .dll |
Phantom DLL loads. |
none |
unfiltered | Small captures or pipeline debugging. Large and slow. |
Presets are ordinary Procmon .pmc files in presets/. They were
generated with scripts/New-Presets.py
(pip install procmon-parser) and round-trip validated; the SHA-256 hashes are
in presets/manifest.json. The daemon loads only
local files from that directory — there is no preset upload endpoint.
By default the filter is non-destructive: filtered events stay in the .pml,
so query and analyze still see everything. Set dropFiltered: true on
procmon_start if you would rather trade offline detail for a smaller file.
| Control | Implementation |
|---|---|
| No LAN exposure | server.listen(port, '127.0.0.1'); no host override. |
| Authentication | 256-bit bearer token, timingSafeEqual; 401 without it. |
| Least privilege | MCP shim at Medium; only the daemon runs High. |
| No arbitrary commands | Operator-set PROCMON_BIN; flags checked against an allowlist; spawn with an argv array. |
| No path traversal | Basename regex + resolved path must stay under the capture directory. |
| No schema drift | zod on both the MCP boundary and every daemon endpoint. |
| No evidence loss | New captures archive the old .pml; cleanup is dry-run first and never touches the active capture. |
| No UAC bypass | The daemon exits with NOT_ELEVATED at Medium integrity. |
Full threat model, residual risks, and the hardening checklist: docs/security.md.
To report a vulnerability, open a private security advisory on GitHub rather than a public issue.
npm run build # tsc project references
npm run check # build + eslint + prettier + 11 unit tests
npm run test:unit # 11 tests, no admin, no Procmon required
npm run test:integration # E2E against an already-running elevated daemonLayout:
packages/shared/ zod schemas, error envelope (no node:*, no Procmon)
packages/daemon/ High integrity: Procmon lifecycle, HTTP server, CSV store
packages/mcp/ Medium integrity: stdio MCP server, daemon client
presets/ .pmc filters + SHA-256 manifest
scripts/ launcher, token, scheduled task, E2E, preset generator
tests/ unit tests + anonymized fixture capture
docs/ architecture, security, usage, troubleshooting
Adding a tool means: schema in packages/shared/src/schemas.ts, handler in
packages/daemon/src/server.ts, description in packages/mcp/src/tools.ts,
and a unit test. See docs/architecture.md.
- v0.1.0, single capture at a time. This is deliberate, not a missing lock.
queryandanalyzeread CSV only; there is no live.pmltail.- One daemon per user session; no multi-user service mode.
- Presets produced with
procmon-parsermay need regeneration after a major Procmon change. GUI export remains a fallback (seepresets/README.md). - Planned: XML query support and a structured finding report.
- CI runs
npm run checkon Windows for every push and pull request.
MIT — see LICENSE.
Procmon is a Microsoft/Sysinternals tool and is not bundled here. Use this project only on systems you own or have explicit permission to test.