fuzzer: Instructions file for Codex

AGENTS.md — fuzzer-tool

Coverage-guided binary fuzzer: ASAN/MSAN/TSAN/UBSAN detection, dictionary mutations, Markov chain generation, Monte Carlo optimization, format-aware grammar mutations, and state persistence. CLI tool that fuzzes arbitrary binaries (see fuzzer-tool --help).

The fuzzer executes attacker-controlled input against instrumented targets and parses the targets' own binaries — any bug in this tool's parsing/process code is a bug in the fuzzer, not just the target.

References (read on demand)

Hard Rules

1. Always make surgical changes.
2. Always follow existing conventions. Before adding anything — a target, a script, a scheduler, a test fixture — find the closest existing example and match it: directory layout, file naming, function shape, flag names, error handling, comment style. Read the surrounding code first; do not invent a parallel way of doing something the repo already does. Concretely:
   • Vendored library sources go in $FUZZ_VENDOR_ROOT/<lib>/ (default ~/fuzzing/vendoring/<lib>/, legacy vendor/<lib>/ via --in-tree-vendor), fetched by a tools/vendor_<lib>.sh script. Never commit them; never put them under the build root ($FUZZ_BUILD_ROOT/<lib>/, default ~/fuzzing/builds/, legacy targets/ via --in-tree-targets).
   • New fuzz targets are wired into tools/build_targets.sh rather than built by hand.
   • New schedulers register in _OPERATOR_STRATEGY_NAMES and follow the select_op/record/bandit_stats interface.
   • If a convention appears wrong, fix it in one place for everything rather than working around it locally, and say so.
3. Never bypass the pre-commit hooks (--no-verify). Fix the warnings, then recommit.
4. Always fix impactguard breaking changes.
5. Always use clang, never gcc (build scripts prefer clang automatically).
6. Stop suggesting use_direct_lite = False to work around ASAN in direct_lite mode — debug the root cause instead.
7. Never commit binary files or corpus directories — build targets from source, keep corpus data local.
8. Before deleting code, find where it should be wired first; if not found, clean up. When removing code, stay strictly within the scope of the removal — do not remove unrelated code.
9. Do not nuke the repo.
10. All fuzz targets: compile with ASAN (-fsanitize=address) and AFL edge coverage via afl_shim.c (-include src/fuzzer_tool/adapters/afl_shim.c). Pre-compile library sources as .o files; link the shim only into the target wrapper.
11. Always create TODOs. Always commit and push after finishing a task.
12. Update docs/DEEP_DIVE.md with new features (the comprehensive reference). Update README.md only when adding or changing high-level capabilities visible in the quick-start or feature overview.
13. Op mutators have a single source of truth: src/fuzzer_tool/core/operator_registry.py's REGISTRY. Register new operators there only — the dispatch table (build_dispatch), the per-input op list (build_ops), scheduler arming (_register_arms), and OPERATOR_CATEGORIES all derive from it. Never add operator names to the legacy MUTATIONS/FORMAT_MUTATIONS/DICT_MUTATIONS lists or hand-edit OPERATOR_CATEGORIES; schedulers discover ops through the services layer and never hardcode op lists.
14. Only run the full pytest suite if a file in the codebase was modified.
15. Always after developing a new function and verify its correctness try to vectorize it after the fact, keep the fastest version.
16. Always use the existing pickle machinery, avoid json.
17. For random always use the prng in src/fuzzer_tool/core/rand_pool.py.
18. Do not create artifacts in the source codebase dir.
19. Always create corpus on ~/.
20. Always make sure a new functionality is wired up where needed.
21. try except pass is a bad pattern.
22. Always exercise hygiene: every test must clean up their mess.
23. If you solved the halting problem you are allowed to run tests that the user is saying they are hanging otherwise read the code to see what it does.
24. For every new functionality always add one falsification test and one adversarial test.
25. Always use subagents for multiple file exploring or long tasks.
26. Without any question when the user instructs you to git and commit now, you obey, create the commit message, commit and push. no questions asked and no deliberation.
27. When writing something intended for human consumption, (comment, commit message, reply to prompt) use as few words as possible. Pick every word meticulously to reduce the volume to a strict minimum. Be down to the point. Less is more.
28. Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.
29. Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums. Keep self-explanatory, one-off values inline to avoid clutter. If a value comes from a spec (e.g. HTTP 200 OK), use a constant regardless.
30. Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.
31. Keep function names short. Less than 30 characters.
32. Use enums instead of booleans for function parameters.
33. Let the reader of the code breathe. Add empty lines between logical blocks of code.
34. Add a small, to the point, comment to explain what the block does and why. Use examples when possible. Propose ASCII drawings to explain complete systems.
35. Treat member visibility changes as a breaking design shift. Keep all fields and functions private unless external access is strictly required by the design. Prompt the user for explicit approval before changing any access modifier from private to internal or public.
36. Program to levels of abstraction. Lower-level mechanics must be encapsulated in a dedicated driver/abstraction layer. Expose clean, high-level APIs to the rest of the application so calling code works with domain concepts, not raw implementation details. 36a. Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature. 36b. Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer).
37. If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.
38. When implementing a new feature don't write it right away. First write the test. Observe it failing. Then write the feature. And observe the test passing (Test driven development).
39. No retry-until-random-hit loops in tests (for _ in range(N): if cond: break/found=True). This tests luck, not behavior — it can pass while the code is broken and fails unreproducibly when it doesn't.
    • Inject a scripted/fake RNG that deterministically drives the exact call sequence and assert the exact output.
    • See docs/refs/bug-classes.md §Testing.
