# khaledobeid/multi-agent-mcp-security-auditor architecture

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

- Interactive diagram: https://gitdiagram.com/khaledobeid/multi-agent-mcp-security-auditor
- Repository: https://github.com/khaledobeid/multi-agent-mcp-security-auditor

## Overview

This is a multi-agent auditor for third-party MCP servers and AI-agent tool packages. A user submits a package through the CLI; the graph prepares audit state, inspects manifests and permissions, maps findings to OWASP guidance and dependency vulnerabilities, conditionally red-teams dangerous packages, then produces a verdict and patched manifest. The graph and shared state are the internal orchestration layer. The README documents capabilities not fully shown in excerpts; links based on those statements are cited there, and unsampled implementation details are not inferred.

Main entry points: [`src/mcp_security_auditor/graph.py`](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/graph.py) (Audit graph), [`src/mcp_security_auditor/agents/inspector.py`](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/inspector.py) (Surface inspector), [`src/mcp_security_auditor/agents/threat_analyst.py`](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/threat_analyst.py) (Threat analyst), [`src/mcp_security_auditor/llm.py`](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/llm.py) (LLM and embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_cli["Audit CLI<br/>[main.py]"]
  node_workflow["Audit graph<br/>[graph.py]"]
end

subgraph group_audit["Audit agents"]
  node_intake["Package intake<br/>[intake.py]"]
  node_inspector["Surface inspector<br/>[inspector.py]"]
  node_analyst["Threat analyst<br/>[threat_analyst.py]"]
  node_redteam["Red-team agent<br/>[red_team.py]"]
  node_report["Report and verdict<br/>[report.py]"]
end

subgraph group_analysis["Analysis tools"]
  node_scanner["Manifest scanner"]
  node_permissions["Permission diff<br/>[permission_diff.py]"]
  node_osv["Dependency lookup<br/>[osv.py]"]
  node_sandbox["Sandbox test<br/>[sandbox.py]"]
  node_patcher["Manifest patcher<br/>[patcher.py]"]
end

subgraph group_foundation["Shared runtime"]
  node_state["Audit state<br/>[state.py]"]
  node_contracts["Audit contracts<br/>[schemas.py]"]
  node_agentloop["Agent turn loop<br/>[agent_loop.py]"]
  node_toolrun["Tool execution<br/>[tool_exec.py]"]
  node_messages["Message helpers<br/>[messages.py]"]
  node_text["Untrusted text handling<br/>[text.py]"]
  node_llm["LLM and embeddings<br/>[llm.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_knowledge["Security knowledge"]
  node_retrieval["Security retrieval<br/>[rag.py]"]
  node_ingest["Corpus ingestion<br/>[ingest.py]"]
  node_vectorstore[("Vector store")]
end

node_user(("Package submitter"))
node_gemini["Gemini services"]
node_osvservice["OSV.dev"]

node_user -->|"submits package"| node_cli
node_cli -->|"runs audit"| node_workflow
node_workflow -->|"starts at"| node_intake
node_workflow -->|"dispatches"| node_inspector
node_workflow -->|"dispatches"| node_analyst
node_workflow -->|"conditionally dispatches"| node_redteam
node_workflow -->|"dispatches"| node_report
node_workflow -->|"uses"| node_state
node_intake -->|"updates"| node_state
node_inspector -->|"scans package"| node_scanner
node_inspector -->|"checks permissions"| node_permissions
node_inspector -->|"requests agent turn"| node_agentloop
node_analyst -->|"searches guidance"| node_retrieval
node_analyst -->|"checks dependencies"| node_osv
node_analyst -->|"requests agent turn"| node_agentloop
node_redteam -->|"tests suspicious tools"| node_sandbox
node_report -->|"patches manifest"| node_patcher
node_inspector -->|"executes tool calls"| node_toolrun
node_inspector -->|"formats package brief"| node_text
node_cli -->|"prints run messages"| node_messages
node_agentloop -->|"requests model"| node_llm
node_llm -->|"reads model settings"| node_settings
node_llm -->|"calls"| node_gemini
node_retrieval -->|"gets embeddings"| node_llm
node_retrieval -->|"searches"| node_vectorstore
node_ingest -->|"builds"| node_vectorstore
node_osv -->|"queries"| node_osvservice
node_contracts -->|"defines state types"| node_state

click node_cli "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/main.py"
click node_workflow "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/graph.py"
click node_state "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/state.py"
click node_contracts "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/schemas.py"
click node_intake "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/intake.py"
click node_inspector "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/inspector.py"
click node_analyst "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/threat_analyst.py"
click node_redteam "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/red_team.py"
click node_report "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/report.py"
click node_scanner "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/manifest_scanner.py"
click node_permissions "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/permission_diff.py"
click node_osv "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/osv.py"
click node_sandbox "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/sandbox.py"
click node_patcher "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/patcher.py"
click node_retrieval "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/rag.py"
click node_ingest "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/rag/ingest.py"
click node_agentloop "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/agent_loop.py"
click node_toolrun "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/tool_exec.py"
click node_messages "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/messages.py"
click node_text "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/text.py"
click node_llm "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/llm.py"
click node_settings "https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/config.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_cli,node_workflow toneBlue
class node_intake,node_inspector,node_analyst,node_redteam,node_report toneAmber
class node_scanner,node_permissions,node_osv,node_sandbox,node_patcher toneMint
class node_state,node_contracts,node_agentloop,node_toolrun,node_messages,node_text,node_llm,node_settings toneRose
class node_retrieval,node_ingest,node_vectorstore,node_user,node_gemini,node_osvservice toneIndigo
```

## Components

### Entry and orchestration

- [Audit CLI](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/main.py): `src/mcp_security_auditor/main.py`
- [Audit graph](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/graph.py): `src/mcp_security_auditor/graph.py`

### Audit agents

- [Package intake](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/intake.py): `src/mcp_security_auditor/agents/intake.py`
- [Surface inspector](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/inspector.py): `src/mcp_security_auditor/agents/inspector.py`
- [Threat analyst](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/threat_analyst.py): `src/mcp_security_auditor/agents/threat_analyst.py`
- [Red-team agent](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/red_team.py): `src/mcp_security_auditor/agents/red_team.py`
- [Report and verdict](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/agents/report.py): `src/mcp_security_auditor/agents/report.py`

### Analysis tools

- [Manifest scanner](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/manifest_scanner.py): `src/mcp_security_auditor/tools/manifest_scanner.py`
- [Permission diff](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/permission_diff.py): `src/mcp_security_auditor/tools/permission_diff.py`
- [Dependency lookup](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/osv.py): `src/mcp_security_auditor/tools/osv.py`
- [Sandbox test](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/sandbox.py): `src/mcp_security_auditor/tools/sandbox.py`
- [Manifest patcher](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/patcher.py): `src/mcp_security_auditor/tools/patcher.py`

### Shared runtime

- [Audit state](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/state.py): `src/mcp_security_auditor/state.py`
- [Audit contracts](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/schemas.py): `src/mcp_security_auditor/schemas.py`
- [Agent turn loop](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/agent_loop.py): `src/mcp_security_auditor/utils/agent_loop.py`
- [Tool execution](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/tool_exec.py): `src/mcp_security_auditor/utils/tool_exec.py`
- [Message helpers](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/messages.py): `src/mcp_security_auditor/utils/messages.py`
- [Untrusted text handling](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/utils/text.py): `src/mcp_security_auditor/utils/text.py`
- [LLM and embeddings](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/llm.py): `src/mcp_security_auditor/llm.py`
- [Runtime settings](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/config.py): `src/mcp_security_auditor/config.py`

### Security knowledge

- [Security retrieval](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/tools/rag.py): `src/mcp_security_auditor/tools/rag.py`
- [Corpus ingestion](https://github.com/khaledobeid/multi-agent-mcp-security-auditor/blob/main/src/mcp_security_auditor/rag/ingest.py): `src/mcp_security_auditor/rag/ingest.py`
- **Vector store**

### Other components

- **Package submitter**
- **Gemini services**
- **OSV.dev**

## Connections

- Package submitter → Audit CLI: submits package (evidence: `README.md`)
- Audit CLI → Audit graph: runs audit (evidence: `src/mcp_security_auditor/main.py`)
- Audit graph → Package intake: starts at (evidence: `src/mcp_security_auditor/graph.py`)
- Audit graph → Surface inspector: dispatches (evidence: `src/mcp_security_auditor/graph.py`)
- Audit graph → Threat analyst: dispatches (evidence: `src/mcp_security_auditor/graph.py`)
- Audit graph → Red-team agent: conditionally dispatches (evidence: `src/mcp_security_auditor/graph.py`)
- Audit graph → Report and verdict: dispatches (evidence: `src/mcp_security_auditor/graph.py`)
- Audit graph → Audit state: uses (evidence: `src/mcp_security_auditor/graph.py`)
- Package intake → Audit state: updates (evidence: `README.md`)
- Surface inspector → Manifest scanner: scans package (evidence: `src/mcp_security_auditor/agents/inspector.py`)
- Surface inspector → Permission diff: checks permissions (evidence: `src/mcp_security_auditor/agents/inspector.py`)
- Surface inspector → Agent turn loop: requests agent turn (evidence: `src/mcp_security_auditor/agents/inspector.py`)
- Threat analyst → Security retrieval: searches guidance (evidence: `src/mcp_security_auditor/agents/threat_analyst.py`)
- Threat analyst → Dependency lookup: checks dependencies (evidence: `src/mcp_security_auditor/agents/threat_analyst.py`)
- Threat analyst → Agent turn loop: requests agent turn (evidence: `src/mcp_security_auditor/agents/threat_analyst.py`)
- Red-team agent → Sandbox test: tests suspicious tools (evidence: `README.md`)
- Report and verdict → Manifest patcher: patches manifest (evidence: `src/mcp_security_auditor/agents/report.py`)
- Surface inspector → Tool execution: executes tool calls (evidence: `src/mcp_security_auditor/agents/inspector.py`)
- Surface inspector → Untrusted text handling: formats package brief (evidence: `src/mcp_security_auditor/agents/inspector.py`)
- Audit CLI → Message helpers: prints run messages (evidence: `README.md`)
- Agent turn loop → LLM and embeddings: requests model (evidence: `src/mcp_security_auditor/utils/agent_loop.py`)
- LLM and embeddings → Runtime settings: reads model settings (evidence: `src/mcp_security_auditor/llm.py`)
- LLM and embeddings → Gemini services: calls (evidence: `src/mcp_security_auditor/llm.py`)
- Security retrieval → LLM and embeddings: gets embeddings (evidence: `src/mcp_security_auditor/tools/rag.py`)
- Security retrieval → Vector store: searches (evidence: `src/mcp_security_auditor/tools/rag.py`)
- Corpus ingestion → Vector store: builds (evidence: `README.md`)
- Dependency lookup → OSV.dev: queries (evidence: `README.md`)
- Audit contracts → Audit state: defines state types (evidence: `src/mcp_security_auditor/state.py`)
