Procmon MCP
by cobaltcub
README.md
# Procmon MCP
**Give an AI agent scriptable access to Process Monitor on Windows — without giving the agent admin rights.**
[](#requirements)
[](#requirements)
[](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.
```text
┌──────────────────────────┐ 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](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](https://nodejs.org/) 22 or newer (tested on 24).
- [Sysinternals Process Monitor](https://learn.microsoft.com/sysinternals/downloads/procmon).
- 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
```powershell
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.
<details>
<summary>Generic <code>mcpServers</code> config (Claude Desktop, VS Code, ...)</summary>
```json
{
"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>"
}
}
}
}
```
</details>
<details>
<summary>opencode config</summary>
```json
{
"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>"
}
}
}
}
```
</details>
Verify the wiring by asking the agent to call `procmon_status`. A healthy
response looks like:
```json
{ "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:
```text
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:
```text
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](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/`](presets/). They were
generated with [`scripts/New-Presets.py`](scripts/New-Presets.py)
(`pip install procmon-parser`) and round-trip validated; the SHA-256 hashes are
in [`presets/manifest.json`](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](docs/security.md).
To report a vulnerability, open a private security advisory on GitHub rather
than a public issue.
## Development
```powershell
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:
```text
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](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](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.