# ogiwbuz188/adaptive-fuzzer architecture

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

- Interactive diagram: https://gitdiagram.com/ogiwbuz188/adaptive-fuzzer
- Repository: https://github.com/ogiwbuz188/adaptive-fuzzer

## Overview

Adaptive Behavioral Fuzzer is a research prototype for reproducible, sandboxed fuzzing of 100 synthetic REST targets. Its main flow loads a benchmark manifest, derives target runs and seeds, launches targets and a fuzzer worker in Bubblewrap, discovers routes, mutates requests, analyzes responses, and records telemetry and reports. Optional branches provide authorization probes and a path-traversal canary; evaluation consumes recorded results and verified labels. The README documents several capabilities whose implementations are unsampled, so those nodes and links are limited to documented relationships.

Main entry points: [`src/execution/sandbox_worker.py`](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/sandbox_worker.py) (Sandbox worker), [`src/fuzzer.py`](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/fuzzer.py) (Behavioral fuzzer), [`src/execution/runner.py`](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/runner.py) (Benchmark runner), [`src/execution/sandbox.py`](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/sandbox.py) (Bubblewrap sandbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Run execution"]
  node_manifest["Benchmark manifest<br/>[manifest.py]"]
  node_runner["Benchmark runner<br/>[runner.py]"]
  node_sandbox["Bubblewrap sandbox<br/>[sandbox.py]"]
  node_target["Synthetic API targets"]
  node_worker["Sandbox worker<br/>[sandbox_worker.py]"]
end

subgraph group_fuzzing["Fuzzing and detection"]
  node_fuzzer["Behavioral fuzzer<br/>[fuzzer.py]"]
  node_statistical["Statistical detector<br/>[statistical.py]"]
  node_fingerprint["Fingerprint detector"]
  node_pathoracle["Path canary oracle<br/>[path_oracle.py]"]
  node_bola["Authorization probe<br/>[bola.py]"]
end

subgraph group_records["Telemetry and provenance"]
  node_telemetryschema["Telemetry events<br/>[schema.py]"]
  node_telemetrywriter["Telemetry writer<br/>[writer.py]"]
  node_artifacts[("Run artifacts")]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_statsanalysis["Statistical analysis"]
  node_groundtruth["Verified labels<br/>[ground_truth.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts runs"| node_runner
node_runner -->|"loads"| node_manifest
node_runner -->|"builds sandbox command"| node_sandbox
node_sandbox -->|"isolates target"| node_target
node_sandbox -->|"launches worker"| node_worker
node_worker -->|"runs fuzz session"| node_fuzzer
node_worker -->|"runs scenarios"| node_bola
node_worker -->|"reads benchmark settings"| node_manifest
node_fuzzer -->|"sends requests"| node_target
node_fuzzer -->|"analyzes responses"| node_statistical
node_fuzzer -->|"checks fingerprints"| node_fingerprint
node_fuzzer -->|"checks canary token"| node_pathoracle
node_worker -->|"creates events"| node_telemetryschema
node_worker -->|"appends events"| node_telemetrywriter
node_telemetrywriter -->|"serializes events"| node_telemetryschema
node_telemetrywriter -->|"writes telemetry"| node_artifacts
node_runner -->|"writes logs and reports"| node_artifacts
node_researcher -->|"evaluates run"| node_metrics
node_metrics -->|"reads telemetry"| node_artifacts
node_metrics -->|"checks labels"| node_groundtruth
node_researcher -.->|"compares detector modes"| node_statsanalysis

click node_manifest "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/manifest.py"
click node_runner "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/runner.py"
click node_sandbox "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/sandbox.py"
click node_target "https://github.com/ogiwbuz188/adaptive-fuzzer/tree/main/research_benchmark"
click node_worker "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/sandbox_worker.py"
click node_fuzzer "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/fuzzer.py"
click node_statistical "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/statistical.py"
click node_fingerprint "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/response_fingerprint.py"
click node_pathoracle "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/path_oracle.py"
click node_bola "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/bola.py"
click node_telemetryschema "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/telemetry/schema.py"
click node_telemetrywriter "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/telemetry/writer.py"
click node_metrics "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/evaluation/metrics.py"
click node_statsanalysis "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/evaluation/statistical_analysis.py"
click node_groundtruth "https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/ground_truth.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_manifest,node_runner,node_sandbox,node_target,node_worker toneBlue
class node_fuzzer,node_statistical,node_fingerprint,node_pathoracle,node_bola toneAmber
class node_telemetryschema,node_telemetrywriter,node_artifacts toneMint
class node_metrics,node_statsanalysis,node_groundtruth toneRose
class node_researcher toneIndigo
```

## Components

### Run execution

- [Benchmark manifest](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/manifest.py): `src/execution/manifest.py`
- [Benchmark runner](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/runner.py): `src/execution/runner.py`
- [Bubblewrap sandbox](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/sandbox.py): `src/execution/sandbox.py`
- [Synthetic API targets](https://github.com/ogiwbuz188/adaptive-fuzzer/tree/main/research_benchmark): `research_benchmark`
- [Sandbox worker](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/execution/sandbox_worker.py): `src/execution/sandbox_worker.py`

### Fuzzing and detection

- [Behavioral fuzzer](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/fuzzer.py): `src/fuzzer.py`
- [Statistical detector](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/statistical.py): `src/detectors/statistical.py`
- [Fingerprint detector](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/response_fingerprint.py): `src/detectors/response_fingerprint.py`
- [Path canary oracle](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/path_oracle.py): `src/detectors/path_oracle.py`
- [Authorization probe](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/detectors/bola.py): `src/detectors/bola.py`

### Telemetry and provenance

- [Telemetry events](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/telemetry/schema.py): `src/telemetry/schema.py`
- [Telemetry writer](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/telemetry/writer.py): `src/telemetry/writer.py`
- **Run artifacts**

### Evaluation

- [Evaluation metrics](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Statistical analysis](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/evaluation/statistical_analysis.py): `src/evaluation/statistical_analysis.py`
- [Verified labels](https://github.com/ogiwbuz188/adaptive-fuzzer/blob/main/src/ground_truth.py): `src/ground_truth.py`

### Other components

- **Researcher**

## Connections

- Researcher → Benchmark runner: starts runs (evidence: `README.md`)
- Benchmark runner → Benchmark manifest: loads (evidence: `src/execution/runner.py`)
- Benchmark runner → Bubblewrap sandbox: builds sandbox command (evidence: `src/execution/runner.py`)
- Bubblewrap sandbox → Synthetic API targets: isolates target (evidence: `README.md`)
- Bubblewrap sandbox → Sandbox worker: launches worker (evidence: `README.md`)
- Sandbox worker → Behavioral fuzzer: runs fuzz session (evidence: `src/execution/sandbox_worker.py`)
- Sandbox worker → Authorization probe: runs scenarios (evidence: `src/execution/sandbox_worker.py`)
- Sandbox worker → Benchmark manifest: reads benchmark settings (evidence: `src/execution/sandbox_worker.py`)
- Behavioral fuzzer → Synthetic API targets: sends requests (evidence: `README.md`)
- Behavioral fuzzer → Statistical detector: analyzes responses (evidence: `src/fuzzer.py`)
- Behavioral fuzzer → Fingerprint detector: checks fingerprints (evidence: `src/fuzzer.py`)
- Behavioral fuzzer → Path canary oracle: checks canary token (evidence: `README.md`)
- Sandbox worker → Telemetry events: creates events (evidence: `src/execution/sandbox_worker.py`)
- Sandbox worker → Telemetry writer: appends events (evidence: `src/execution/sandbox_worker.py`)
- Telemetry writer → Telemetry events: serializes events (evidence: `src/telemetry/writer.py`)
- Telemetry writer → Run artifacts: writes telemetry (evidence: `README.md`)
- Benchmark runner → Run artifacts: writes logs and reports (evidence: `src/execution/runner.py`)
- Researcher → Evaluation metrics: evaluates run (evidence: `README.md`)
- Evaluation metrics → Run artifacts: reads telemetry (evidence: `README.md`)
- Evaluation metrics → Verified labels: checks labels (evidence: `README.md`)
- Researcher → Statistical analysis: compares detector modes (evidence: `README.md`)
