How yahyatoubali/crashwise works
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: activities Activities · main.py Main flow · client.py Workflow client · synth.py Harness synth
Components 17
Interfaces
Human-facing entrypoints and dashboard UI
Orchestration
Temporal workflows and campaign control plane
- Main flow · Campaign lifecycle orchestration
crashwise/orchestration/workflows/main.py - Activities · Setup, fuzzing, triage, verification, and notifications
crashwise/orchestration/activities - Workflow client · Submits and signals campaigns
crashwise/orchestration/client.py - Worker · Executes workflow activities
crashwise/orchestration/worker.py
AI Agents
Synthesis, research, triage, and reporting subsystems
- Harness synth · AI-assisted fuzz harness generation and evolution
crashwise/agents/harness_synth/synth.py - Coverage loop · Coverage analysis and adaptive strategy updates
crashwise/agents/research/coverage_analyzer.py - Triage · Crash deduplication and exploitability analysis
crashwise/agents/triage/analyzer.py - Feedback · Diagnose failures and patch harnesses
crashwise/agents/feedback/analyzer.py - Reporting · Risk scoring and final reports
crashwise/agents/reporting/generator.py
Runtime
Execution sandboxes and shared infrastructure
- Sandbox exec · Dockerized fuzzers and monitors
crashwise/execution/dispatcher.py - Kernel path · Optional kernel-oriented execution path
crashwise/execution/qemu_manager.py - Core services · Config, database, Redis, storage, logging, notifications
crashwise/core/config.py - Kernel bridge · Kernel-specific parsing and models
crashwise/kernelbridge/parser.py
Connections 20
- 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