# yahyatoubali/crashwise architecture

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

- Interactive diagram: https://gitdiagram.com/yahyatoubali/crashwise
- Repository: https://github.com/yahyatoubali/crashwise

## Overview

1. **Purpose and top-level shape**  
   CrashWise is a Python 3.11+ system for automated vulnerability discovery in C/C++ codebases. The repository is organized as a pipeline engine rather than a single app: it clones a target repo, builds it with sanitizers and coverage flags, synthesizes a fuzz harness, runs fuzzers in isolation, triages crashes, and produces reports.

2. **Primary entrypoints**  
   There are three human-facing entrypoints: the **CLI** (`crashwise/cli.py`), the **API** (`crashwise/api/main.py`), and the **dashboard** (`crashwise/dashboard/app.py` plus the frontend in `crashwise/web/frontend`). These all sit above the orchestration layer and are used to submit campaigns, inspect state, and send control signals.

3. **Orchestration is the central control plane**  
   The core runtime is **Temporal-based**. The `crashwise/orchestration` package defines the main workflow and the activity graph that drives the campaign lifecycle. This is the boundary where long-running, retryable, distributed work is split into discrete steps like setup, profiling, fuzz execution, triage, verification, and notification.

4. **Campaign workflow pipeline**  
   The main data flow follows the README pipeline: **clone → build → harness synthesis → fuzz → triage → report**, with a self-correction loop around harness generation and fuzzing. The workflow package contains activities for each stage, including seeding the corpus, injecting seeds, mutating or hot-swapping harnesses, analyzing coverage, verifying patches/PoCs, and updating campaign state.

5. **Harness synthesis subsystem**  
   `crashwise/agents/harness_synth` is a dedicated AI-assisted subsystem for generating `LLVMFuzzerTestOneInput` harnesses. It statically inspects headers, resolves typedefs and struct types, scores candidate entry points, builds a LangGraph state machine, and uses an LLM to generate/validate/retry harness code. This subsystem is the boundary between source-code understanding and executable fuzz input generation.

6. **Coverage and feedback loop**  
   `crashwise/agents/research` and `crashwise/agents/harness_synth/coverage-related pieces` implement the feedback loop that makes fuzzing adaptive. Coverage data is read and transformed into blocker diagnoses such as magic values, length checks, checksums, or state-machine gates. That analysis feeds dictionary generation, harness rewrites, and strategy pivots when fuzzing plateaus.

7. **Execution sandboxes**  
   Actual fuzzing runs are isolated in the `crashwise/execution` layer, which manages Docker-based sandboxes and monitors execution. AFL++ and libFuzzer are the main fuzzers, and the codebase also includes QEMU/KVM support for kernel-oriented targets. The execution boundary is important: the campaign logic lives outside the sandbox, while fuzzer processes run with restricted filesystem, network, and capability settings.

8. **Crash triage and exploitability analysis**  
   `crashwise/agents/triage` and `crashwise/agents/feedback` handle crash understanding after execution. The triage layer deduplicates crashes by stack hash, classifies them, and estimates exploitability. The feedback layer can use backtraces and analysis output to diagnose harness failures or crashes and route fixes back into the synthesis loop.

9. **Reporting and risk scoring**  
   `crashwise/agents/reporting` turns triage outcomes into final findings, including CVSS-oriented scoring. This is the output boundary of the system: it converts raw fuzzing/crash data into human-consumable vulnerability reports and campaign summaries.

10. **Target discovery and repository analysis**  
   The `crashwise/core`, `crashwise/research`, and `crashwise/kernelbridge` packages support target onboarding and target-specific inspection. Core utilities cover configuration, discovery, manifests, logging, storage, Redis, and database access. Kernelbridge indicates a separate parsing/model path for kernel-style targets, distinct from normal user-space libraries.

11. **State, persistence, and distributed coordination**  
   CrashWise persists campaign state through multiple stores: **PostgreSQL or SQLite** via SQLAlchemy, **Redis** for coordination/distributed state, and **object storage** (R2/S3-style) for artifacts. Temporal provides workflow durability and retries, while the `core` package centralizes access to config, database, Redis, storage, and notifications.

12. **AI provider boundary**  
   The repository separates LLM usage into configurable providers. Harness synthesis uses a configured `CRASHWISE_LLM_MODEL`, while crash triage can use backends like Ollama, OpenAI-compatible endpoints, or other supported providers. This keeps model access behind `crashwise/core/ai_provider.py` and the agent packages rather than spreading provider-specific logic across the codebase.

13. **Operational interfaces and control signals**  
   The system supports live campaign control through workflow signals such as pause, force pivot, and seed injection. That means the orchestration layer is not just batch execution; it is an interactive control plane for long-running fuzzing campaigns.

