🛡️ SIGIL Inspector

The official developer toolkit for inspecting, intercepting, and auditing SIGIL-secured MCP (Model Context Protocol) traffic.

Part of the SIGIL Protocol — the sovereign identity and security layer for AI agents.

---

What is the SIGIL Inspector?

The SIGIL Inspector is a local web UI — inspired by the MCP Inspector — that lets you visually audit the security envelope attached to every AI agent tool call in real time.

When an AI agent calls a tool (e.g., read_vault_file, execute_shell), a SIGIL-aware gateway wraps the JSON-RPC message with a _sigil object containing a cryptographic identity and a policy verdict (Allowed / Blocked / Scanned). The SIGIL Inspector makes this transparent.

AI Agent ──────► MCP Tool Server
         ▲
         │
   [_sigil envelope]
   {
     identity: "did:sigil:parent_01",
     policy_verdict: "allowed",
     signature: "sig_abc123..."
   }

---

Quick Start

The fastest way to start the Inspector:

npx @sigil-protocol/inspector

Then open your browser at http://localhost:5173

---

Installation

Install globally to run from anywhere:

npm install -g @sigil-protocol/inspector
sigil-inspector

Or as a project dev dependency:

npm install --save-dev @sigil-protocol/inspector

---

Usage

Running the Inspector

# With a custom port
PORT=3000 npx @sigil-protocol/inspector

# Default (port 5173)
npx @sigil-protocol/inspector

Connecting to an MCP Server

Once the Inspector is open in your browser:

1. Set the Transport Type — stdio for local processes, SSE for remote servers.
2. Enter the Command to launch your MCP server (e.g., npx).
3. Enter the Arguments (e.g., @modelcontextprotocol/server-everything).
4. Click Connect & Inspect.

---

The _sigil Security Envelope

SIGIL extends the standard MCP JSON-RPC protocol by injecting a _sigil object into the params of every request. Here is what a SIGIL-secured tool call looks like:

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "read_vault_file",
    "arguments": {
      "path": "/vault/budget_2025.xlsx"
    },
    "_sigil": {
      "identity": "did:sigil:parent_01",
      "policy_verdict": "allowed",
      "timestamp": "2026-02-21T17:54:44.123Z",
      "nonce": "a3f82c1d9b7e04f5a3b2c1d0e9f8a7b6",
      "signature": "base64url-ed25519-signature"
    }
  }
}

Policy Verdicts

Verdict	Icon	Description
allowed	🛡️ Green	The policy engine verified the identity and permitted this action.
blocked	🚫 Red	The action was denied. The reason field explains why.
scanned	👁️ Blue	The action is allowed but the payload was automatically scanned (e.g., for PII).

---

Blocked Request Example

When a child agent attempts a destructive command, SIGIL blocks it and includes a reason:

{
  "jsonrpc": "2.0",
  "id": 99,
  "method": "tools/call",
  "params": {
    "name": "execute_shell",
    "arguments": { "cmd": "rm -rf /" },
    "_sigil": {
      "identity": "did:sigil:child_02",
      "policy_verdict": "blocked",
      "timestamp": "2026-02-21T10:45:12.000Z",
      "nonce": "3b9ac2e1f8d070a4c5b6e7f8a9b0c1d2",
      "signature": "base64url-ed25519-signature",
      "reason": "Role 'child_02' lacks permission for destructive system tools."
    }
  }
}

The Inspector will display this with a red shield icon and a highlighted policy banner when you expand the row.

---

Integrating with a Real Backend

For development use, the Inspector ships with a built-in mock stream generator that simulates live MCP traffic so you can explore the UI immediately.

To connect it to a real SIGIL-powered MCP gateway, the Inspector's useInspectorCore hook is designed as a drop-in integration point. Extend it to consume messages from any of these sources:

Option A: Standard I/O (stdio)

Wire your MCP server's stdout directly into the Inspector's hook. The parser (src/utils/parser.ts) accepts a raw JSON string and returns a ParsedIntercept:

import { parseInterceptedMessage } from '@sigil-protocol/inspector/src/utils/parser';

const intercept = parseInterceptedMessage(rawJsonString);
// Returns a ParsedIntercept with { action, description, sigil, rawPayload }

