Fuzzing & Security

Relevant source files

The following files were used as context for generating this wiki page:

• fuzz/FUZZING_STRATEGY.md
• fuzz/CORPUS_METHODOLOGY.md
• fuzz/fuzz_targets/hnsw_config/target.rs
• CONTRIBUTING.md
• fuzz/Cargo.toml
• GATE_1_COMPLETE.md

Introduction

Fuzzing is a mandatory quality gate for EdgeVec, designed to ensure the stability and security of critical components, particularly the binary quantization and HNSW indexing modules. The primary purpose of the fuzzing strategy is to guarantee panic-freedom, memory safety, and mathematical invariant preservation across all security-sensitive operations.

Within the project context, fuzzing serves as a "Nvidia Grade" verification layer, catching edge cases such as buffer overflows, out-of-bounds (OOB) access, and non-deterministic behavior that standard unit tests might miss. It is integrated directly into the CI pipeline and local development workflows to provide continuous protection against regressions.
Sources: fuzz/FUZZING_STRATEGY.md:10-20, CONTRIBUTING.md:214-230

Fuzzing Architecture and Strategy

The EdgeVec fuzzing infrastructure is built using cargo-fuzz and libfuzzer-sys, leveraging the arbitrary crate to generate structured inputs for complex data types. The system is organized into a corpus-based hierarchy where each target resides in its own subdirectory.

Key Performance Goals

Goal	Target	Metric
Panic-freedom	100%	No panics on valid/invalid input
Memory safety	100%	No buffer overflows, OOB access
Determinism	100%	Same input always produces same output
Invariant preservation	100%	All mathematical invariants hold
Sources: fuzz/FUZZING_STRATEGY.md:14-24, fuzz/Cargo.toml:15-20

Fuzzing Lifecycle

The following diagram illustrates the flow from seed generation to bug triage in the EdgeVec ecosystem:

The fuzzer continuously mutates inputs from the corpus to find new code paths and potential crashes.
Sources: fuzz/FUZZING_STRATEGY.md:195-205, fuzz/CORPUS_METHODOLOGY.md:10-25

Fuzz Targets & Components

EdgeVec implements multiple specialized fuzz targets to exercise different layers of the vector engine.

Core Targets

• fuzz_quantization: Verifies binary quantization logic, testing for NaN handling, subnormal numbers, and symmetry in Hamming distance calculations.
• hnsw_config: Fuzzes the HnswConfig and HnswIndex::new constructors by providing arbitrary byte sequences interpreted as configuration parameters (m, ef_construction, dimensions).
• hnsw_insert & hnsw_search: Tests the core graph operations for search complexity invariants and sorted results.
• wal_replay: Validates the Write-Ahead Log iterator against corrupted or truncated data to ensure the persistence layer never panics.
  Sources: fuzz/FUZZING_STRATEGY.md:28-45, fuzz/fuzz_targets/hnsw_config/target.rs:7-30

Configuration Fuzzing Logic

The hnsw_config target specifically interprets raw data to validate the index constructor:

fuzz_target!(|data: &[u8]| {
    if data.len() < 20 { return; }
    let m = u32::from_le_bytes(data[0..4].try_into().unwrap());
    let dimensions = u32::from_le_bytes(data[16..20].try_into().unwrap());
    
    let mut config = HnswConfig::new(dimensions);
    config.m = m;
    
    let storage = VectorStorage::new(&config, None);
    let result = HnswIndex::new(config, &storage);
    // Panics here are considered P0/P1 bugs
});

Sources: fuzz/fuzz_targets/hnsw_config/target.rs:7-35

Corpus Methodology

A well-crafted seed corpus is critical for fuzzing effectiveness. EdgeVec uses a structured methodology to generate initial seeds that cover known boundary conditions.

Seed Categories

Category	Purpose
Special Floats	Test NaN, Infinity, and subnormal handling
Boundary Patterns	Test bit-packing logic and byte boundaries
Malformed Data	Specifically target error-handling code paths
Dense Clusters	Test HNSW graph navigation in similar vector spaces
Sources: fuzz/FUZZING_STRATEGY.md:162-175, fuzz/CORPUS_METHODOLOGY.md:120-135

The relationship between targets, their verifiers, and the underlying corpus.
Sources: fuzz/FUZZING_STRATEGY.md:28-60, fuzz/CORPUS_METHODOLOGY.md:165-175

Security Standards & Verification

EdgeVec adheres to the "Nvidia Grade" verification protocol, where correctness is paramount.

Forbidden Security Patterns

• unwrap() in Library Code: Never allowed in public APIs or persistence logic. All fallible operations must return Result.
• Unsafe without Proof: Every unsafe block requires a documented safety proof and a reference to the review that approved it.
• Panic in Public APIs: Invariants must be checked via validation, not assert! or panic!.
  Sources: CONTRIBUTING.md:65-105

Bug Severity Classification

Severity	Description
P0 Critical	Memory unsafety (Buffer overflow, Use-after-free)
P1 High	Panic in production code (Unwrap on None)
P2 Medium	Invariant violation (Wrong distance calculation)
P3 Low	Performance issues (Unexpected O(n²) behavior)
Sources: fuzz/FUZZING_STRATEGY.md:215-225

Execution and CI Integration

Fuzzing is automated locally and in CI to ensure constant coverage.

Local Command Suite

# Run quantization fuzzer for 5 minutes
cargo +nightly fuzz run fuzz_quantization -- -max_total_time=300

# Minimize a crash artifact
cargo +nightly fuzz tmin fuzz_quantization artifacts/crash_id

# Generate coverage report
cargo +nightly fuzz coverage fuzz_quantization

Sources: fuzz/FUZZING_STRATEGY.md:180-195

Fuzz tests are scheduled to run daily at midnight via GitHub Actions and triggered on every push that modifies the quantization or fuzzing modules.
Sources: fuzz/FUZZING_STRATEGY.md:200-210

Conclusion

Fuzzing and security at EdgeVec are not reactive measures but proactive architectural pillars. By combining structured corpus generation, mandatory panic-freedom targets, and a strict "no unwrap" policy, the project ensures that the vector engine remains robust against both accidental corruption and adversarial inputs. The continuous expansion of targets to include SIMD and SQ8 operations reflects a commitment to maintaining these safety standards as the project scales.
Sources: fuzz/FUZZING_STRATEGY.md:245-255, CONTRIBUTING.md:275-285