# 0xsamaaritan/pandora architecture

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

- Interactive diagram: https://gitdiagram.com/0xsamaaritan/pandora
- Repository: https://github.com/0xsamaaritan/pandora

## Overview

Pandora is a single-organisation exposure-monitoring CLI. The operator supplies organisation identifiers and configuration, chooses a surface or dark run, and Pandora queries the relevant source set, reconciles findings against persistent state, then reports and optionally alerts on new results. The graph preserves the documented source capabilities, including dork customization and secret confirmation. Source integrations are grouped by run mode because the sampled source excerpt is incomplete; their individual registrations and calls cannot all be verified here.

Main entry points: [`pandora/cli.py`](https://github.com/0xsamaaritan/pandora/blob/main/pandora/cli.py) (CLI runner), [`pandora/sources.py`](https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py) (Surface sources), [`pandora/model.py`](https://github.com/0xsamaaritan/pandora/blob/main/pandora/model.py) (Finding model), [`pandora/report.py`](https://github.com/0xsamaaritan/pandora/blob/main/pandora/report.py) (Report generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run control"]
  node_cli["CLI runner<br/>[cli.py]"]
  node_banner["Startup banner<br/>[banner.py]"]
end

subgraph group_sources["Exposure sources"]
  node_surface["Surface sources<br/>[sources.py]"]
  node_dark["Dark sources<br/>[sources.py]"]
  node_dorks["Search dorks<br/>[sources.py]"]
  node_gitleaks["Secret confirmation<br/>[sources.py]"]
end

subgraph group_tracking["Finding tracking"]
  node_finding["Finding model<br/>[model.py]"]
  node_store[("Dedupe state<br/>[store.py]")]
end

subgraph group_delivery["Reports and alerts"]
  node_reports["Report generation<br/>[report.py]"]
end

node_operator(("Operator"))
node_config["YAML config"]
node_indexes{{"OSINT and threat indexes"}}
node_reportfiles["JSON and Markdown reports"]
node_alerts{{"Webhook and email"}}
node_gitrepos{{"Configured repositories"}}

node_operator -->|"runs"| node_cli
node_config -->|"configures"| node_cli
node_cli -->|"prints"| node_banner
node_cli -->|"dispatches"| node_surface
node_cli -->|"dispatches"| node_dark
node_surface -->|"queries"| node_indexes
node_dark -->|"queries"| node_indexes
node_surface -->|"uses"| node_dorks
node_surface -->|"includes"| node_gitleaks
node_gitleaks -->|"scans"| node_gitrepos
node_surface -->|"creates"| node_finding
node_dark -->|"creates"| node_finding
node_cli -->|"collects"| node_finding
node_cli -->|"reconciles"| node_store
node_store -->|"keys and restores"| node_finding
node_cli -->|"writes and summarizes"| node_reports
node_reports -->|"writes"| node_reportfiles
node_reports -->|"notifies"| node_alerts

click node_cli "https://github.com/0xsamaaritan/pandora/blob/main/pandora/cli.py"
click node_banner "https://github.com/0xsamaaritan/pandora/blob/main/pandora/banner.py"
click node_surface "https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py"
click node_dark "https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py"
click node_dorks "https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py"
click node_gitleaks "https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py"
click node_finding "https://github.com/0xsamaaritan/pandora/blob/main/pandora/model.py"
click node_store "https://github.com/0xsamaaritan/pandora/blob/main/pandora/store.py"
click node_reports "https://github.com/0xsamaaritan/pandora/blob/main/pandora/report.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_banner toneBlue
class node_surface,node_dark,node_dorks,node_gitleaks toneAmber
class node_finding,node_store,node_alerts toneMint
class node_reports toneRose
class node_operator,node_config,node_indexes,node_reportfiles,node_gitrepos toneIndigo
```

## Components

### Run control

- [CLI runner](https://github.com/0xsamaaritan/pandora/blob/main/pandora/cli.py): `pandora/cli.py`
- [Startup banner](https://github.com/0xsamaaritan/pandora/blob/main/pandora/banner.py): `pandora/banner.py`

### Exposure sources

- [Surface sources](https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py): `pandora/sources.py`
- [Dark sources](https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py): `pandora/sources.py`
- [Search dorks](https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py): `pandora/sources.py`
- [Secret confirmation](https://github.com/0xsamaaritan/pandora/blob/main/pandora/sources.py): `pandora/sources.py`

### Finding tracking

- [Finding model](https://github.com/0xsamaaritan/pandora/blob/main/pandora/model.py): `pandora/model.py`
- [Dedupe state](https://github.com/0xsamaaritan/pandora/blob/main/pandora/store.py): `pandora/store.py`

### Reports and alerts

- [Report generation](https://github.com/0xsamaaritan/pandora/blob/main/pandora/report.py): `pandora/report.py`

### Other components

- **Operator**
- **YAML config**
- **OSINT and threat indexes**
- **JSON and Markdown reports**
- **Webhook and email**
- **Configured repositories**

## Connections

- Operator → CLI runner: runs (evidence: `README.md`)
- YAML config → CLI runner: configures (evidence: `pandora/cli.py`)
- CLI runner → Startup banner: prints (evidence: `pandora/cli.py`)
- CLI runner → Surface sources: dispatches (evidence: `pandora/cli.py`)
- CLI runner → Dark sources: dispatches (evidence: `pandora/cli.py`)
- Surface sources → OSINT and threat indexes: queries (evidence: `README.md`)
- Dark sources → OSINT and threat indexes: queries (evidence: `README.md`)
- Surface sources → Search dorks: uses (evidence: `pandora/sources.py`)
- Surface sources → Secret confirmation: includes (evidence: `README.md`)
- Secret confirmation → Configured repositories: scans (evidence: `pandora/sources.py`)
- Surface sources → Finding model: creates (evidence: `pandora/sources.py`)
- Dark sources → Finding model: creates (evidence: `pandora/sources.py`)
- CLI runner → Finding model: collects (evidence: `pandora/cli.py`)
- CLI runner → Dedupe state: reconciles (evidence: `pandora/cli.py`)
- Dedupe state → Finding model: keys and restores (evidence: `pandora/store.py`)
- CLI runner → Report generation: writes and summarizes (evidence: `pandora/cli.py`)
- Report generation → JSON and Markdown reports: writes (evidence: `pandora/report.py`)
- Report generation → Webhook and email: notifies (evidence: `pandora/report.py`)
