# pr60t/firedamp architecture

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

- Interactive diagram: https://gitdiagram.com/pr60t/firedamp
- Repository: https://github.com/pr60t/firedamp

## Overview

Firedamp audits RAG tenant isolation: the CLI provisions or connects to a target, creates Alice and Bob sessions, plants canaries through the adapter, probes as the unauthorized persona, checks responses and retrieval context, and reports leaks and risk. The Open WebUI adapter separates authentication, ingestion, querying, and resource lifecycle operations. The repository also includes a bug-class and probe-channel taxonomy and a CVE registry. The graph reflects documented workflow and visible calls; unsampled implementation details and unshown wiring are omitted.

Main entry points: [`cli.py`](https://github.com/pr60t/firedamp/blob/main/cli.py) (Firedamp CLI), [`adapters/openwebui/__init__.py`](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/__init__.py) (Open WebUI adapter), [`adapters/openwebui/query.py`](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/query.py) (RAG and direct queries), [`adapters/openwebui/ingest.py`](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/ingest.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scan["Scan orchestration"]
  node_cli["Firedamp CLI<br/>[cli.py]"]
  node_target_lifecycle["Target lifecycle<br/>[target.py]"]
  node_adapter_registry["Adapter interface and registry<br/>[base.py]"]
  node_alice(("Owner persona"))
  node_bob(("Querier persona"))
end

subgraph group_engine["Probe and detection"]
  node_canary_engine["Canary and leak engine<br/>[engine.py]"]
end

subgraph group_openwebui["Open WebUI adapter"]
  node_openwebui_adapter["Open WebUI adapter<br/>[__init__.py]"]
  node_auth["Persona authentication<br/>[auth.py]"]
  node_ingestion["Document ingestion<br/>[ingest.py]"]
  node_query["RAG and direct queries<br/>[query.py]"]
  node_resource_lifecycle["Resource audit and cleanup<br/>[lifecycle.py]"]
end

subgraph group_findings["Vulnerability taxonomy and reporting"]
  node_bug_classes["Bug and channel taxonomy<br/>[bug_classes.py]"]
  node_cve_registry["CVE registry<br/>[cve_registry.py]"]
  node_reporter["Risk and telemetry reporter<br/>[reporter.py]"]
end

node_operator(("Audit operator"))
node_rag_target[("RAG platform")]

node_operator -->|"starts scan"| node_cli
node_cli -->|"starts or connects"| node_target_lifecycle
node_cli -->|"selects adapter"| node_adapter_registry
node_adapter_registry -->|"loads adapter"| node_openwebui_adapter
node_openwebui_adapter -->|"composes"| node_auth
node_openwebui_adapter -->|"composes"| node_ingestion
node_openwebui_adapter -->|"composes"| node_query
node_openwebui_adapter -->|"composes"| node_resource_lifecycle
node_cli -.->|"authenticates personas"| node_auth
node_cli -->|"sets up owner"| node_alice
node_cli -->|"probes as"| node_bob
node_cli -->|"generates and evaluates"| node_canary_engine
node_canary_engine -->|"provides decoys"| node_ingestion
node_cli -.->|"plants documents"| node_ingestion
node_ingestion -->|"uploads and indexes"| node_rag_target
node_cli -->|"dispatches probes"| node_query
node_query -->|"sends queries"| node_rag_target
node_query -.->|"returns response and context"| node_canary_engine
node_cli -.->|"runs resource checks"| node_resource_lifecycle
node_resource_lifecycle -->|"audits and cleans resources"| node_rag_target
node_cli -->|"reports scan results"| node_reporter
node_cve_registry -->|"uses taxonomy"| node_bug_classes

click node_cli "https://github.com/pr60t/firedamp/blob/main/cli.py"
click node_target_lifecycle "https://github.com/pr60t/firedamp/blob/main/core/target.py"
click node_adapter_registry "https://github.com/pr60t/firedamp/blob/main/adapters/base.py"
click node_canary_engine "https://github.com/pr60t/firedamp/blob/main/core/engine.py"
click node_bug_classes "https://github.com/pr60t/firedamp/blob/main/probes/schemas/bug_classes.py"
click node_cve_registry "https://github.com/pr60t/firedamp/blob/main/probes/cve_registry.py"
click node_reporter "https://github.com/pr60t/firedamp/blob/main/core/reporter.py"
click node_openwebui_adapter "https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/__init__.py"
click node_auth "https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/auth.py"
click node_ingestion "https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/ingest.py"
click node_query "https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/query.py"
click node_resource_lifecycle "https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/lifecycle.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_target_lifecycle,node_adapter_registry,node_alice,node_bob toneBlue
class node_canary_engine,node_rag_target toneAmber
class node_openwebui_adapter,node_auth,node_ingestion,node_query,node_resource_lifecycle toneMint
class node_bug_classes,node_cve_registry,node_reporter toneRose
class node_operator toneIndigo
```

## Components

### Scan orchestration

- [Firedamp CLI](https://github.com/pr60t/firedamp/blob/main/cli.py): `cli.py`
- [Target lifecycle](https://github.com/pr60t/firedamp/blob/main/core/target.py): `core/target.py`
- [Adapter interface and registry](https://github.com/pr60t/firedamp/blob/main/adapters/base.py): `adapters/base.py`
- **Owner persona**
- **Querier persona**

### Probe and detection

- [Canary and leak engine](https://github.com/pr60t/firedamp/blob/main/core/engine.py): `core/engine.py`

### Open WebUI adapter

- [Open WebUI adapter](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/__init__.py): `adapters/openwebui/__init__.py`
- [Persona authentication](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/auth.py): `adapters/openwebui/auth.py`
- [Document ingestion](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/ingest.py): `adapters/openwebui/ingest.py`
- [RAG and direct queries](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/query.py): `adapters/openwebui/query.py`
- [Resource audit and cleanup](https://github.com/pr60t/firedamp/blob/main/adapters/openwebui/lifecycle.py): `adapters/openwebui/lifecycle.py`

### Vulnerability taxonomy and reporting

- [Bug and channel taxonomy](https://github.com/pr60t/firedamp/blob/main/probes/schemas/bug_classes.py): `probes/schemas/bug_classes.py`
- [CVE registry](https://github.com/pr60t/firedamp/blob/main/probes/cve_registry.py): `probes/cve_registry.py`
- [Risk and telemetry reporter](https://github.com/pr60t/firedamp/blob/main/core/reporter.py): `core/reporter.py`

### Other components

- **Audit operator**
- **RAG platform**

## Connections

- Audit operator → Firedamp CLI: starts scan (evidence: `README.md`)
- Firedamp CLI → Target lifecycle: starts or connects (evidence: `cli.py`)
- Firedamp CLI → Adapter interface and registry: selects adapter (evidence: `cli.py`)
- Adapter interface and registry → Open WebUI adapter: loads adapter (evidence: `adapters/base.py`)
- Open WebUI adapter → Persona authentication: composes (evidence: `adapters/openwebui/__init__.py`)
- Open WebUI adapter → Document ingestion: composes (evidence: `adapters/openwebui/__init__.py`)
- Open WebUI adapter → RAG and direct queries: composes (evidence: `adapters/openwebui/__init__.py`)
- Open WebUI adapter → Resource audit and cleanup: composes (evidence: `adapters/openwebui/__init__.py`)
- Firedamp CLI → Persona authentication: authenticates personas
- Firedamp CLI → Owner persona: sets up owner (evidence: `README.md`)
- Firedamp CLI → Querier persona: probes as (evidence: `README.md`)
- Firedamp CLI → Canary and leak engine: generates and evaluates (evidence: `cli.py`)
- Canary and leak engine → Document ingestion: provides decoys (evidence: `adapters/openwebui/ingest.py`)
- Firedamp CLI → Document ingestion: plants documents
- Document ingestion → RAG platform: uploads and indexes (evidence: `adapters/openwebui/ingest.py`)
- Firedamp CLI → RAG and direct queries: dispatches probes (evidence: `cli.py`)
- RAG and direct queries → RAG platform: sends queries (evidence: `adapters/openwebui/query.py`)
- RAG and direct queries → Canary and leak engine: returns response and context
- Firedamp CLI → Resource audit and cleanup: runs resource checks
- Resource audit and cleanup → RAG platform: audits and cleans resources (evidence: `adapters/openwebui/lifecycle.py`)
- Firedamp CLI → Risk and telemetry reporter: reports scan results (evidence: `README.md`)
- CVE registry → Bug and channel taxonomy: uses taxonomy (evidence: `probes/cve_registry.py`)
