Sub-ms deterministic parsing vs. LLM-based policy for agent safety?

Disclaimer

MiSeGuard is an independent personal project created by Midhun Sekhar. It is not affiliated with, endorsed by, or representative of any current, past, or future employer. All development was conducted entirely on personal equipment, during personal time, and without the use of proprietary resources or confidential information.

A deterministic safety layer for autonomous coding agents.

Runtime circuit breaker and stdio proxy that intercepts MCP tool calls before they reach your OS.

AI coding agents can modify your machine. MiSeGuard puts a deterministic security boundary between the agent and your tools.

What is MCP? The Model Context Protocol (MCP) is an open standard that lets autonomous AI agents (such as Cursor, Claude Code, Antigravity, OpenCode, Windsurf) invoke external tools (bash, filesystem, git, terminal) over stdio JSON-RPC 2.0. MiSeGuard sits as a transparent, sub-millisecond proxy between your agent and those tool runtimes to inspect, score, and block destructive operations before they reach the real operating system.

What Does "Deterministic" Mean? The same command or file mutation with the same configuration always produces the exact identical risk score. No LLM in the loop, no non-deterministic inference, no prompt drift.

npm install -g miseguard

npx miseguard --help

npm install --save-dev miseguard

Requirements: Node.js 18.0 or later.

miseguard init

Choose the method that matches your workflow:

• Starting fresh or configuring an agent GUI? Usesnippet to generate copy-pasteable JSON:

miseguard snippet --tool filesystem --path .

• Already have an existing MCP configuration file? Usewrap-config <file-path> to automatically rewrite and back up your config in place:

miseguard wrap-config .antigravity/mcp.json
miseguard wrap-config "%APPDATA%\Claude\claude_desktop_config.json"

miseguard wrap-config
miseguard check "rm -rf /"     # 🛑 Exit Code 1: Blocked
miseguard check "git status"    # 🟢 Exit Code 0: Safe

MiSeGuard computes a multi-factor Blast-Radius Risk Score (0–100) for every tool invocation.

📌 CLI Exit Code Stability Contract:

0: Safe operation (Green) or permitted in permissive mode. 1: Dangerous operation blocked by circuit breaker (Red). 2: Caution operation triggering dry-run in strict mode (Yellow). 3: Internal parsing or configuration error. Exit codes are stable and guaranteed across versions for CI/CD and pre-commit hook integration.

Generate a starter configuration file in your project:

miseguard init
{
  "$schema": "https://raw.githubusercontent.com/midhunweb/miseguard/main/schema.json",
  "mode": "strict",
  "thresholds": {
    "block": 70,
    "dryRun": 30
  },
  "allowlist": [
    "echo *",
    "git log*",
    "git status*",
    "git diff*",
    "npm run test*",
    "npm run lint*",
    "npm run clean:*"
  ],
  "protectedPaths": [
    ".env*",
    "*.pem",
    "*.key",
    "id_rsa*",
    "id_ed25519*",
    "~/.ssh/*",
    "~/.aws/*",
    "~/.kube/*",
    ".git/*",
    "secrets/**"
  ]
}

• mode :
  • "strict" (default): Yellow tier actions trigger ephemeral sandbox dry-run simulation; Red tier actions are blocked.
  • "permissive" : Yellow tier actions log warnings and allow execution; Red tier actions are still blocked.
• allowlist : Commands or file targets matching these patterns are unconditionally grantedGreen (Score 0) status.
• protectedPaths : Glob patterns of sensitive files that immediately elevate risk toRed (Score >= 70) upon access or mutation attempt.
• thresholds : Customize risk boundaries for block anddryRun .

Safely transforms tools in an existing MCP configuration file so commands run shielded behind miseguard proxy --. Supports explicit file paths or workspace auto-discovery:

miseguard wrap-config .antigravity/mcp.json
miseguard wrap-config "%APPDATA%\Claude\claude_desktop_config.json"
miseguard wrap-config ~/.config/Claude/claude_desktop_config.json

miseguard wrap-config

Creates <file-path>.bak before modification and guarantees idempotency.

Generates copy-pasteable JSON configuration blocks for agent GUI settings (Cursor, Claude, Antigravity, Windsurf):

miseguard snippet --tool filesystem --path ./

miseguard snippet --tool git --path ./

miseguard snippet --tool bash

miseguard snippet --tool custom --name my-server --cmd python --args -m my_module

Evaluates the blast-radius risk score of any shell command:

miseguard check "rm -rf /"

Simulates a command inside an isolated ephemeral shadow sandbox and outputs a SHA-256 filesystem delta table:

miseguard dry-run "npm run build"

Runs MiSeGuard as an active stdio proxy in front of an MCP server process:

miseguard proxy -- npx -y @modelcontextprotocol/server-filesystem ./

Displays the complete deterministic security rule matrix.

MiSeGuard adds negligible overhead. The numbers below measure policy evaluation and interception logic — the scoring, sandbox dispatch, and diff-checking path. They exclude process spawn, JSON serialization, and OS scheduling, which are common to all stdio proxies and not attributable to MiSeGuard.

Reproducibility: Full methodology, hardware specs, warm-up procedure, and percentile distributions are in docs/BENCHMARKS.md. Run npm run benchmark to reproduce on your own machine.

MiSeGuard operates at the Model Context Protocol (MCP) stdio layer. It intercepts every tools/call JSON-RPC message that flows between an agent and an MCP tool server (bash, filesystem, git, etc.).

Being explicit about architectural boundaries:

• Does not protect against prompt injection — That is an LLM inference layer concern. MiSeGuard assumes the agent's intent may be compromised or hallucinatory, and deterministically enforces policy on theexecuted action , not the reasoning.

• Does not intercept native IDE built-in tools — Cursor's internalrun_command , Antigravity's internaledit_file , and Windsurf's native terminal bypass MCP entirely. MiSeGuard only inspects MCP stdio traffic. Direct IDE extension hooks are planned for v0.3.0.

• Does not sandbox long-running persistent VM state — Ephemeral shadow sandboxes for dry-runs are discarded immediately after filesystem diff analysis.

• Does not support HTTP/gRPC transports yet — Standard input/output (stdio ) JSON-RPC 2.0 only for v0.1.0 (HTTP/SSE transport on roadmap for v0.2.0).

• Does not use ML or probabilistic heuristics for risk scoring — By design. Determinism and reproducibility are core security features.

• Does not defend against kernel-level escapes or raw syscall bypasses — Operates at the tool runtime protocol layer.

• v0.2.0 : HTTP / SSE / gRPC MCP transport support

• v0.3.0 : IDE Extension / LSP wrapper for Cursor, Antigravity, and Windsurf native tools

• Architecture & Design Specification →

• Latency Benchmark Details →

• Agent Frontend Integration Guide (Cursor, Claude Desktop, Antigravity) →

npm test

npm run benchmark

MIT License. Copyright (c) 2026 Midhun Sekhar & MiSeGuard Contributors.