Option B: WebSockets / SSE

If your gateway exposes an event stream (e.g., http://localhost:9000/events):

1. Select SSE in the Transport Type dropdown in the UI.
2. Enter your SSE endpoint URL and click Connect & Inspect.

Option C: Embedding into an Agent-Centric OS

The SIGIL Inspector is designed to be embedded directly into agent-centric operating systems such as the MyMolt Project, an agent-centric OS for families. The React components are portable and can be imported directly:

import { AuditLogPane } from '@sigil-protocol/inspector';
import { useInspectorCore } from '@sigil-protocol/inspector';

---

TypeScript API Reference

ParsedIntercept

The normalized data structure produced by the parser for every intercepted message.

interface ParsedIntercept {
  id: string;             // Unique UUID for React rendering
  action: string;         // MCP method (e.g., "tools/call", "resources/read")
  description: string;    // Human-readable summary
  sigil: SigilEnvelope | null; // Extracted security envelope, or null if absent
  rawPayload: string;     // The full original JSON-RPC string
}

SigilEnvelope

The SIGIL security extension object found in params._sigil:

interface SigilEnvelope {
  identity: string;          // DID of the caller (e.g., "did:sigil:parent_01")
  policy_verdict: 'allowed' | 'blocked' | 'scanned';
  timestamp: string;         // ISO 8601, millisecond precision
  nonce?: string;            // 16-byte random hex — replay prevention
  signature?: string;        // Ed25519, base64url-encoded (absent in dev mode)
  reason?: string;           // Present when verdict is blocked or scanned
}

parseInterceptedMessage(rawJson: string): ParsedIntercept | null

Safely parses a raw JSON-RPC string and extracts the SIGIL envelope. Returns null if the input is not valid JSON-RPC 2.0.

---

Architecture

sigil-inspector/
├── bin/
│   └── cli.js               # Node.js CLI entrypoint — launches Express server
├── dist/                    # Compiled production React UI (Vite output)
├── src/
│   ├── components/
│   │   ├── Header.tsx        # Status bar + SIGIL branding
│   │   ├── ConnectionPane.tsx # Server configuration sidebar
│   │   └── AuditLogPane.tsx  # Main log stream + expandable JSON viewer
│   ├── hooks/
│   │   └── useInspectorCore.ts  # State management for the message stream
│   ├── types/
│   │   └── mcp.ts            # TypeScript interfaces for MCP + SIGIL envelope
│   └── utils/
│       └── parser.ts         # Core JSON-RPC parsing + _sigil extraction logic
├── .npmignore
├── LICENSE                   # EUPL-1.2
├── package.json
└── README.md

---

Design System

The SIGIL Inspector uses the bespoke Versa UI glassmorphism design system with the SIGIL corporate identity:

• Theme: Light mode by default, automatically switches to dark mode via prefers-color-scheme.
• Accent Color: SIGIL Lavender #9370DB
• Fonts: Inter (UI text) + Fira Code (monospace/code blocks)
• Glass Panels: backdrop-filter: blur(16px) with semi-transparent borders

---

Security

The SIGIL Inspector was audited prior to publication. Key findings:

• XSS: All raw JSON payloads are rendered via standard React string bindings — no dangerouslySetInnerHTML is used.
• Path Traversal: express.static() in bin/cli.js sandboxes all file access to dist/ only.
• Dependency Vulnerabilities: Linting dev dependencies (eslint) include a minimatch ReDoS issue (GHSA-3ppc-4f35-3m26) that does not ship with the published package.

---

Contributing

This project is licensed under EUPL-1.2. Contributions must be made under the same licence. Please open an issue or pull request on GitHub.

---

License

SIGIL Inspector is dual-licensed:

• Open Source (EUPL-1.2): Free for open-source projects and personal use. See LICENSE.
• Commercial: Required for proprietary or closed-source applications. See LICENSE-COMMERCIAL or contact info@sigil-protocol.org.

Note: Using SIGIL Inspector as a dev dependency in a proprietary project does NOT automatically require a commercial licence, provided you do not modify and redistribute SIGIL Inspector itself in closed-source form.