Skip to content

About

Split-privilege Procmon MCP server for Windows: one UAC prompt per boot, then AI agents can safely capture, query, and triage Process Monitor data without admin rights.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Procmon MCP

Give an AI agent scriptable access to Process Monitor on Windows — without giving the agent admin rights.

platform node license

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.ps1 against Procmon 4.01. The three presets were load-tested separately (see presets/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      │
                                    └──────────────────────────────┘

Why not just run everything as admin?

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.

Features

  • One UAC prompt per boot. Manual .bat launcher 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 .pmc filters 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).

Requirements

  • 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.

Quick start

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.ps1

Start the daemon:

  1. Right-click scripts\Start-Daemon-Elevated.bat → Run as administrator.
  2. Approve the single UAC prompt.
  3. 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.

Tools

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 agent workflow

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
  1. procmon_status
  2. procmon_start { preset, backingName }
  3. 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.
  4. procmon_stop
  5. procmon_save { format: "csv", name }
  6. procmon_analyze { file: "<name>.csv" }, then procmon_query to 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.

Presets

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.

Security model

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.

Development

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 daemon

Layout:

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.

Limitations and roadmap

  • v0.1.0, single capture at a time. This is deliberate, not a missing lock.
  • query and analyze read CSV only; there is no live .pml tail.
  • One daemon per user session; no multi-user service mode.
  • Presets produced with procmon-parser may need regeneration after a major Procmon change. GUI export remains a fallback (see presets/README.md).
  • Planned: XML query support and a structured finding report.
  • CI runs npm run check on Windows for every push and pull request.

License

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.

About

Split-privilege Procmon MCP server for Windows: one UAC prompt per boot, then AI agents can safely capture, query, and triage Process Monitor data without admin rights.

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages