sentinel-prox 0.2.2

Stop prompt-injection attacks at the action layer — where the damage happens.

SENTINEL sits between your agent and your MCP tool servers, tracks which tool results each action could have been influenced by, and refuses the actions you guard when that lineage includes untrusted content — even when the attack slipped past your content filter. Read Known limitations before relying on it: the lineage is per MCP session, and only the tools you write rules for are guarded.

_{A poisoned page induces the agent to email a customer record to an attacker. The Layer-1 filter misses the obfuscated injection — the action is refused anyway, because its lineage includes untrusted tool output.}

pip install "sentinel-prox>=0.2.2"   # never 0.1.x: those releases are insecure
sentinel init             # write sentinel.yaml
sentinel check            # run serve's startup checks without serving; non-zero if serve would fail
sentinel scaffold > policy.yaml
sentinel serve            # your agent points at http://127.0.0.1:8765/mcp

Your agent needs no code changes: point its MCP endpoint at SENTINEL instead of directly at your tool servers. Interception is guaranteed by topology, not by asking the agent to cooperate.

Status and known limitations

Read this before deploying anything.

Known limitations

These are open, verified, and not yet fixed. Each one changes what SENTINEL protects you from.

SENTINEL_API_TOKEN must be set for any deployment reachable from a network. With neither it nor SENTINEL_ALLOW_ANONYMOUS=1 set, the service refuses to serve rather than serving openly.

The problem

AI agents don't just answer questions any more — they send email, query business systems, and read the open web. That makes indirect prompt injection an action problem, not a text problem: an attacker hides an instruction inside content the agent will read, and it executes with the agent's full privileges. "Summarize this pricing page" quietly becomes "email this customer's SSN to the attacker."

Content filters scan the words. Microsoft's own Prompt Shields documentation says it "may not catch all attack vectors" and recommends additional validation layers. The gap: security is applied to the words, while the damage is done by the actions.

SENTINEL closes it by judging an action on where its data came from, not on how the request was phrased.

What it protects against

Every decision becomes an immutable, replayable forensic record, exportable as SIEM-ready JSONL.

_{The same attack, run twice. Without SENTINEL the customer's SSN and API key reach the attacker's inbox; with it, the email is never sent.}

How it works

 your agent  ──MCP──▶  SENTINEL  ──MCP──▶  your MCP servers
                          │
       1. trace      label the origin of everything the agent has seen
       2. authorize  policy decides each call using that lineage (deny-overrides)
       3. contain    trust score + automatic quarantine
       4. record     immutable spans → replay + SOC export

Provenance is a set of trust labels (SYSTEM > USER > AGENT > RETRIEVED_CONTENT) unioned over an action's transitive derived_from ancestry, never the label of the most recent step. The proxy keeps that union incrementally as the session runs; a test checks it against a full walk of the provenance graph on random sessions. An action is tainted iff RETRIEVED_CONTENT is in that set.

Taint clears exactly one way: declassification, declared per tool in policy.

tools:
  read_price:
    declassify:
      schema: decimal_amount   # output crosses the boundary only if it validates
    rules: []

StructuredExtractor then validates that tool's output against the named schema. On a match the value starts fresh at SYSTEM trust with no inherited ancestry; on a mismatch it stays exactly as tainted as it was. Opt-in per tool, so a tool with no declassify block can never clear taint, and the schema registry is closed — policy names a reviewed schema or the policy fails to load. A cleared value cannot launder a tainted sibling, because recombination re-taints.

Policy compiles to a typed condition AST and is evaluated by tree-walk; there is no eval anywhere in the codebase. Rules are deny-only with deny-overrides, and unknown tools are default-denied.

Configuration

sentinel.yaml (created by sentinel init):

servers:                      # YOUR MCP servers — SENTINEL ships no tools
  - name: github
    url: https://mcp.example/gh
policy: ./policy.yaml         # your rules; generate with `sentinel scaffold`
host: 127.0.0.1
port: 8765
dashboard: false              # the bundled UI is a DEMO, opt-in only
catalogue_strict: true        # refuse catalogues containing injection markers

Seeing enforcement

Every decision is logged where you are actually looking — blocks at WARNING, allowed calls at INFO, each carrying the trace_id that ties the line back to the full forensic record:

23:16:40 INFO    ALLOW  get_customer_record  [trace 2ad33998e093]
23:16:40 INFO    ALLOW  web_fetch  [trace 2ad33998e093]
23:16:40 WARNING BLOCK  send_email  rule=block-untrusted-origin  [trace 2ad33998e093]

sentinel serve --log-format json emits one JSON object per line for an aggregator, and --log-level WARNING narrows it to refusals and quarantines.

Tool arguments are never logged. The payloads SENTINEL inspects are the very secrets it exists to protect, so writing them to a log would move the secret from a blocked call into a plaintext file that ships off-box — performing the exfiltration that was just prevented. The decision is logged; the data stays in the access-controlled forensic store. There is a test asserting the synthetic SSN and API key never appear in log output.

Precedence is CLI flag > environment variable > config file > default, so a container can override a checked-in file. Every key has an env equivalent (SENTINEL_MCP_SERVERS, SENTINEL_POLICY_FILE, …) — see .env.example.

Writing policy

Rules are deny-only: a call is allowed when no deny rule matches. sentinel scaffold emits every discovered tool explicitly denied, with its description and a recommended starting rule, so you edit rather than invent.

policy_version: 1
config:
  allowed_domains: ["corp.example"]
tools:
  send_email:
    rules:
      - id: block-untrusted-origin
        deny_if: "RETRIEVED_CONTENT in effective_provenance"
      - id: domain-allowlist
        deny_if: "recipient_domain not in allowed_domains"
  delete_record:
    rules:
      - id: never
        deny_always: true

Predicates support == != < >= in "not in", and/or/not, set literals ({USER}), true/false, tool arguments, and config values. There is no null, and a predicate may nest at most 64 levels; use a set for long lists of alternatives. Numbers must be finite, a numeric string compares as a number, and a boolean never equals a number. In a comparison the left side describes the call and the right side is what you allow: a variable on the right (allowed_domains, max_amount) is read from config only, never from the call's arguments. If you forget to declare it, the rule denies every call rather than letting the agent supply its own allowlist, and SENTINEL logs a warning naming the rule when the policy loads. The fields SENTINEL derives from a call (recipient_domain, recipient_domains, url_host) may appear on either side, so "evil.test" in recipient_domains works.

Deployment

Self-hosting is free and needs no cloud account:

python -c "import secrets; print('SENTINEL_API_TOKEN=' + secrets.token_urlsafe(32))" > .env
docker compose -f deploy/compose.yaml --env-file .env up -d --build

This keeps forensic history on a volume, refuses to start without the token, and listens on loopback only. deploy/DEPLOY.md covers the local demo, reaching SENTINEL from other machines (free options, and which ones we have tested), platforms that set PORT, and the optional, untested Azure template.

Put your tool servers on an internal network reachable only by SENTINEL — that topology is what makes interception unbypassable.

Authentication is required: with no credential configured SENTINEL refuses to serve. Set SENTINEL_API_TOKEN, or SENTINEL_API_TOKENS for per-tenant credentials, for your agents, and SENTINEL_ADMIN_TOKEN for the operator if you need to replace policies or clear quarantines through the API (see .env.example).

Resource limits

Every per-request and per-tenant resource is capped, so one caller cannot exhaust the service. The defaults sit well above normal use and only affect abuse.

GET /events returns at most 1000 events per call, with next_since to resume.

The rate limit is keyed by tenant for a valid credential and by client address for everything else, including invalid credentials and anonymous traffic. Inventing a new token for each request therefore does not buy a new budget. Behind a reverse proxy, the client address is the proxy's unless uvicorn trusts it: set FORWARDED_ALLOW_IPS to the proxy's address or CIDR. Do not set it to * on a host clients can reach directly, because uvicorn then takes the client-supplied X-Forwarded-For at face value. Until you configure it, all unauthenticated callers share one budget.

These counters live in process memory. Two replicas give a tenant twice the budget; enforce a global limit at the load balancer if you need one.

Forensic data

The default store is SQLite at ${SENTINEL_DATA_DIR:-./var}/sentinel.db.

• Retention. A trace is deleted, whole, once its newest span is older than SENTINEL_FORENSIC_RETENTION_DAYS (default 90; 0 keeps everything). The purge runs the first time runs are listed or started after startup, then at most once a day while runs are being started, so an idle service purges nothing. Runs in flight are never deleted. Set the window to what your audit obligations require.
• Ownership. Each run's tenant is recorded when it starts, so after a restart every tenant sees its own history and no one else's. History written by a version before that has no recorded owner; it is shown only to the operator (SENTINEL_ADMIN_TOKEN) rather than guessed at.
• Encryption at rest. SENTINEL does not encrypt the database. Tool arguments and results are redacted before they are written, but tool names, decisions and timings are stored in the clear. Put SENTINEL_DATA_DIR on an encrypted volume.
• Backup. A clean shutdown checkpoints the write-ahead log, so the .db file of a stopped service is complete on its own. While it runs, copy it with SQLite's online backup (sqlite3 sentinel.db ".backup copy.db"), not a file copy: the newest writes can still be in sentinel.db-wal.
• Cosmos DB. Retention there is the container's time-to-live (defaultTtl), set on the container; SENTINEL does not purge Cosmos itself.

Running at zero cost

Nothing in SENTINEL requires a paid service. Enforcement — provenance tracking and the authorization engine — runs locally and is identical everywhere. The paid integrations improve detection, labelling and telemetry; they are upgrades, not prerequisites, and GET /capabilities reports which backend each capability is actually running on.

The Layer-1 shield only flags; it never blocks. The authorization engine refuses a tainted action whether or not anything flagged the text that tainted it, so a simpler free detector does not weaken enforcement.

An Azure Container Apps blueprint is in deploy/. It is optional and has not been deployed or smoke-tested; see Status and known limitations.

Try the demo

A bundled demo shows the whole pipeline on a scripted attack — useful for seeing what a block looks like, but not the product surface:

sentinel serve --dashboard     # → http://localhost:8765

Hosted: https://sentinel-i63x.onrender.com (free tier — first load may take ~50 s to wake). It runs in anonymous demo mode with authentication disabled, so treat it as a public sandbox, not as an example of a secured deployment: everything in it is synthetic and anyone can drive it. A real deployment must set SENTINEL_API_TOKEN. A poisoned page induces the agent to email a synthetic customer record to an attacker; the Layer-1 filter misses the obfuscated variant and authorization blocks it anyway. The taint comes from the page: the bundled policy marks the records service's output as trusted (trusted_output), so the record lookup alone taints nothing, and without the page the agent never attempts the email. The attacker's domain is also outside the bundled allowlist, a second, independent reason for the same refusal; the tests show that an email to an allowed address is refused after the page and allowed without it. All demo data is synthetic — the record is a labelled fake (SSN 000-00-0000, a non-functional sk-synthetic-DO-NOT-USE key) and send_email writes to an in-memory sink. Nothing is ever sent.

With a real model

The default agent is a real LLM whenever a credential is present — set OPENAI_API_KEY, or AZURE_OPENAI_ENDPOINT + AZURE_OPENAI_DEPLOYMENT. With no credential it falls back to a deterministic scripted transcript so CI stays key-free. For a free local model, point OPENAI_BASE_URL at any OpenAI-compatible endpoint:

ollama serve && ollama pull llama3.2
export OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_MODEL=llama3.2

What SENTINEL does not protect against

Stating the boundary precisely is what separates a security product from a demo.

• Provenance is tracked at message / tool-result granularity, not token-level inside model reasoning. Taint spreads conservatively unless a sanitizer clears it.
• It secures the action layer, not the model's cognition. It does not stop a model being persuaded — it stops the resulting unauthorized action.
• The proxy and the policy store are trusted components.
• One trace is handled by one proxy instance; horizontal scaling is across traces.
• Conservative tainting is intentional. The escape hatch is declassification, declared per tool in policy, and it is deliberately narrow: syntactic schema validation only. Taint saturation is the correct bias for action-layer security, so clearing it must be something an operator opts into for a specific tool and a specific shape of value.
• Sanitization is syntactic, not semantic. A schema-valid {"price": 999999} is well-formed but still subject to argument-level rules such as an amount cap.

Development

python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]" -c versions.lock   # Windows: .venv\Scripts\python.exe
.venv/bin/python -m pytest        # every test must pass
.venv/bin/python -m ruff check src tests
.venv/bin/python -m mypy src      # strict

Install -c versions.lock so local matches CI and the container — a floating dependency is how a production deploy once broke. Requires Python 3.11+.

See CONTRIBUTING.md for the security invariants a change must preserve, and CHANGELOG.md for release notes. Design notes live in docs/: the scoping analysis for proxying arbitrary MCP servers, and the competitive/threat-landscape research behind the roadmap.

License & credits

MIT — see LICENSE.

Built on the Model Context Protocol Python SDK, FastAPI, Starlette, sse-starlette, Uvicorn, Pydantic, PyYAML, httpx, pytest, ruff, mypy, gitleaks, and the Azure SDKs for Python. Thank you to their maintainers.

AI tools used in development: Claude Code (Anthropic) and GitHub Copilot. SENTINEL also integrates Azure OpenAI (attack classification) and Azure AI Content Safety / Prompt Shields (Layer-1 screening) as optional components.

Originally built for the Microsoft Build AI Hackathon 2026 — Security in the Agentic Future — by Pali Krishna Harshith.