# insjunaid/promptshield architecture

> Architecture diagram of the GitHub repository insjunaid/promptshield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/insjunaid/promptshield
- Repository: https://github.com/insjunaid/promptshield

## Overview

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: [`promptshield/gateway/core.py`](https://github.com/insjunaid/promptshield/blob/main/promptshield/gateway/core.py) (Gateway Logic), [`lab/run.py`](https://github.com/insjunaid/promptshield/blob/main/lab/run.py) (Lab Runner), [`promptshield/pipeline.py`](https://github.com/insjunaid/promptshield/blob/main/promptshield/pipeline.py) (Content Pipeline), [`promptshield/policy/engine.py`](https://github.com/insjunaid/promptshield/blob/main/promptshield/policy/engine.py) (Policy Decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["MCP Gateway"]
  node_gateway_transport["MCP Transport<br/>[server.py]"]
  node_gateway_core["Gateway Logic<br/>[core.py]"]
  node_api["API Service<br/>[server.py]"]
  node_app_state["Shared App State<br/>[state.py]"]
end

subgraph group_inspection["Content Inspection"]
  node_pipeline["Content Pipeline<br/>[pipeline.py]"]
  node_layers["Detection Layers"]
  node_canaries["Canary Checks<br/>[canary.py]"]
end

subgraph group_controls["Policy and Controls"]
  node_policy["Policy Decisions<br/>[engine.py]"]
  node_policy_schema["Policy Schema<br/>[schema.py]"]
  node_action_guard["Action Guard<br/>[l4_action_guard.py]"]
  node_registry_guard["Registry Guard<br/>[registry_guard.py]"]
  node_models["Shared Schemas<br/>[models.py]"]
  node_redactor["Secret Redaction<br/>[redact.py]"]
end

subgraph group_operations["Operations UI"]
  node_events["Event Bus<br/>[events.py]"]
  node_database[("SQLite Store<br/>[db.py]")]
  node_dashboard["Security Dashboard<br/>[App.tsx]"]
  node_dashboard_api["API Client<br/>[client.ts]"]
end

subgraph group_lab["Attack Lab"]
  node_lab_runner["Lab Runner<br/>[run.py]"]
  node_lab_agent["Lab Agent<br/>[victim.py]"]
  node_attack_site["Attack Site<br/>[build.py]"]
  node_attacker_sink["Attacker Sink<br/>[server.py]"]
end

node_agent(("AI Agent"))
node_tool_servers["MCP Tool Servers"]

node_agent -->|"MCP requests"| node_gateway_transport
node_gateway_transport -->|"dispatches calls"| node_gateway_core
node_gateway_core -->|"forwards allowed calls"| node_tool_servers
node_tool_servers -->|"returns results"| node_gateway_core
node_gateway_core -->|"scans results"| node_pipeline
node_pipeline -->|"runs layers"| node_layers
node_pipeline -->|"provides findings"| node_policy
node_policy -->|"returns verdict"| node_gateway_core
node_gateway_core -->|"checks tool calls"| node_action_guard
node_gateway_core -->|"guards tool definitions"| node_registry_guard
node_layers -->|"includes checks"| node_canaries
node_action_guard -->|"checks canary leaks"| node_canaries
node_policy -->|"uses policy rules"| node_policy_schema
node_gateway_core -->|"uses shared services"| node_app_state
node_api -->|"builds runtime state"| node_app_state
node_gateway_core -->|"publishes verdicts"| node_events
node_events -->|"persists events"| node_database
node_database -->|"scrubs stored data"| node_redactor
node_api -->|"serves dashboard API"| node_dashboard_api
node_dashboard -->|"requests data"| node_dashboard_api
node_events -->|"streams live events"| node_dashboard
node_dashboard -->|"manages approvals and policy"| node_api
node_lab_runner -->|"runs attack scenarios"| node_lab_agent
node_lab_runner -->|"exercises shielded runs"| node_gateway_core
node_lab_runner -->|"builds attack content"| node_attack_site
node_lab_agent -.->|"may exfiltrate data"| node_attacker_sink
node_gateway_core -->|"validates boundary data"| node_models
node_canaries -->|"registers secrets"| node_redactor

click node_gateway_transport "https://github.com/insjunaid/promptshield/blob/main/promptshield/gateway/server.py"
click node_gateway_core "https://github.com/insjunaid/promptshield/blob/main/promptshield/gateway/core.py"
click node_api "https://github.com/insjunaid/promptshield/blob/main/promptshield/api/server.py"
click node_app_state "https://github.com/insjunaid/promptshield/blob/main/promptshield/api/state.py"
click node_pipeline "https://github.com/insjunaid/promptshield/blob/main/promptshield/pipeline.py"
click node_layers "https://github.com/insjunaid/promptshield/tree/main/promptshield/layers"
click node_canaries "https://github.com/insjunaid/promptshield/blob/main/promptshield/layers/canary.py"
click node_policy "https://github.com/insjunaid/promptshield/blob/main/promptshield/policy/engine.py"
click node_policy_schema "https://github.com/insjunaid/promptshield/blob/main/promptshield/policy/schema.py"
click node_action_guard "https://github.com/insjunaid/promptshield/blob/main/promptshield/layers/l4_action_guard.py"
click node_registry_guard "https://github.com/insjunaid/promptshield/blob/main/promptshield/registry_guard.py"
click node_models "https://github.com/insjunaid/promptshield/blob/main/promptshield/models.py"
click node_redactor "https://github.com/insjunaid/promptshield/blob/main/promptshield/redact.py"
click node_events "https://github.com/insjunaid/promptshield/blob/main/promptshield/events.py"
click node_database "https://github.com/insjunaid/promptshield/blob/main/promptshield/storage/db.py"
click node_dashboard "https://github.com/insjunaid/promptshield/blob/main/dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/insjunaid/promptshield/blob/main/dashboard/src/api/client.ts"
click node_lab_runner "https://github.com/insjunaid/promptshield/blob/main/lab/run.py"
click node_lab_agent "https://github.com/insjunaid/promptshield/blob/main/lab/agent/victim.py"
click node_attack_site "https://github.com/insjunaid/promptshield/blob/main/lab/attack_site/build.py"
click node_attacker_sink "https://github.com/insjunaid/promptshield/blob/main/lab/attacker_sink/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway_transport,node_gateway_core,node_api,node_app_state toneBlue
class node_pipeline,node_layers,node_canaries toneAmber
class node_policy,node_policy_schema,node_action_guard,node_registry_guard,node_models,node_redactor,node_tool_servers toneMint
class node_events,node_database,node_dashboard,node_dashboard_api toneRose
class node_lab_runner,node_lab_agent,node_attack_site,node_attacker_sink,node_agent toneIndigo
```

## Components

### MCP Gateway

- [MCP Transport](https://github.com/insjunaid/promptshield/blob/main/promptshield/gateway/server.py): `promptshield/gateway/server.py`
- [Gateway Logic](https://github.com/insjunaid/promptshield/blob/main/promptshield/gateway/core.py): `promptshield/gateway/core.py`
- [API Service](https://github.com/insjunaid/promptshield/blob/main/promptshield/api/server.py): `promptshield/api/server.py`
- [Shared App State](https://github.com/insjunaid/promptshield/blob/main/promptshield/api/state.py): `promptshield/api/state.py`

### Content Inspection

- [Content Pipeline](https://github.com/insjunaid/promptshield/blob/main/promptshield/pipeline.py): `promptshield/pipeline.py`
- [Detection Layers](https://github.com/insjunaid/promptshield/tree/main/promptshield/layers): `promptshield/layers`
- [Canary Checks](https://github.com/insjunaid/promptshield/blob/main/promptshield/layers/canary.py): `promptshield/layers/canary.py`

### Policy and Controls

- [Policy Decisions](https://github.com/insjunaid/promptshield/blob/main/promptshield/policy/engine.py): `promptshield/policy/engine.py`
- [Policy Schema](https://github.com/insjunaid/promptshield/blob/main/promptshield/policy/schema.py): `promptshield/policy/schema.py`
- [Action Guard](https://github.com/insjunaid/promptshield/blob/main/promptshield/layers/l4_action_guard.py): `promptshield/layers/l4_action_guard.py`
- [Registry Guard](https://github.com/insjunaid/promptshield/blob/main/promptshield/registry_guard.py): `promptshield/registry_guard.py`
- [Shared Schemas](https://github.com/insjunaid/promptshield/blob/main/promptshield/models.py): `promptshield/models.py`
- [Secret Redaction](https://github.com/insjunaid/promptshield/blob/main/promptshield/redact.py): `promptshield/redact.py`

### Operations UI

- [Event Bus](https://github.com/insjunaid/promptshield/blob/main/promptshield/events.py): `promptshield/events.py`
- [SQLite Store](https://github.com/insjunaid/promptshield/blob/main/promptshield/storage/db.py): `promptshield/storage/db.py`
- [Security Dashboard](https://github.com/insjunaid/promptshield/blob/main/dashboard/src/App.tsx): `dashboard/src/App.tsx`
- [API Client](https://github.com/insjunaid/promptshield/blob/main/dashboard/src/api/client.ts): `dashboard/src/api/client.ts`

### Attack Lab

- [Lab Runner](https://github.com/insjunaid/promptshield/blob/main/lab/run.py): `lab/run.py`
- [Lab Agent](https://github.com/insjunaid/promptshield/blob/main/lab/agent/victim.py): `lab/agent/victim.py`
- [Attack Site](https://github.com/insjunaid/promptshield/blob/main/lab/attack_site/build.py): `lab/attack_site/build.py`
- [Attacker Sink](https://github.com/insjunaid/promptshield/blob/main/lab/attacker_sink/server.py): `lab/attacker_sink/server.py`

### Other components

- **AI Agent**
- **MCP Tool Servers**

## Connections

- AI Agent → MCP Transport: MCP requests (evidence: `README.md`)
- MCP Transport → Gateway Logic: dispatches calls (evidence: `promptshield/gateway/server.py`)
- Gateway Logic → MCP Tool Servers: forwards allowed calls (evidence: `README.md`)
- MCP Tool Servers → Gateway Logic: returns results (evidence: `README.md`)
- Gateway Logic → Content Pipeline: scans results (evidence: `promptshield/gateway/core.py`)
- Content Pipeline → Detection Layers: runs layers (evidence: `promptshield/pipeline.py`)
- Content Pipeline → Policy Decisions: provides findings (evidence: `promptshield/policy/engine.py`)
- Policy Decisions → Gateway Logic: returns verdict (evidence: `promptshield/policy/engine.py`)
- Gateway Logic → Action Guard: checks tool calls (evidence: `README.md`)
- Gateway Logic → Registry Guard: guards tool definitions (evidence: `README.md`)
- Detection Layers → Canary Checks: includes checks (evidence: `promptshield/layers/defaults.py`)
- Action Guard → Canary Checks: checks canary leaks (evidence: `README.md`)
- Policy Decisions → Policy Schema: uses policy rules (evidence: `promptshield/policy/engine.py`)
- Gateway Logic → Shared App State: uses shared services (evidence: `promptshield/api/state.py`)
- API Service → Shared App State: builds runtime state (evidence: `promptshield/api/server.py`)
- Gateway Logic → Event Bus: publishes verdicts (evidence: `promptshield/gateway/core.py`)
- Event Bus → SQLite Store: persists events (evidence: `promptshield/events.py`)
- SQLite Store → Secret Redaction: scrubs stored data (evidence: `promptshield/storage/db.py`)
- API Service → API Client: serves dashboard API (evidence: `promptshield/api/server.py`)
- Security Dashboard → API Client: requests data (evidence: `dashboard/src/App.tsx`)
- Event Bus → Security Dashboard: streams live events (evidence: `README.md`)
- Security Dashboard → API Service: manages approvals and policy (evidence: `README.md`)
- Lab Runner → Lab Agent: runs attack scenarios (evidence: `lab/run.py`)
- Lab Runner → Gateway Logic: exercises shielded runs (evidence: `lab/run.py`)
- Lab Runner → Attack Site: builds attack content (evidence: `lab/run.py`)
- Lab Agent → Attacker Sink: may exfiltrate data (evidence: `README.md`)
- Gateway Logic → Shared Schemas: validates boundary data (evidence: `promptshield/gateway/core.py`)
- Canary Checks → Secret Redaction: registers secrets (evidence: `promptshield/layers/canary.py`)
