Skip to main content
Glama
Procmon MCP

Procmon MCP

by cobaltcub

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.

{
  "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>"
      }
    }
  }
}
{
  "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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors