{
"markdown": "\n\n# 🛡️ Prompt_Sentinel\n\n### A trusted action boundary for coding agents\n\nPrompt_Sentinel keeps **policy, approval, capability tickets, MCP admission, and audit decisions** in trusted host-side code — where the model can propose actions, but the runtime decides what is authorized.\n\n
\n\n\n\n\n\n\n\n\n
\n\n> **The rule:** a model-generated tool call is a proposal, not an authorization.\n\n
\n\n---\n\n## Contents\n\n- [Why it exists](#why-it-exists)\n- [How it works](#how-it-works)\n- [Product shape](#product-shape)\n- [Architecture](#architecture)\n- [Install](#install)\n- [Fast start](#fast-start)\n- [CLI surface](#cli-surface)\n- [MCP poisoning hardening](#mcp-poisoning-hardening)\n- [Policy packs](#policy-packs)\n- [Runtime guarantees](#runtime-guarantees)\n- [Hooks and adapters](#hooks-and-adapters)\n- [Repository map](#repository-map)\n- [Schemas](#schemas)\n- [Development](#development)\n- [Current security posture](#current-security-posture)\n\n---\n\n## Why it exists\n\nCoding agents now act across files, shells, browsers, plugins, and MCP servers. That creates a boundary problem:\n\n> **Untrusted text can shape trusted actions.**\n\nA repository file, tool response, retrieved web page, MCP descriptor, or user message can all contain instructions. Prompt_Sentinel treats those inputs as **untrusted influence**, not authority.\n\nInstead of asking an LLM to protect itself, Prompt_Sentinel separates the system into explicit trust zones.\n\n```mermaid\nflowchart LR\n A[Untrusted text
user input · repo files · tool output · MCP metadata] --> B[Model proposes
a tool call]\n B --> C{Prompt_Sentinel
trusted runtime}\n C -->|Allowed| D[Trusted execution]\n C -->|Needs approval| E[Signed capability ticket]\n C -->|Denied| F[Explicit denial]\n D --> G[(Hash-chained audit log)]\n E --> G\n F --> G\n```\n\nPrompt_Sentinel separates:\n\n| Boundary | What lives there | Trust level |\n|---|---|---:|\n| **Input surface** | User text, repo text, retrievals, tool output, MCP descriptors | Untrusted |\n| **Model layer** | Tool-call proposals, reasoning, suggested actions | Proposal only |\n| **Runtime layer** | Policy checks, capability verification, MCP pinning, quotas | Trusted |\n| **Execution layer** | Shell, files, browser, plugins, MCP calls | Authorized only |\n| **Audit layer** | Tool decisions, denials, approvals, exports | Evidence trail |\n\n---\n\n## How it works\n\nPrompt_Sentinel acts as a policy engine between the agent and the tools it wants to use.\n\n```mermaid\nsequenceDiagram\n participant U as User / Repo / Tool Output\n participant M as Coding Agent\n participant P as Prompt_Sentinel Runtime\n participant H as Host Executor\n participant A as Audit Chain\n\n U->>M: Untrusted instructions or context\n M->>P: Proposed tool call + params\n P->>P: Validate policy, scope, quotas, MCP metadata\n alt Allowed\n P->>H: Authorize execution\n H->>A: Record decision + result metadata\n else Needs capability\n P->>M: Require signed ticket\n M->>P: Present capability ticket\n P->>P: Verify audience, expiry, nonce, scope, params\n P->>H: Authorize execution\n H->>A: Record approval path\n else Denied\n P->>A: Record denial\n P->>M: Return explicit denial\n end\n```\n\nThe model can still reason, plan, and propose. It just cannot silently convert a proposal into an action.\n\n---\n\n## Product shape\n\nPrompt_Sentinel is organized around three layers.\n\n| Layer | Role | Included here |\n|---|---|---:|\n| **Core** | Local runtime, CLI, sealed policy handling, signed capability flow, local audit chain, Codex and Claude adapters | ✅ Implemented |\n| **Guard Add-On** | Managed policy packs, approval workflows, improved denial UX, hosted audit search, team presets | 🧩 Scaffolding |\n| **Enterprise** | Central policy distribution, approval services, SSO/RBAC, SIEM export, KMS/HSM integration, long-retention compliance reporting | 🧩 Scaffolding |\n\nThis repository implements the **Core runtime** directly and includes Guard and Enterprise scaffolding under `AGENT_CORE/`.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TB\n subgraph Agent_Host[Agent host]\n CA[Claude adapter]\n CX[Codex adapter]\n MCP[MCP client metadata]\n end\n\n subgraph Core[Prompt_Sentinel Core]\n PE[Policy engine]\n CV[Capability verifier]\n MA[MCP admission verifier]\n RQ[Runtime quotas]\n AO[Audit output]\n end\n\n subgraph Trusted_State[Trusted state outside model context]\n SP[Sealed policy]\n PK[Public keys]\n MP[MCP manifests + schema hashes]\n AL[(Audit chain)]\n end\n\n subgraph Tools[Authorized execution targets]\n SH[Shell / Bash]\n FS[Files]\n BR[Browser]\n PL[Plugins]\n MT[MCP tools]\n end\n\n CA --> PE\n CX --> PE\n MCP --> MA\n SP --> PE\n PK --> CV\n MP --> MA\n PE --> CV\n PE --> RQ\n PE --> AO\n CV --> AO\n MA --> AO\n AO --> AL\n PE -->|allow / deny / require capability| Tools\n```\n\n### Decision lifecycle\n\n```mermaid\nflowchart LR\n P[Proposal] --> S[Schema + parameter check]\n S --> Q[Quota + path controls]\n Q --> M[MCP server/tool pin check]\n M --> C{Capability required?}\n C -->|No| X[Authorize]\n C -->|Yes| V[Verify signed ticket]\n V --> X\n C -->|Invalid / absent| D[Deny]\n X --> A[Audit]\n D --> A\n```\n\n---\n\n## Install\n\nFrom the repository root:\n\n```bash\npip install -e .\n```\n\nThat installs the `prompt-sentinel` CLI while sourcing the runtime package from:\n\n```text\nAGENT_CORE/prompt-sentinel-claude/prompt-sentinel-core/src\n```\n\n---\n\n## Fast start\n\nValidate a policy:\n\n```bash\nprompt-sentinel policy validate --policy policy.json\n```\n\nSummarize a policy:\n\n```bash\nprompt-sentinel policy summary --policy policy.json\n```\n\nCheck a proposed tool call:\n\n```bash\nprompt-sentinel check-proposal --policy policy.json --proposal proposal.json\n```\n\nCheck and execute through the trusted path:\n\n```bash\nprompt-sentinel check-proposal --policy policy.json --proposal proposal.json --execute\n```\n\nInspect the audit trail:\n\n```bash\nprompt-sentinel audit tail --audit-log prompt_sentinel.audit.jsonl --limit 10\n```\n\n---\n\n## CLI surface\n\n### Core policy and proposal checks\n\n```bash\nprompt-sentinel check-proposal --policy policy.json --proposal proposal.json\nprompt-sentinel check-proposal --policy policy.json --proposal proposal.json --execute\nprompt-sentinel policy validate --policy policy.json\nprompt-sentinel policy summary --policy policy.json\n```\n\n### Signed capability flow\n\nIssue a capability ticket:\n\n```bash\nprompt-sentinel issue-capability \\\n --authority policy_engine \\\n --audience local.prompt-sentinel \\\n --operation approve_tool_call \\\n --session-id sess-1 \\\n --scope scope.json \\\n --params params.json \\\n --private-key keys/dev.key\n```\n\nVerify a capability ticket:\n\n```bash\nprompt-sentinel verify-capability \\\n --capability ticket.json \\\n --public-key keys/dev.key.pub \\\n --params params.json \\\n --session-id sess-1 \\\n --operation approve_tool_call \\\n --scope scope.json\n```\n\n### Audit inspection and export\n\n```bash\nprompt-sentinel audit tail --audit-log prompt_sentinel.audit.jsonl --limit 10\nprompt-sentinel audit export --audit-log prompt_sentinel.audit.jsonl --destination stdout\n```\n\nBackward-compatible aliases still exist for:\n\n```text\npolicy-summary\npolicy-validate\naudit-tail\naudit-export\n```\n\n---\n\n## MCP poisoning hardening\n\nPrompt_Sentinel includes an MCP admission and pinning layer. It treats MCP server metadata, tool descriptors, tool schemas, tool arguments, and tool output as untrusted until the trusted runtime verifies them.\n\n### Threat coverage\n\n| MCP risk | Prompt_Sentinel control |\n|---|---|\n| Poisoned tool descriptions or schemas | Descriptor review + schema hash pinning |\n| Server rug-pulls after approval | Manifest verification before enablement |\n| Unapproved tools appearing in `tools/list` | Policy-pinned server/tool admission |\n| Unsafe STDIO server launches | Command allowlist + shell/metacharacter denial |\n| Cross-server data laundering | Explicit `mcp_data_flows.allowed` edges |\n| Tool output triggering follow-up secret reads | Output risk scanning + audit/review path |\n| Capability confusion | Expected operation, scope, params, and session checks |\n\n### MCP admission workflow\n\n```mermaid\nflowchart TB\n T[Capture MCP tools/list JSON] --> B[Build admission manifest]\n B --> R[Review descriptor risks]\n R --> H[Pin schema hashes]\n H --> P[Add server, transport, tools to policy]\n P --> V[Verify manifest against policy]\n V --> E[Enable server in agent host]\n E --> C[Runtime MCP proposal checks]\n```\n\nBuild a manifest for a streamable HTTP MCP server:\n\n```bash\nprompt-sentinel mcp build-manifest \\\n --tools finance.tools.json \\\n --server-id finance \\\n --publisher example \\\n --transport streamable-http \\\n --server-url https://finance.example/mcp \\\n --output finance.manifest.json\n```\n\nVerify the manifest:\n\n```bash\nprompt-sentinel mcp verify-manifest \\\n --manifest finance.manifest.json \\\n --policy policy.json\n```\n\nFor STDIO MCP servers, the manifest and policy can include the launch command:\n\n```bash\nprompt-sentinel mcp build-manifest \\\n --tools local.tools.json \\\n --server-id local-search \\\n --transport stdio \\\n --command python \\\n --arg -m \\\n --arg local_search_server \\\n --output local-search.manifest.json\n```\n\nSTDIO launch policy denies shell usage, unsafe metacharacters, and commands that are not allowlisted.\n\n---\n\n## MCP policy fields\n\nMCP policy is expressed alongside normal tool permissions.\n\n```json\n{\n \"tool_permissions\": {\n \"Bash\": {\n \"allowed_params\": [\"command\", \"cmd\", \"input\", \"stdin\", \"description\"],\n \"max_calls_per_session\": 25\n }\n },\n \"mcp_transport\": {\n \"stdio\": {\n \"allowed_commands\": [\"python\", \"python3\", \"node\", \"npx\", \"uvx\"]\n }\n },\n \"mcp_servers\": {\n \"finance\": {\n \"enabled\": true,\n \"transport\": \"streamable-http\",\n \"url\": \"https://finance.example/mcp\",\n \"publisher\": \"example\",\n \"trust_tier\": \"trusted\",\n \"tools\": {\n \"lookup_invoice\": {\n \"schema_hash\": \"REPLACE_WITH_MANIFEST_SCHEMA_HASH\",\n \"allowed_params\": [\"invoice_id\"],\n \"max_calls_per_session\": 5\n }\n }\n },\n \"enrichment\": {\n \"enabled\": true,\n \"transport\": \"streamable-http\",\n \"url\": \"https://enrich.example/mcp\",\n \"publisher\": \"third-party\",\n \"trust_tier\": \"third-party\",\n \"tools\": {\n \"lookup_invoice\": {\n \"schema_hash\": \"REPLACE_WITH_MANIFEST_SCHEMA_HASH\",\n \"allowed_params\": [\"invoice_id\"]\n }\n }\n }\n },\n \"mcp_data_flows\": {\n \"allowed\": [\n {\"from\": \"finance\", \"to\": \"enrichment\"}\n ],\n \"blocked\": []\n }\n}\n```\n\nBy default, data from one MCP server cannot be passed into a third-party or untrusted MCP server unless `mcp_data_flows.allowed` explicitly permits that edge.\n\n---\n\n## Runtime MCP calls\n\nHost adapters should name MCP tools with one of the supported forms:\n\n```text\nmcp____\nmcp::\n```\n\nMCP proposals should include metadata when available:\n\n```json\n{\n \"tool\": \"mcp__finance__lookup_invoice\",\n \"params\": {\n \"invoice_id\": \"INV-1\"\n },\n \"metadata\": {\n \"schema_hash\": \"REPLACE_WITH_MANIFEST_SCHEMA_HASH\",\n \"input_origins\": []\n }\n}\n```\n\n`input_origins` is used for cross-server data-flow checks. Tool output is also scanned for prompt-like follow-up instructions and sensitive payload patterns so poisoned responses can be audited and reviewed.\n\n---\n\n## Policy packs\n\nThe packaged runtime ships with starter policy packs.\n\n| Pack | Path | Use |\n|---|---|---|\n| Core default | `AGENT_CORE/prompt-sentinel-claude/prompt-sentinel-core/src/prompt_sentinel/policies/default-policy.json` | Local default runtime policy |\n| Guard team | `AGENT_CORE/prompt-sentinel-claude/prompt-sentinel-core/src/prompt_sentinel/policies/guard-team-policy.json` | Team-oriented presets |\n| Enterprise default | `AGENT_CORE/prompt-sentinel-claude/prompt-sentinel-core/src/prompt_sentinel/policies/enterprise-default-policy.json` | Enterprise control-plane baseline |\n\nThese policies cover:\n\n- Tool allowlists and parameter allowlists\n- Path controls and quotas\n- Sensitive action classes\n- Approval scopes and operations\n- MCP transport rules, server pins, and data-flow rules\n- Audit retention classes\n- Inheritance hooks for managed policy layering\n\n---\n\n## Runtime guarantees\n\nPrompt_Sentinel's strongest guarantees are host-enforced.\n\n| Guarantee | Why it matters |\n|---|---|\n| **Sealed policy stays outside model context** | The model cannot rewrite the rules that govern its tools. |\n| **Signed capability tickets bind approval context** | Approvals are tied to session, audience, expiry, nonce, operation, scope, and exact parameters. |\n| **Every tool decision is audit-chained** | Allows review of allowed, denied, and capability-mediated actions. |\n| **MCP servers and tools require admission** | Tools are enabled only after manifest and policy checks. |\n| **Policy denials are explicit** | Unsafe actions are not silently worked around. |\n\n---\n\n## Hooks and adapters\n\nClaude and Codex adapters call the shared runtime helpers instead of duplicating authorization logic.\n\nThe Claude hook matcher covers standard local tools and MCP tool names:\n\n```text\nBash|Edit|Write|mcp__.*|mcp:.*\n```\n\nHooks evaluate proposals with `execute=false`, which lets the host deny unsafe MCP/tool proposals without executing them locally. Trusted execution remains a separate runtime step.\n\n---\n\n## Repository map\n\n| Path | Purpose |\n|---|---|\n| `AGENT_CORE/prompt-sentinel-claude/prompt-sentinel-core/` | Authoritative installable runtime and CLI used by the root package |\n| `AGENT_CORE/prompt-sentinel-codex/` | Codex plugin and skill distribution layer |\n| `AGENT_CORE/prompt-sentinel-control-plane/` | Enterprise control-plane skeleton and schemas |\n| `AGENT_CORE/prompt-sentinel-core/` | Standalone runtime copy kept in sync for packaging/distribution work |\n| `V1_Prompt_Sentinel/prompt-sentinel-core/` | V1 package copy kept in sync for compatibility |\n| `V3_LLM_Boundary_Crypto_end_to_end.py` | Original end-to-end prototype kept as a runnable reference |\n| `deployment_guide.md` | Framework integration examples for LangChain, LlamaIndex, and FastAPI |\n\n---\n\n## Schemas\n\nInstallable schemas ship with the runtime package:\n\n- Policy bundle schema\n- Capability ticket schema\n- Audit export record schema\n\nSee:\n\n```text\nAGENT_CORE/prompt-sentinel-claude/prompt-sentinel-core/src/prompt_sentinel/schemas/\n```\n\nEnterprise-facing schemas remain under:\n\n```text\nAGENT_CORE/prompt-sentinel-control-plane/schemas/\n```\n\n---\n\n## Development\n\nRun focused tests from the repository root:\n\n```bash\npython -m pytest AGENT_CORE/prompt-sentinel-claude/prompt-sentinel-core/tests -q\npython -m pytest AGENT_CORE/prompt-sentinel-core/tests -q\npython -m pytest V1_Prompt_Sentinel/prompt-sentinel-core/tests -q\n```\n\nThe original V3 demo remains useful for concept validation:\n\n```bash\npython V3_LLM_Boundary_Crypto_end_to_end.py\n```\n\n---\n\n## Current security posture\n\nThe project is partially hardened against MCP poisoning in the places this repository controls.\n\n### Hardened now\n\n- MCP admission manifests pin full tool descriptors by hash.\n- Policy verifies approved servers, transports, tools, and schema hashes.\n- STDIO launch rules reject shell-style command execution.\n- Runtime checks enforce MCP parameter allowlists and call quotas.\n- Cross-server data flows are explicit.\n- Tool output risk is audited.\n\n### Host integration still required\n\nRemaining hardening depends on the agent host. The host must:\n\n- Capture `tools/list` from MCP servers.\n- Run manifest verification before enabling servers.\n- Pass schema hash metadata on MCP calls.\n- Preserve Prompt_Sentinel outside model-controlled state.\n- Route execution through the trusted runtime instead of letting model output execute directly.\n\n---\n\n\n\n### Prompt_Sentinel turns agent autonomy into governed execution.\n\n**The model proposes. The runtime authorizes. The audit trail remembers.**\n\n
\n",
"bytes": 16616,
"sha": "d7726cda57d4e234918732d49f064b9b24dbdf5fdac60766e3bebaff87d95a1c",
"repo_slug": "reneemgagnon/prompt_sentinel",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_reneemgagnon_prompt_sentinel_prompt_sent_ca5879ae/readme"
}