# Fuzzing Strategy

This document explains our fuzzing approach and addresses OSSF Scorecard's
Fuzzing check.

## Current Implementation

This project uses **Hypothesis** for property-based fuzz testing:

- **Workflow**: `.github/workflows/fuzz.yml`
- **Tests**: `tests/fuzz/test_fuzz_security.py`, `tests/fuzz/test_fuzz_utilities.py`
- **Schedule**: Weekly on Sunday + on changes to security/utilities code

### What We Test

Our fuzz tests cover:
- Input validation edge cases
- Security-sensitive string handling
- API boundary testing
- File path validation
- URL parsing and sanitization

### Test Configuration

```yaml
# Regular CI runs
--hypothesis-seed=0  # Reproducible tests

# Extended scheduled runs
HYPOTHESIS_PROFILE=extended  # More examples, deeper exploration
```

## Why Not OSS-Fuzz?

OSSF Scorecard's Fuzzing check looks for integration with:
- [OSS-Fuzz](https://github.com/google/oss-fuzz) - Google's continuous fuzzing
- [ClusterFuzzLite](https://google.github.io/clusterfuzzlite/) - Lightweight alternative
- [OneFuzz](https://github.com/microsoft/onefuzz) - Microsoft's fuzzing platform

**These are not appropriate for this project because:**

1. **OSS-Fuzz targets native code** - Designed for C/C++ vulnerabilities using
   libFuzzer/AFL++. This project is primarily Python.

2. **Hypothesis is the Python equivalent** - Property-based testing with
   automatic example generation provides equivalent security value.

3. **No native code attack surface** - Our security-sensitive code is Python,
   where Hypothesis testing is the standard approach.

## OSSF Scorecard Note

Scorecard's "Fuzzing" check does not recognize Hypothesis-based testing.
This is a known limitation of the check. Our fuzzing implementation provides
equivalent security value for Python codebases.

## Future Considerations

If the project adds significant native code dependencies (C extensions, FFI),
we would consider:
- ClusterFuzzLite integration for continuous fuzzing
- Native fuzz targets for critical C code paths

## References

- [Hypothesis Documentation](https://hypothesis.readthedocs.io/)
- [OSSF Scorecard Fuzzing Check](https://github.com/ossf/scorecard/blob/main/docs/checks.md#fuzzing)
- [Property-Based Testing in Python](https://hypothesis.works/)
