john/McRogueFace
1
0
Fork 0
Code Issues 25 Pull requests Projects Releases Wiki Activity

[Major Feature] Coverage-guided fuzz harness for Python API (libFuzzer + ASan) #283

New issue
Closed
opened 2026-03-08 03:19:59 +00:00 by john · 1 comment
john commented 2026-03-08 03:19:59 +00:00
Owner
Copy link

Context

The 7DRL 2026 post-mortem found 22 memory safety bugs, most of which require specific input sequences to trigger (entity cross-grid transfer, holding references across mutations, etc.). The existing test suite exercises normal operation paths and misses these edge cases entirely — ASan found 0 bugs when run against the full test suite, but immediately found the gridstate overflow when given a targeted trigger.

Coverage-guided fuzzing would systematically explore these edge cases.

Proposal

Create tests/fuzz/ with Atheris-based fuzz targets:

  1. Grid/Entity fuzz target: Random sequences of grid creation, entity append/remove/transfer, position changes, visibility updates
  2. Collection fuzz target: Random insert/remove/slice operations on UICollection and UIEntityCollection
  3. Property fuzz target: Random get/set of properties on UI objects with varying types
  4. Animation fuzz target: Random animation creation, callback registration, stepping

Each target creates mcrfpy objects and performs random operations, letting ASan catch any memory corruption.

