# arnavsharma-ind/cerberus- architecture

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

- Interactive diagram: https://gitdiagram.com/arnavsharma-ind/cerberus-
- Repository: https://github.com/arnavsharma-ind/cerberus-

## Overview

Cerberus is an MCP runtime behavioral firewall and SOC control plane. Agents send tool calls through its HTTP or Stdio ingress; Cerberus inspects and scores their behavior, applies policy and security checks, then forwards, blocks, or challenges calls while recording audit evidence. Operators review monitoring, incidents, policies, approvals, and analytics in the dashboard. The README documents major capabilities, but several implementation files were not sampled, so links to those subsystems use README evidence rather than claims of inspected calls.

Main entry points: [`src/cerberus/proxy/server.py`](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/server.py) (Proxy Engine), [`frontend/src/App.tsx`](https://github.com/arnavsharma-ind/cerberus-/blob/main/frontend/src/App.tsx) (React Dashboard), [`src/cerberus/proxy/logger.py`](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/logger.py) (Audit Ledger), [`src/cerberus/proxy/stdio_server.py`](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/stdio_server.py) (Stdio Proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["MCP Ingress"]
  node_http_gateway["HTTP Gateway<br/>[server.py]"]
  node_stdio_proxy["Stdio Proxy<br/>[stdio_server.py]"]
end

subgraph group_defense["Runtime Defense"]
  node_event_model["Tool Call Events<br/>[models.py]"]
  node_proxy_engine["Proxy Engine<br/>[server.py]"]
  node_behavior["Behavior Ensemble<br/>[ensemble.py]"]
  node_baseline[("Baseline Store<br/>[baseline_store.py]")]
  node_preflight["Schema &amp; Scope"]
  node_threat_detectors["Threat Detectors"]
  node_response_inspector["Response Inspection"]
  node_policy["OPA Policy<br/>[opa_client.py]"]
  node_policy_synthesis["Policy Synthesis<br/>[synthesizer.py]"]
end

subgraph group_operations["Forensics &amp; Operations"]
  node_challenge["Step-up Challenges"]
  node_redactor["Secret Redaction<br/>[redactor.py]"]
  node_audit[("Audit Ledger<br/>[logger.py]")]
  node_narrative["Attack Narratives<br/>[reconstructor.py]"]
  node_storage[("Storage Backend<br/>[backend.py]")]
  node_soc_routes["SOC API<br/>[soc_routes.py]"]
end

subgraph group_console["SOC Console"]
  node_frontend["React Dashboard<br/>[App.tsx]"]
  node_frontend_api["Dashboard API Client<br/>[api.ts]"]
end

node_agent(("MCP Agent"))
node_upstream["MCP Servers"]
node_operator(("Security Operator"))

node_agent -->|"sends tool calls"| node_http_gateway
node_agent -->|"uses Stdio"| node_stdio_proxy
node_http_gateway -->|"processes calls"| node_proxy_engine
node_stdio_proxy -->|"intercepts calls"| node_proxy_engine
node_proxy_engine -->|"builds events"| node_event_model
node_proxy_engine -->|"scores behavior"| node_behavior
node_proxy_engine -->|"checks stability"| node_baseline
node_proxy_engine -->|"checks tool scope"| node_preflight
node_proxy_engine -->|"runs detectors"| node_threat_detectors
node_proxy_engine -->|"enforces decisions"| node_policy
node_proxy_engine -->|"inspects responses"| node_response_inspector
node_proxy_engine -->|"requests approval"| node_challenge
node_proxy_engine -->|"scrubs secrets"| node_redactor
node_redactor -->|"redacts before persistence"| node_audit
node_proxy_engine -->|"records events"| node_audit
node_proxy_engine -->|"forwards allowed calls"| node_upstream
node_policy_synthesis -->|"pushes Rego policies"| node_policy
node_audit -->|"reconstructs attack chains"| node_narrative
node_proxy_engine -.->|"persists state"| node_storage
node_operator -->|"reviews security"| node_frontend
node_frontend -.->|"requests dashboard data"| node_frontend_api
node_frontend_api -.->|"calls SOC endpoints"| node_soc_routes
node_soc_routes -->|"reads engine state"| node_proxy_engine
node_frontend -.->|"manages policies"| node_policy_synthesis

click node_http_gateway "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/server.py"
click node_stdio_proxy "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/stdio_server.py"
click node_event_model "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/models.py"
click node_proxy_engine "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/server.py"
click node_behavior "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/behavioral/ensemble.py"
click node_baseline "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/behavioral/baseline_store.py"
click node_preflight "https://github.com/arnavsharma-ind/cerberus-/tree/main/src/cerberus/scanner"
click node_threat_detectors "https://github.com/arnavsharma-ind/cerberus-/tree/main/src/cerberus/detectors"
click node_response_inspector "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/response_inspector.py"
click node_policy "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/policy/opa_client.py"
click node_policy_synthesis "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/policy/synthesizer.py"
click node_challenge "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/challenge_manager.py"
click node_redactor "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/redactor.py"
click node_audit "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/logger.py"
click node_narrative "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/narrative/reconstructor.py"
click node_storage "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/storage/backend.py"
click node_soc_routes "https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/soc_routes.py"
click node_frontend "https://github.com/arnavsharma-ind/cerberus-/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/arnavsharma-ind/cerberus-/blob/main/frontend/src/api.ts"

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_http_gateway,node_stdio_proxy toneBlue
class node_event_model,node_proxy_engine,node_behavior,node_baseline,node_preflight,node_threat_detectors,node_response_inspector,node_policy,node_policy_synthesis toneAmber
class node_challenge,node_redactor,node_audit,node_narrative,node_storage,node_soc_routes,node_upstream toneMint
class node_frontend,node_frontend_api toneRose
class node_agent,node_operator toneIndigo
```

## Components

### MCP Ingress

- [HTTP Gateway](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/server.py): `src/cerberus/proxy/server.py`
- [Stdio Proxy](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/stdio_server.py): `src/cerberus/proxy/stdio_server.py`

### Runtime Defense

- [Tool Call Events](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/models.py): `src/cerberus/proxy/models.py`
- [Proxy Engine](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/server.py): `src/cerberus/proxy/server.py`
- [Behavior Ensemble](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/behavioral/ensemble.py): `src/cerberus/behavioral/ensemble.py`
- [Baseline Store](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/behavioral/baseline_store.py): `src/cerberus/behavioral/baseline_store.py`
- [Schema & Scope](https://github.com/arnavsharma-ind/cerberus-/tree/main/src/cerberus/scanner): `src/cerberus/scanner`
- [Threat Detectors](https://github.com/arnavsharma-ind/cerberus-/tree/main/src/cerberus/detectors): `src/cerberus/detectors`
- [Response Inspection](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/response_inspector.py): `src/cerberus/proxy/response_inspector.py`
- [OPA Policy](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/policy/opa_client.py): `src/cerberus/policy/opa_client.py`
- [Policy Synthesis](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/policy/synthesizer.py): `src/cerberus/policy/synthesizer.py`

### Forensics & Operations

- [Step-up Challenges](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/challenge_manager.py): `src/cerberus/proxy/challenge_manager.py`
- [Secret Redaction](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/redactor.py): `src/cerberus/proxy/redactor.py`
- [Audit Ledger](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/logger.py): `src/cerberus/proxy/logger.py`
- [Attack Narratives](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/narrative/reconstructor.py): `src/cerberus/narrative/reconstructor.py`
- [Storage Backend](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/storage/backend.py): `src/cerberus/storage/backend.py`
- [SOC API](https://github.com/arnavsharma-ind/cerberus-/blob/main/src/cerberus/proxy/soc_routes.py): `src/cerberus/proxy/soc_routes.py`

### SOC Console

- [React Dashboard](https://github.com/arnavsharma-ind/cerberus-/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard API Client](https://github.com/arnavsharma-ind/cerberus-/blob/main/frontend/src/api.ts): `frontend/src/api.ts`

### Other components

- **MCP Agent**
- **MCP Servers**
- **Security Operator**

## Connections

- MCP Agent → HTTP Gateway: sends tool calls (evidence: `README.md`)
- MCP Agent → Stdio Proxy: uses Stdio (evidence: `README.md`)
- HTTP Gateway → Proxy Engine: processes calls (evidence: `src/cerberus/proxy/server.py`)
- Stdio Proxy → Proxy Engine: intercepts calls (evidence: `README.md`)
- Proxy Engine → Tool Call Events: builds events (evidence: `src/cerberus/proxy/server.py`)
- Proxy Engine → Behavior Ensemble: scores behavior (evidence: `src/cerberus/proxy/server.py`)
- Proxy Engine → Baseline Store: checks stability (evidence: `src/cerberus/proxy/server.py`)
- Proxy Engine → Schema & Scope: checks tool scope (evidence: `README.md`)
- Proxy Engine → Threat Detectors: runs detectors (evidence: `src/cerberus/proxy/server.py`)
- Proxy Engine → OPA Policy: enforces decisions (evidence: `src/cerberus/proxy/server.py`)
- Proxy Engine → Response Inspection: inspects responses (evidence: `src/cerberus/proxy/engine.py`)
- Proxy Engine → Step-up Challenges: requests approval (evidence: `src/cerberus/proxy/engine.py`)
- Proxy Engine → Secret Redaction: scrubs secrets (evidence: `README.md`)
- Secret Redaction → Audit Ledger: redacts before persistence (evidence: `README.md`)
- Proxy Engine → Audit Ledger: records events (evidence: `README.md`)
- Proxy Engine → MCP Servers: forwards allowed calls (evidence: `README.md`)
- Policy Synthesis → OPA Policy: pushes Rego policies (evidence: `README.md`)
- Audit Ledger → Attack Narratives: reconstructs attack chains (evidence: `README.md`)
- Proxy Engine → Storage Backend: persists state (evidence: `src/cerberus/proxy/server.py`)
- Security Operator → React Dashboard: reviews security (evidence: `frontend/src/App.tsx`)
- React Dashboard → Dashboard API Client: requests dashboard data
- Dashboard API Client → SOC API: calls SOC endpoints
- SOC API → Proxy Engine: reads engine state (evidence: `src/cerberus/proxy/soc_routes.py`)
- React Dashboard → Policy Synthesis: manages policies (evidence: `README.md`)
