# Fuzz

Run and manage FalkorDB's cargo-fuzz pipeline for the query runtime...

- Repository: https://github.com/FalkorDB/FalkorDB (10505 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add FalkorDB/FalkorDB --skill fuzz -g -a claude-code -y`
Codex: `npx skills add FalkorDB/FalkorDB --skill fuzz -g -a codex -y`
Cursor: `npx skills add FalkorDB/FalkorDB --skill fuzz -g -a cursor -y`
Gemini CLI: `npx skills add FalkorDB/FalkorDB --skill fuzz -g -a gemini-cli -y`

## Description

Run and manage FalkorDB's cargo-fuzz pipeline for the query runtime (fuzz_target_runtime) - build the fuzz target, run/minimize the corpus, generate coverage, and reproduce a crash artifact. Use when asked to fuzz test the runtime, investigate a fuzzing crash/artifact, or update the fuzz corpus.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Fuzz

The fuzz target lives in `fuzz/` (crate `graph-fuzz`, binary
`fuzz_target_runtime`, fuzzing `graph`'s query runtime). `fuzz.sh` runs the
full local sequence below end-to-end.

## 1. Toolchain setup (one-time / per environment)

`cargo-fuzz` requires the nightly toolchain plus LLVM tools:

```bash
rustup default nightly
rustup component add llvm-tools-preview
cargo install cargo-fuzz --version <CARGO_FUZZ_VERSION> --locked
```
Check the currently-pinned `CARGO_FUZZ_VERSION` in `.github/workflows/rust-pr.yml`
so your local `cargo-fuzz` matches CI.

## 2. Build

```bash
cargo build --features fuzz
```

## 3. Seed the corpus

The corpus is seeded from the TCK test run (it generates a wide variety of
valid Cypher queries/inputs):

```bash
mkdir -p fuzz/corpus/fuzz_target_runtime/
source venv/bin/activate 2>/dev/null || source /data/venv/bin/activate   # pytest deps (/data/venv in devcontainer/CI)
TCK_DONE=tck_done.txt pytest tests/tck/test_tck.py -s
```

## 4. Run / minimize / cover

On Linux, first export the RediSearch link workaround CI uses, so the embedded
static libs link without duplicate-symbol errors (not needed / not a valid
flag with macOS's linker):
```bash
export RUSTFLAGS="-C link-arg=-Wl,--allow-multiple-definition"   # Linux/CI only

CXX=clang++ CARGO_PROFILE_RELEASE_LTO=false cargo fuzz run fuzz_target_runtime -- -max_total_time=<seconds>
CXX=clang++ CARGO_PROFILE_RELEASE_LTO=false cargo fuzz cmin fuzz_target_runtime      # minimize the corpus
CXX=clang++ CARGO_PROFILE_RELEASE_LTO=false cargo fuzz coverage fuzz_target_runtime  # generate coverage data
```
Then render an HTML coverage report. Resolve `llvm-cov` from the active Rust
toolchain (via `llvm-tools-preview`) rather than a system one, exactly as CI
does, to avoid version skew; the target triple differs by OS:
```bash
LLVM_COV=$(find "$(rustc --print sysroot)" -name llvm-cov -type f | head -1)

The rest: https://github.com/FalkorDB/FalkorDB/blob/HEAD/.claude/skills/fuzz/SKILL.md