40. Every scheduler armed through _register_arms (src/fuzzer_tool/services/fuzzer.py) must declare an explicit class-level supports_priors bool: True only when its init_arm() accepts an informative (prior_alpha, prior_beta) override. _register_arms gates priors behind getattr(scheduler, "supports_priors", False), so a scheduler that omits the flag silently discards format-operator priors instead of failing loudly. Declare it directly after the class docstring with a one-line reason, following op_monte_carlo.py / op_exp3.py.
41. Always check that the new features implemented or bug fixes do not introduce speed penalty regressions.
42. When implementing new features always think of edge cases for the tests.
43. Always maintain succinct, brief, down to the point and updated documentation.
44. When adding, removing or wiring a new subsystem update architecture.png.
45. Every time a new source file.py is created run lizard --CCN=15 file.py and fix warnings.
46. Always run the control against itself; it's what exposes a broken oracle. Whenever a test compares an implementation against a reference — two samples, two policies, old code as oracle — also compare the reference against a second run of itself, and assert that control passes first. A control that fails means the comparison is wrong, not the code.
    • Measured here: comparing two Thompson selection policies with stats.chisquare(obs, exp) treats one sample's counts as fixed frequencies, halves the variance and roughly doubles chi2. It reported chi2=526 on 264 arms (df 264, p=0.0000) for two implementations that were in fact identical.
    • The control run under the correct stats.chi2_contingency gives p=0.74. The tell was the ~2x ratio to the degrees of freedom, and only the self-comparison surfaces it.
    • See tests/test_seed_quality_beta_identity.py::test_matches_betavariate_in_distribution.
    • This is the statistical sibling of Hard Rule 39: an oracle that cannot fail on identical inputs is not an oracle.
47. Always do git commit and push after tests pass do not run tests after git commit and push.
48. When planning to add new features: add code sketches and always add a section with the fully wiring the new feature.
49. When planning a new feature always reason over small targeted code tests, copy the function to test and test it.
50. The full pytest battery is over 14k tests, running it is unpractical, always run the tests for the affected code.
51. Whenever any method from scipy, sympy or gmpy is needed implement it by ourselves instead of importing more libraries.
52. Always run calibrations against fuzzgoat target and make sure it's built with clang.
53. For every layout update in afl_shim.c then increment __AFL_SHM_LAYOUT +1.
54. Always keep memory usage bounded.
55. For cleanliness and maintainability: A big class with a lot of members and reentrancy is preferable than a big procedure.
56. Always rebuild targets if afl_shim.c changes.
57. Push ifs up, fors down wherever possible.
    • Ifs up: decide flags, modes and feature availability once (setup, per run or per exec) and bind the result (a bound method, a table, a filtered list). Don't re-check them per mutation, per byte or per edge, and don't pass a mode flag down for the callee to branch on.
    • Fors down: give functions the whole batch (randbytes(n), randint_list, translate, numpy) instead of calling them per item, and hoist loop-invariant checks out of loops.
    • Measure: benchmark before and after. Keep the change only if it is faster; if it isn't, record why (see docs/DEEP_DIVE.md §Push ifs up, fors down).
    • Cache safely: a cache of state that can change must be revalidated cheaply or reset at a known boundary, for example mutate() clearing _meta_strategy_cached.