Skip to main content
Glama
Procmon MCP

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

[![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-0078D6)](#requirements)
[![node](https://img.shields.io/badge/node-%3E%3D22-339933)](#requirements)
[![license](https://img.shields.io/badge/license-MIT-blue)](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.