Skip to main content

Fuzzing

Overview​

HVE Core uses Atheris fuzz harnesses to satisfy OSSF Scorecard Fuzzing compliance. Each Python skill with a tests/ directory includes a polyglot fuzz_harness.py that runs as both a pytest test and an Atheris coverage-guided fuzz target.

Scorecard Fuzzing Detection​

OSSF Scorecard evaluates fuzzing through a three-phase detection pipeline:

PhaseDetection MethodHVE Core Strategy
1OSSFuzz integrationNot applicable (HVE Core is not a library)
2ClusterFuzzLite YAMLNot applicable (no .clusterfuzzlite/ config)
3Source file regex: import atherisActive: fuzz_harness.py in each Python skill

Phase 3 scans all .py files in the repository for import atheris. A single match satisfies the OSSF Scorecard Fuzzing check, which contributes as one weighted sub-check to the aggregate Scorecard score.

Convention​

Every Python skill with a tests/ directory MUST include:

  1. tests/fuzz_harness.py: polyglot harness with try: import atheris guard
  2. fuzz dependency group in pyproject.toml with atheris>=3.0
  3. python_files config in [tool.pytest.ini_options] including fuzz_harness.py

The validate:skills npm script enforces this convention. Builds fail when a Python skill has tests/ but no fuzz_harness.py.

Running Fuzz Tests​

pytest Mode (CI Default)​

cd .github/skills/experimental/powerpoint
uv run pytest tests/fuzz_harness.py -v

Runs property-based tests without requiring Atheris. This is the default CI path.

Atheris Mode (Local Fuzzing)​

cd .github/skills/experimental/powerpoint
uv sync --group fuzz
uv run python tests/fuzz_harness.py

Runs coverage-guided fuzzing with Atheris. Requires Linux x86_64 (no macOS wheels). Press Ctrl+C to stop.

Adding a Fuzz Harness to a New Skill​

  1. Create tests/fuzz_harness.py following the polyglot pattern from an existing skill
  2. Add fuzz = ["atheris>=3.0"] to [dependency-groups] in pyproject.toml
  3. Add python_files = ["test_*.py", "fuzz_harness.py"] to [tool.pytest.ini_options]
  4. Run npm run validate:skills to verify compliance
  5. Run uv run pytest tests/fuzz_harness.py -v to verify pytest mode passes

Platform Compatibility​

Atheris provides pre-built wheels for Linux x86_64 only. The fuzz dependency group is separate from dev so that uv sync (without --group fuzz) works on all platforms. The harness degrades gracefully: when Atheris is not installed, FUZZING = False and only pytest tests execute.

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.