Prerequisites

  • Clang build (see #282)
  • Atheris pip package
  • ASan-instrumented build (make asan)

Related

  • #258–#278 (the bugs fuzzing should find)
  • #279 (memory safety audit meta-issue)
## Context The 7DRL 2026 post-mortem found 22 memory safety bugs, most of which require specific input sequences to trigger (entity cross-grid transfer, holding references across mutations, etc.). The existing test suite exercises normal operation paths and misses these edge cases entirely — ASan found 0 bugs when run against the full test suite, but immediately found the gridstate overflow when given a targeted trigger. Coverage-guided fuzzing would systematically explore these edge cases. ## Proposal Create `tests/fuzz/` with Atheris-based fuzz targets: 1. **Grid/Entity fuzz target**: Random sequences of grid creation, entity append/remove/transfer, position changes, visibility updates 2. **Collection fuzz target**: Random insert/remove/slice operations on UICollection and UIEntityCollection 3. **Property fuzz target**: Random get/set of properties on UI objects with varying types 4. **Animation fuzz target**: Random animation creation, callback registration, stepping Each target creates mcrfpy objects and performs random operations, letting ASan catch any memory corruption. ## Prerequisites - Clang build (see #282) - Atheris pip package - ASan-instrumented build (`make asan`) ## Related - #258–#278 (the bugs fuzzing should find) - #279 (memory safety audit meta-issue)
john commented 2026-04-17 03:14:59 +00:00
Author
Owner
Copy link

Closing. Resolution: shipped as a native clang+libFuzzer+ASan harness instead of Atheris. Python-level coverage would have added nothing — every bug from #258-#278 lives below the Python/C++ boundary and is reached through normal mcrfpy.* calls. libFuzzer already instruments the C++ engine code and drives input through a byte-consumer that the Python fuzz scripts read from; no atheris dependency was needed.

What shipped

  • make fuzz-build / make fuzz / make fuzz-long / make fuzz-repro (tranche W1)
  • build-fuzz/mcrfpy_fuzz single binary, target chosen by MCRF_FUZZ_TARGET env var (W2/W3)
  • Six Python-driven fuzz targets under tests/fuzz/:
    • fuzz_grid_entity — EntityCollection lifecycle (W4 → closed #258-#263, #273, #274)
    • fuzz_property_types — type confusion on Frame/Caption/Sprite/Entity/Grid/TileLayer/ColorLayer (W5 → closed #267, #268, #272)
    • fuzz_anim_timer_scene — animation/timer/scene lifecycle (W6)
    • fuzz_fov — compute_fov / is_in_fov with enum fuzzing (W8 → surfaced #310)
    • fuzz_maps_procgen — HeightMap/DiscreteMap/NoiseSource/BSP (W7)
    • fuzz_pathfinding_behavior — DijkstraMap, grid.step, entity behavior (W9 → surfaced #311)
  • README at tests/fuzz/README.md with triage workflow

Gaps intentionally left open (flagged for follow-up issues, not this one)

  • Tiled/LDtk import parsers (TileSetFile, TileMapFile, WangSet, LdtkProject, AutoRuleSet)
  • Shader / PropertyBinding / UniformCollection lifecycle
  • Audio DSP chain (SoundBuffer filters)
  • Texture factory methods (from_bytes, composite, hsl_shift)
  • Primitives not yet property-fuzzed (Line, Circle, Arc)

These represent new attack surface rather than gaps in the original proposal.

Closing. Resolution: **shipped as a native clang+libFuzzer+ASan harness instead of Atheris.** Python-level coverage would have added nothing — every bug from #258-#278 lives below the Python/C++ boundary and is reached through normal `mcrfpy.*` calls. libFuzzer already instruments the C++ engine code and drives input through a byte-consumer that the Python fuzz scripts read from; no `atheris` dependency was needed. ### What shipped - `make fuzz-build` / `make fuzz` / `make fuzz-long` / `make fuzz-repro` (tranche W1) - `build-fuzz/mcrfpy_fuzz` single binary, target chosen by `MCRF_FUZZ_TARGET` env var (W2/W3) - Six Python-driven fuzz targets under `tests/fuzz/`: - `fuzz_grid_entity` — EntityCollection lifecycle (W4 → closed #258-#263, #273, #274) - `fuzz_property_types` — type confusion on Frame/Caption/Sprite/Entity/Grid/TileLayer/ColorLayer (W5 → closed #267, #268, #272) - `fuzz_anim_timer_scene` — animation/timer/scene lifecycle (W6) - `fuzz_fov` — `compute_fov` / `is_in_fov` with enum fuzzing (W8 → surfaced #310) - `fuzz_maps_procgen` — HeightMap/DiscreteMap/NoiseSource/BSP (W7) - `fuzz_pathfinding_behavior` — DijkstraMap, `grid.step`, entity behavior (W9 → surfaced #311) - README at `tests/fuzz/README.md` with triage workflow ### Gaps intentionally left open (flagged for follow-up issues, not this one) - Tiled/LDtk import parsers (TileSetFile, TileMapFile, WangSet, LdtkProject, AutoRuleSet) - Shader / PropertyBinding / UniformCollection lifecycle - Audio DSP chain (SoundBuffer filters) - Texture factory methods (`from_bytes`, `composite`, `hsl_shift`) - Primitives not yet property-fuzzed (Line, Circle, Arc) These represent new attack surface rather than gaps in the original proposal.
john changed title from [Major Feature] Atheris coverage-guided fuzzing harness for Python API to [Major Feature] Coverage-guided fuzz harness for Python API (libFuzzer + ASan) 2026-04-17 03:15:00 +00:00
john closed this issue 2026-04-17 03:15:00 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
master
threedee
emscripten-mcrogueface
rogueliketutorial25
alpha_presentable
alpha_streamline_2
alpha_streamline_1
interpreter_mode
grid_entity_integration
reprs_and_member_names
break_up_ui_h
standardize_font_handling
standardize_vector_handling
standardize_color_handling
standardize_texture_handling
raii_pyobjects
rebase-for-7DRL_Feb-2024
engjam_uicollection
engjam_ui_overhaul
0.2.3-prerelease-7drl2026-emscripten
Labels
Clear labels   
Alpha Release Requirement

This issue is a blocker to 0.1 Alpha release of McRogueFace.

  
Bugfix

   
Demo Target

Functionality to demonstrate; Depends on new features, but this issue isn't for writing them.

  
Documentation

   
Major Feature

Significant time and effort required.

  
Minor Feature

Some effort required to create or overhaul functionality.

  
priority:tier1-active

Current development focus - critical path to v1.0

  
priority:tier2-foundation

Important foundation work - not blocking v1.0

  
priority:tier3-future

Future features - deferred until after v1.0

  
priority:tier4-deferred

   
Refactoring & Cleanup

no new functionality, just improving the codebase.

  
system:animation

Animation and property interpolation

  
system:documentation

Documentation infrastructure

  
system:grid

Grid system and spatial containers

  
system:input

Input handling and events

  
system:performance

Performance optimization and profiling

  
system:procgen

Procedural Generation (Noise, BSP, Heightmap)

  
system:python-binding

Python/C++ binding layer

  
system:rendering

Rendering pipeline and visuals

  
system:ui-hierarchy

UI component hierarchy and composition

  
Tiny Feature

quick and easy - a few lines or with little interconnection around the codebase

  
workflow:blocked

Blocked by other work - waiting on dependencies

  
workflow:needs-benchmark

Needs performance testing and benchmarks

  
workflow:needs-documentation

Needs documentation before or after implementation

No labels
Alpha Release Requirement
Bugfix
Demo Target
Documentation
Major Feature
Minor Feature
priority:tier1-active
priority:tier2-foundation
priority:tier3-future
priority:tier4-deferred
Refactoring & Cleanup
system:animation
system:documentation
system:grid
system:input
system:performance
system:procgen
system:python-binding
system:rendering
system:ui-hierarchy
Tiny Feature
workflow:blocked
workflow:needs-benchmark
workflow:needs-documentation
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
john/McRogueFace#283
No description provided.