veilgate 0.1.2

A local-first zero-trust Model Context Protocol (MCP) privacy firewall & context-diet gateway.

Description

Veilgate is an enterprise-grade, local-first proxy and security gateway that sits transparently between AI client hosts (Claude Desktop, Cursor, Antigravity, LangGraph) and upstream Model Context Protocol (MCP) tool servers.

As agentic AI workflows adopt dozens of autonomous MCP tools, developers face critical security and efficiency risks:

1. Unchecked Data Exfiltration: Upstream tools can leak corporate databases, PII, and financial accounts directly into public LLM context windows.
2. Confused Deputy Attacks: Tainted prompt data can trick LLMs into re-routing sensitive secrets into unmonitored external network sinks (email, webhooks, cURL).
3. Rug-Pull Tool Mutation: Malicious or compromised servers can stealthily alter tool schemas and descriptions after initial approval.
4. Context Window Token Bloat: Unbounded tool definitions consume 40–70% of prompt token limits before reasoning even begins.

Veilgate eliminates these risks with a zero-trust, fail-closed security architecture:

• Lossless Context Diet: Dynamically prunes bloated schemas and applies BM25 adaptive ranking to keep prompts lean and fast.
• Cryptographic Data Minimization: Intercepts sensitive PII/secrets, stores them locally in an AES-256-GCM vault, and injects format-preserving synthetic tokens (<vg:TYPE:ID>) into LLM prompts.
• Taint-Aware Egress Enforcement: Tracks data origin and halts unauthorized token re-hydration into external sinks.
• Interactive Human-in-the-Loop (HITL) Review: Prompts developers via terminal or the sleek web dashboard with ⚡ Allow Once, 🛡️ Allow Always, or ✕ Deny.
• Tamper-Evident SHA-256 Audit Trail: Cryptographically hash-chains every discovery, call, token transformation, and approval in a local SQLite WAL ledger.

System Architecture

flowchart TD
    subgraph ClientHost["AI Client Host (Claude Desktop / Cursor / CLI)"]
        LLM["AI Agent / LLM Engine"]
    end

    subgraph VeilgateGateway["Veilgate Zero-Trust Privacy Firewall"]
        Proxy["FastMCP MITM Proxy Router"]
        
        subgraph Pipeline["Firewall Security Pipeline"]
            RugPull["1. Rug-Pull & Fingerprint Guard"]
            Diet["2. Lossless Context-Diet & BM25 Ranker"]
            ACL["3. Zero-Trust ACL & Egress Inspector"]
            HITL["4. Interactive HITL Review Queue"]
            Taint["5. Taint Tracker & Vault Minimizer"]
        end

        Vault[("Local AES-GCM Vault & Stash")]
        Audit[("Tamper-Evident Audit Ledger (SHA-256)")]
        Policy[("policy.yaml & policy.learned.yaml")]
    end

    subgraph UpstreamMCP["Upstream MCP Ecosystem"]
        ServerA["Database MCP (invoicedb)"]
        ServerB["Egress MCP (mailer / web)"]
        ServerC["Filesystem / CLI Tools"]
    end

    LLM <-->|"MCP stdio / SSE"| Proxy
    Proxy --> Pipeline
    Pipeline --> Vault
    Pipeline --> Audit
    Pipeline --> Policy
    HITL <-->|"WebSocket / REST API"| Dashboard["Local Web Dashboard (Port 8765)"]
    Pipeline <-->|"Safe Filtered Calls"| UpstreamMCP

Repository Layout

Prerequisites

Installing uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Installation

Install Veilgate directly from PyPI:

# Standard installation
pip install veilgate

# With web observability dashboard extras
pip install "veilgate[dashboard]"

# Or run directly via uv without installing:
uvx veilgate --help

Project Setup (Contributing / Development)

Clone the repository and synchronize dependencies into an isolated virtual environment:

# Clone repository
git clone https://github.com/OmH3/Veilgate.git
cd veilgate

# Install with development and dashboard extras
uv sync --extra dev --extra dashboard

# Alternatively with standard pip
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev,dashboard]"

Generate your master cryptographic key:

uv run veilgate keygen

Quickstart & CLI Commands

1. Initialize a New Policy

Generate a baseline policy.yaml pre-configured with recommended security rules and PII detectors:

uv run veilgate init

2. Adopt Existing MCP Configurations

Instantly migrate existing Claude Desktop, Cursor, or Cline MCP configs into Veilgate:

uv run veilgate adopt --client claude-desktop

3. Run the Veilgate Firewall Proxy

Start the proxy gateway in foreground mode:

uv run veilgate run --config policy.yaml

4. Launch the Live Observability Dashboard

Start the local review and monitoring dashboard:

uv run veilgate dashboard --config policy.yaml --port 8765

Open http://localhost:8765 in your browser.

Interactive Human-in-the-Loop (HITL) Approvals

Veilgate treats egress and unallowed tools with zero trust. Whenever an agent attempts to invoke a tool that lacks pre-approved authorization or touches external networks, execution is automatically paused and queued for developer review:

Decision Matrix

Live Web Dashboard & Observability

The local-first dashboard (http://localhost:8765) gives developers complete visibility into agentic operations:

1. Minimization Metrics:
   • Total Intercepted Calls: Lifetime count of all MCP tool executions.
   • Blocked Exfiltrations: Real-time count of blocked unauthorized calls or taint policy violations.
   • Tokens Minted: Number of sensitive values safely anonymized into <vg:TYPE:ID>.
   • Pending Approvals: Real-time count of calls awaiting human review.
2. Interactive Review Queue:
   • Visual cards detailing the tool name, session ID, reason code, and sanitized argument preview.
   • Action buttons with real-time feedback.
3. Tamper-Evident Audit Stream:
   • Live stream of all gateway events chronologically ordered.
   • Cryptographic SHA-256 hashes linking each row to its predecessor (prev_hash).

Audit Verification & Security

Veilgate maintains an append-only, tamper-evident cryptographic ledger:

# Verify integrity of all audit events
uv run veilgate audit verify

# Export audit trail to JSONL for SIEM ingestion
uv run veilgate audit export --output audit_export.jsonl

# Inspect details of a specific tool
uv run veilgate explain mailer.send_email

Running Tests

Veilgate maintains exhaustive test coverage across unit contracts and real-world attack vectors:

# Run all unit tests
uv run pytest tests/unit -q

# Run security attack suite (A1-A16 catalog)
uv run pytest tests/security -q

# Run test suite with coverage report
uv run pytest --cov=src/veilgate --cov-report=term-missing

Publishing to PyPI

Veilgate uses standard modern PyPA packaging powered by hatchling and twine:

# 1. Clean previous build artifacts
rm -rf dist build *.egg-info

# 2. Build sdist and wheel
uv run python -m build

# 3. Validate packages
uv run twine check dist/*

# 4. Upload to TestPyPI (optional verification)
uv run twine upload --repository testpypi dist/*

# 5. Upload to official PyPI
uv run twine upload dist/*

Resources & Support

• Documentation: https://github.com/OmH3/Veilgate
• Model Context Protocol Specification: https://modelcontextprotocol.io
• Issues & Bug Reports: https://github.com/OmH3/Veilgate/issues
• Discussions & Community: Discord Community

License

Veilgate is open-source software licensed under the MIT License.