14. **Repo layout and test boundaries**  
   The `tests/unit` suite is broad and maps closely to the subsystems: compiler, execution, triage, reporting, workflow, Redis, database, kernelbridge, and harness evolution. The presence of `infra/temporal`, Dockerfiles, and `docker-compose.yaml` shows the repo is designed to run as a distributed service stack, not as a single-process library.

15. **What to emphasize in an architecture diagram**  
   The most important diagram boundaries are:  
   - external user interfaces: CLI, API, dashboard  
   - orchestration control plane: Temporal workflows + activities  
   - AI/agent layer: synthesis, research, triage, reporting  
   - execution sandbox: Dockerized fuzzers and optional kernel execution path  
   - persistence layer: database, Redis, object storage  
   - external dependencies: target Git repos, LLM providers, and fuzzing tooling

Main entry points: [`crashwise/orchestration/activities`](https://github.com/yahyatoubali/crashwise/tree/master/crashwise/orchestration/activities) (Activities), [`crashwise/orchestration/workflows/main.py`](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/workflows/main.py) (Main flow), [`crashwise/orchestration/client.py`](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/client.py) (Workflow client), [`crashwise/agents/harness_synth/synth.py`](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/harness_synth/synth.py) (Harness synth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_api["API<br/>entrypoint<br/>[main.py]"]
  node_dashboard["Dashboard<br/>entrypoint<br/>[app.py]"]
  node_frontend["Frontend<br/>ui<br/>[page.tsx]"]
end

subgraph group_control["Orchestration"]
  node_workflow{{"Main flow<br/>temporal workflow<br/>[main.py]"}}
  node_activities["Activities<br/>workflow steps"]
  node_client["Workflow client<br/>temporal client<br/>[client.py]"]
  node_worker["Worker<br/>[worker.py]"]
end

subgraph group_agents["AI Agents"]
  node_harness{{"Harness synth<br/>agent subsystem<br/>[synth.py]"}}
  node_coverage["Coverage loop<br/>feedback analysis"]
  node_triage["Triage<br/>crash analysis<br/>[analyzer.py]"]
  node_feedback["Feedback<br/>repair loop<br/>[analyzer.py]"]
  node_reporting["Reporting<br/>finding synthesis<br/>[generator.py]"]
end

subgraph group_runtime["Runtime"]
  node_execution[("Sandbox exec<br/>fuzz runtime<br/>[dispatcher.py]")]
  node_qemu["Kernel path<br/>qemu/kvm runtime<br/>[qemu_manager.py]"]
  node_core["Core services<br/>shared infra<br/>[config.py]"]
  node_kernelbridge["Kernel bridge<br/>target model<br/>[parser.py]"]
end

node_cli -->|"submit/signal"| node_client
node_api -->|"control"| node_client
node_dashboard -->|"serve data"| node_api
node_frontend -->|"ui"| node_dashboard
node_client -->|"start"| node_workflow
node_worker -->|"run"| node_activities
node_workflow -->|"step through"| node_activities
node_activities -->|"state"| node_core
node_activities -->|"synthesize"| node_harness
node_activities -->|"fuzz"| node_execution
node_activities -->|"analyze crashes"| node_triage
node_activities -->|"analyze coverage"| node_coverage
node_activities -->|"repair loop"| node_feedback
node_activities -->|"report"| node_reporting
node_execution -.->|"optional"| node_qemu
node_harness -->|"adapt"| node_coverage
node_triage -->|"findings"| node_reporting
node_feedback -->|"revise"| node_harness
node_kernelbridge -.->|"target model"| node_qemu
node_core -.->|"durable state"| node_workflow

click node_cli "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/cli.py"
click node_api "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/api/main.py"
click node_dashboard "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/dashboard/app.py"
click node_frontend "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/web/frontend/app/page.tsx"
click node_workflow "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/workflows/main.py"
click node_activities "https://github.com/yahyatoubali/crashwise/tree/master/crashwise/orchestration/activities"
click node_client "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/client.py"
click node_worker "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/worker.py"
click node_harness "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/harness_synth/synth.py"
click node_coverage "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/research/coverage_analyzer.py"
click node_triage "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/triage/analyzer.py"
click node_feedback "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/feedback/analyzer.py"
click node_reporting "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/reporting/generator.py"
click node_execution "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/execution/dispatcher.py"
click node_qemu "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/execution/qemu_manager.py"
click node_core "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/core/config.py"
click node_kernelbridge "https://github.com/yahyatoubali/crashwise/blob/master/crashwise/kernelbridge/parser.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_api,node_dashboard,node_frontend toneBlue
class node_workflow,node_activities,node_client,node_worker toneAmber
class node_harness,node_coverage,node_triage,node_feedback,node_reporting toneMint
class node_execution,node_qemu,node_core,node_kernelbridge toneRose
```

## Components

### Interfaces

Human-facing entrypoints and dashboard UI

- [CLI](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/cli.py): entrypoint · Command-line campaign control · `crashwise/cli.py`
- [API](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/api/main.py): entrypoint · HTTP control API · `crashwise/api/main.py`
- [Dashboard](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/dashboard/app.py): entrypoint · Web dashboard backend · `crashwise/dashboard/app.py`
- [Frontend](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/web/frontend/app/page.tsx): ui · Campaign and crash UI · `crashwise/web/frontend/app/page.tsx`

### Orchestration

Temporal workflows and campaign control plane

- [Main flow](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/workflows/main.py): temporal workflow · Campaign lifecycle orchestration · `crashwise/orchestration/workflows/main.py`
- [Activities](https://github.com/yahyatoubali/crashwise/tree/master/crashwise/orchestration/activities): workflow steps · Setup, fuzzing, triage, verification, and notifications · `crashwise/orchestration/activities`
- [Workflow client](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/client.py): temporal client · Submits and signals campaigns · `crashwise/orchestration/client.py`
- [Worker](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/orchestration/worker.py): temporal worker · Executes workflow activities · `crashwise/orchestration/worker.py`

### AI Agents

Synthesis, research, triage, and reporting subsystems

- [Harness synth](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/harness_synth/synth.py): agent subsystem · AI-assisted fuzz harness generation and evolution · `crashwise/agents/harness_synth/synth.py`
- [Coverage loop](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/research/coverage_analyzer.py): feedback analysis · Coverage analysis and adaptive strategy updates · `crashwise/agents/research/coverage_analyzer.py`
- [Triage](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/triage/analyzer.py): crash analysis · Crash deduplication and exploitability analysis · `crashwise/agents/triage/analyzer.py`
- [Feedback](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/feedback/analyzer.py): repair loop · Diagnose failures and patch harnesses · `crashwise/agents/feedback/analyzer.py`
- [Reporting](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/agents/reporting/generator.py): finding synthesis · Risk scoring and final reports · `crashwise/agents/reporting/generator.py`

### Runtime

Execution sandboxes and shared infrastructure

- [Sandbox exec](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/execution/dispatcher.py): fuzz runtime · Dockerized fuzzers and monitors · `crashwise/execution/dispatcher.py`
- [Kernel path](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/execution/qemu_manager.py): qemu/kvm runtime · Optional kernel-oriented execution path · `crashwise/execution/qemu_manager.py`
- [Core services](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/core/config.py): shared infra · Config, database, Redis, storage, logging, notifications · `crashwise/core/config.py`
- [Kernel bridge](https://github.com/yahyatoubali/crashwise/blob/master/crashwise/kernelbridge/parser.py): target model · Kernel-specific parsing and models · `crashwise/kernelbridge/parser.py`

## Connections

- CLI → Workflow client: submit/signal · CLI drives campaigns through the workflow client
- API → Workflow client: control · API submits and controls campaigns
- Dashboard → API: serve data · Dashboard surfaces campaign state through backend services
- Frontend → Dashboard: ui · Frontend consumes dashboard/backend data
- Workflow client → Main flow: start · Creates and signals Temporal workflows
- Worker → Activities: run · Worker executes activity implementations
- Main flow → Activities: step through · Workflow decomposes the campaign into discrete steps
- Activities → Core services: state · Activities use shared config, storage, database, Redis, and notifications
- Activities → Harness synth: synthesize · Activities invoke harness generation and evolution
- Activities → Sandbox exec: fuzz · Activities dispatch isolated fuzzing jobs
- Activities → Triage: analyze crashes · Activities triage results after execution
- Activities → Coverage loop: analyze coverage · Activities read and transform coverage data
- Activities → Feedback: repair loop · Activities feed failures back into harness correction
- Activities → Reporting: report · Activities generate final findings and summaries
- Sandbox exec → Kernel path: optional · Kernel targets can use the QEMU/KVM path
- Harness synth → Coverage loop: adapt · Coverage feedback changes harness strategy
- Triage → Reporting: findings · Triage outcomes become reported vulnerabilities
- Feedback → Harness synth: revise · Harness failures and crashes trigger synthesis fixes
- Kernel bridge → Kernel path: target model · Kernel parsing supports specialized execution and analysis
- Core services → Main flow: durable state · Workflow uses persistence and coordination services
