fuzz

Fuzzing Infrastructure for HyperSpot

This directory contains fuzzing infrastructure using cargo-fuzz and ClusterFuzzLite.

Overview

Continuous fuzzing helps discover:

• Panics and crashes
• Logic bugs in parsers and validators
• Performance issues (algorithmic complexity attacks)

Quick Start

Prerequisites

# Install cargo-fuzz (requires nightly)
cargo install cargo-fuzz

Running Fuzzing Locally

# Build all fuzz targets
make fuzz-build

# Run all targets (smoke test - 30s each)
make fuzz

# Run specific target for longer
make fuzz-run FUZZ_TARGET=fuzz_odata_filter FUZZ_SECONDS=300

# List all available targets
make fuzz-list

Using CI Script

# Build fuzz targets
python scripts/ci.py fuzz-build

# Run smoke tests
python scripts/ci.py fuzz --seconds 60

# Run specific target
python scripts/ci.py fuzz-run fuzz_odata_filter --seconds 300

Fuzz Targets

Target	Priority	Component	Description
fuzz_odata_filter	HIGH	OData parsing	Fuzzes $filter query string parser
fuzz_odata_cursor	HIGH	Pagination	Fuzzes cursor decoder (base64+JSON)
fuzz_yaml_config	HIGH	Configuration	Fuzzes YAML config parser
fuzz_html_parser	MEDIUM	file_parser	Fuzzes HTML document parser
fuzz_pdf_parser	MEDIUM	file_parser	Fuzzes PDF document parser
fuzz_json_config	MEDIUM	Configuration	Fuzzes JSON parser
fuzz_odata_orderby	MEDIUM	OData parsing	Fuzzes $orderby token parser
fuzz_markdown_parser	LOW	file_parser	Fuzzes Markdown parser

Continuous Fuzzing in CI

ClusterFuzzLite runs automatically:

• On Pull Requests: 10 minutes per target
• On main branch: 1 hour per target
• Scheduled (nightly): 1 hour per target

Results are uploaded as artifacts and issues are created automatically.

Reproducing Crashes

If a crash is found:

# Crashes are saved in artifacts/
cd fuzz
cargo fuzz run fuzz_odata_filter artifacts/fuzz_odata_filter/crash-*

Corpus Management

# Minimize corpus (remove redundant inputs)
make fuzz-corpus FUZZ_TARGET=fuzz_odata_filter

# Add seed inputs
echo 'name eq "test"' > corpus/fuzz_odata_filter/my_seed.txt

Best Practices

1. Don't panic on invalid input - use Result types
2. Limit resource usage - add timeouts and size limits
3. Add seed corpus - good inputs speed up fuzzing
4. Run locally before PR - catch issues early

Cleaning Up

# Remove all fuzzing artifacts
make fuzz-clean

# Or using CI script
python scripts/ci.py fuzz-clean

Resources

• cargo-fuzz book
• ClusterFuzzLite docs
• libFuzzer options

Troubleshooting

cargo-fuzz not found

cargo install cargo-fuzz

Nightly toolchain issues

rustup install nightly
# Use +nightly flag with cargo-fuzz commands:
cargo +nightly fuzz run fuzz_odata_filter

Build failures

Make sure all dependencies are available:

cd fuzz
cargo check --all