# eshan-r/behemoth architecture

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

- Interactive diagram: https://gitdiagram.com/eshan-r/behemoth
- Repository: https://github.com/eshan-r/behemoth

## Overview

Behemoth is an AI-assisted API security auditing framework. The workflow starts with a target URL and OpenAPI specification: the CLI can discover a specification, then the orchestrator scans endpoints, coordinates attack planning and HTTP execution, adapts failed strikes, and saves vulnerability reports while updating a live dashboard. Warlock, Berserker, Alchemist, and Paladin are distinct audit stages; Spirit-Eye and Shadow Memory are Berserker capabilities. The graph follows shown calls and README-described features; unsampled implementation details are represented only where their paths are supported.

Main entry points: [`src/behemoth/core.py`](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/core.py) (Battle Orchestrator), [`src/behemoth/agents/berserker.py`](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/berserker.py) (Berserker Executor), [`src/behemoth/cli.py`](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/cli.py) (CLI), [`src/behemoth/utils/scryer.py`](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/scryer.py) (Spec Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Discovery"]
  node_cli["CLI<br/>[cli.py]"]
  node_scryer["Spec Discovery<br/>[scryer.py]"]
  node_spec["OpenAPI Spec"]
end

subgraph group_engine["Audit Orchestration"]
  node_scanner["Endpoint Scanner<br/>[scanner.py]"]
  node_orchestrator["Battle Orchestrator<br/>[core.py]"]
  node_router["Model Router<br/>[router.py]"]
end

subgraph group_spirits["Agent Circuit"]
  node_warlock["Warlock Scout<br/>[warlock.py]"]
  node_berserker["Berserker Executor<br/>[berserker.py]"]
  node_spirit_eye["Spirit-Eye<br/>[berserker.py]"]
  node_shadow_memory["Shadow Memory<br/>[berserker.py]"]
  node_alchemist["Alchemist Refiner<br/>[alchemist.py]"]
end

subgraph group_results["Evidence and Reporting"]
  node_dashboard["War Room<br/>[dashboard.py]"]
  node_paladin["Paladin Scribe<br/>[paladin.py]"]
  node_report["Finding Reports<br/>[core.py]"]
end

node_operator(("Auditor"))
node_target["Target API"]
node_search["Web Search"]
node_model_service["Gemini Models"]

node_operator -->|"invokes"| node_cli
node_cli -->|"discovers spec"| node_scryer
node_scryer -->|"searches"| node_search
node_scryer -->|"downloads"| node_spec
node_operator -->|"provides"| node_spec
node_cli -->|"starts audit"| node_orchestrator
node_orchestrator -->|"scans spec"| node_scanner
node_scanner -->|"reads"| node_spec
node_orchestrator -->|"selects models"| node_router
node_orchestrator -->|"requests plans"| node_warlock
node_orchestrator -->|"executes strikes"| node_berserker
node_orchestrator -->|"refines plans"| node_alchemist
node_orchestrator -->|"requests reports"| node_paladin
node_orchestrator -->|"updates"| node_dashboard
node_berserker -->|"sends requests"| node_target
node_berserker -->|"analyzes responses"| node_spirit_eye
node_berserker -->|"stores session intel"| node_shadow_memory
node_orchestrator -->|"backtracks gates"| node_shadow_memory
node_warlock -->|"generates plans"| node_model_service
node_alchemist -->|"refines attacks"| node_model_service
node_paladin -->|"generates findings"| node_model_service
node_orchestrator -->|"saves reports"| node_report
node_paladin -->|"writes report content"| node_report

click node_cli "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/cli.py"
click node_scryer "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/scryer.py"
click node_scanner "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/scanner.py"
click node_orchestrator "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/core.py"
click node_router "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/router.py"
click node_dashboard "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/dashboard.py"
click node_warlock "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/warlock.py"
click node_berserker "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/berserker.py"
click node_spirit_eye "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/berserker.py"
click node_shadow_memory "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/berserker.py"
click node_alchemist "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/alchemist.py"
click node_paladin "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/paladin.py"
click node_report "https://github.com/eshan-r/behemoth/blob/main/src/behemoth/core.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_scryer,node_spec toneBlue
class node_scanner,node_orchestrator,node_router toneAmber
class node_warlock,node_berserker,node_spirit_eye,node_shadow_memory,node_alchemist,node_target toneMint
class node_dashboard,node_paladin,node_report toneRose
class node_operator,node_search,node_model_service toneIndigo
```

## Components

### Entry and Discovery

- [CLI](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/cli.py): `src/behemoth/cli.py`
- [Spec Discovery](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/scryer.py): `src/behemoth/utils/scryer.py`
- **OpenAPI Spec**

### Audit Orchestration

- [Endpoint Scanner](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/scanner.py): `src/behemoth/utils/scanner.py`
- [Battle Orchestrator](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/core.py): `src/behemoth/core.py`
- [Model Router](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/router.py): `src/behemoth/utils/router.py`

### Agent Circuit

- [Warlock Scout](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/warlock.py): `src/behemoth/agents/warlock.py`
- [Berserker Executor](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/berserker.py): `src/behemoth/agents/berserker.py`
- [Spirit-Eye](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/berserker.py): `src/behemoth/agents/berserker.py`
- [Shadow Memory](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/berserker.py): `src/behemoth/agents/berserker.py`
- [Alchemist Refiner](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/alchemist.py): `src/behemoth/agents/alchemist.py`

### Evidence and Reporting

- [War Room](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/utils/dashboard.py): `src/behemoth/utils/dashboard.py`
- [Paladin Scribe](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/agents/paladin.py): `src/behemoth/agents/paladin.py`
- [Finding Reports](https://github.com/eshan-r/behemoth/blob/main/src/behemoth/core.py): `src/behemoth/core.py`

### Other components

- **Auditor**
- **Target API**
- **Web Search**
- **Gemini Models**

## Connections

- Auditor → CLI: invokes (evidence: `src/behemoth/cli.py`)
- CLI → Spec Discovery: discovers spec (evidence: `src/behemoth/cli.py`)
- Spec Discovery → Web Search: searches (evidence: `src/behemoth/utils/scryer.py`)
- Spec Discovery → OpenAPI Spec: downloads (evidence: `src/behemoth/utils/scryer.py`)
- Auditor → OpenAPI Spec: provides
- CLI → Battle Orchestrator: starts audit (evidence: `src/behemoth/cli.py`)
- Battle Orchestrator → Endpoint Scanner: scans spec (evidence: `src/behemoth/core.py`)
- Endpoint Scanner → OpenAPI Spec: reads (evidence: `src/behemoth/utils/scanner.py`)
- Battle Orchestrator → Model Router: selects models (evidence: `src/behemoth/core.py`)
- Battle Orchestrator → Warlock Scout: requests plans (evidence: `src/behemoth/core.py`)
- Battle Orchestrator → Berserker Executor: executes strikes (evidence: `src/behemoth/core.py`)
- Battle Orchestrator → Alchemist Refiner: refines plans (evidence: `src/behemoth/core.py`)
- Battle Orchestrator → Paladin Scribe: requests reports (evidence: `src/behemoth/core.py`)
- Battle Orchestrator → War Room: updates (evidence: `src/behemoth/core.py`)
- Berserker Executor → Target API: sends requests (evidence: `src/behemoth/agents/berserker.py`)
- Berserker Executor → Spirit-Eye: analyzes responses (evidence: `README.md`)
- Berserker Executor → Shadow Memory: stores session intel (evidence: `README.md`)
- Battle Orchestrator → Shadow Memory: backtracks gates (evidence: `src/behemoth/core.py`)
- Warlock Scout → Gemini Models: generates plans (evidence: `src/behemoth/agents/warlock.py`)
- Alchemist Refiner → Gemini Models: refines attacks (evidence: `src/behemoth/agents/alchemist.py`)
- Paladin Scribe → Gemini Models: generates findings (evidence: `src/behemoth/agents/paladin.py`)
- Battle Orchestrator → Finding Reports: saves reports (evidence: `src/behemoth/core.py`)
- Paladin Scribe → Finding Reports: writes report content (evidence: `src/behemoth/core.py`)