How insjunaid/promptshield works
PromptShield is a local MCP security gateway: it mediates agent calls to tool servers, checking outbound actions and inspecting inbound tool results before returning them. The main runtime path runs through the gateway, content pipeline, and policy engine; canaries, taint, and registry checks add containment beyond detection. The API supports dashboard operations such as live threats, replay, and approvals. The lab and evaluation code exercise and measure attacks, but are separate from the serving path. Relationships for unsampled routes and guards are included only where the README or source index supports them.
Main entry points: core.py Gateway Logic · run.py Lab Runner · pipeline.py Content Pipeline · engine.py Policy Decisions
Components 23
MCP Gateway
- MCP Transport
promptshield/gateway/server.py - Gateway Logic
promptshield/gateway/core.py - API Service
promptshield/api/server.py - Shared App State
promptshield/api/state.py
Content Inspection
- Content Pipeline
promptshield/pipeline.py - Detection Layers
promptshield/layers - Canary Checks
promptshield/layers/canary.py
Policy and Controls
- Policy Decisions
promptshield/policy/engine.py - Policy Schema
promptshield/policy/schema.py - Action Guard
promptshield/layers/l4_action_guard.py - Registry Guard
promptshield/registry_guard.py - Shared Schemas
promptshield/models.py - Secret Redaction
promptshield/redact.py
Operations UI
- Event Bus
promptshield/events.py - SQLite Store
promptshield/storage/db.py - Security Dashboard
dashboard/src/App.tsx - API Client
dashboard/src/api/client.ts
Attack Lab
- Lab Runner
lab/run.py - Lab Agent
lab/agent/victim.py - Attack Site
lab/attack_site/build.py - Attacker Sink
lab/attacker_sink/server.py
Other components
- AI Agent
- MCP Tool Servers
Connections 28
- AI Agent → MCP Transport: MCP requests
README.md - MCP Transport → Gateway Logic: dispatches calls
promptshield/gateway/server.py - Gateway Logic → MCP Tool Servers: forwards allowed calls
README.md - MCP Tool Servers → Gateway Logic: returns results
README.md - Gateway Logic → Content Pipeline: scans results
promptshield/gateway/core.py - Content Pipeline → Detection Layers: runs layers
promptshield/pipeline.py - Content Pipeline → Policy Decisions: provides findings
promptshield/policy/engine.py - Policy Decisions → Gateway Logic: returns verdict
promptshield/policy/engine.py - Gateway Logic → Action Guard: checks tool calls
README.md - Gateway Logic → Registry Guard: guards tool definitions
README.md - Detection Layers → Canary Checks: includes checks
promptshield/layers/defaults.py - Action Guard → Canary Checks: checks canary leaks
README.md - Policy Decisions → Policy Schema: uses policy rules
promptshield/policy/engine.py - Gateway Logic → Shared App State: uses shared services
promptshield/api/state.py - API Service → Shared App State: builds runtime state
promptshield/api/server.py - Gateway Logic → Event Bus: publishes verdicts
promptshield/gateway/core.py - Event Bus → SQLite Store: persists events
promptshield/events.py - SQLite Store → Secret Redaction: scrubs stored data
promptshield/storage/db.py - API Service → API Client: serves dashboard API
promptshield/api/server.py - Security Dashboard → API Client: requests data
dashboard/src/App.tsx - Event Bus → Security Dashboard: streams live events
README.md - Security Dashboard → API Service: manages approvals and policy
README.md - Lab Runner → Lab Agent: runs attack scenarios
lab/run.py - Lab Runner → Gateway Logic: exercises shielded runs
lab/run.py - Lab Runner → Attack Site: builds attack content
lab/run.py - Lab Agent → Attacker Sink: may exfiltrate data
README.md - Gateway Logic → Shared Schemas: validates boundary data
promptshield/gateway/core.py - Canary Checks → Secret Redaction: registers secrets
promptshield/layers/canary.py