ruzzy

Ruzzy fuzzing campaign

Contract

Field	Bound contract
Trigger	User needs Ruzzy to run coverage-guided fuzzing on Ruby code or a Ruby native extension.
Authority	Reversible local: writes harness, tracer, sanitizer preload, corpus, and installed gem files to the working directory or the local Ruby gem path. Record the installed-gem list before install; rollback is file deletion plus uninstalling exactly the gem version this campaign added. No remote mutation.
Side effect	Write Ruzzy harness scripts, tracer scripts, sanitizer LD_PRELOAD paths, corpus files, and install the target gem with clang and sanitizer flags.
Done	Ruzzy executes the intended Ruby target with the correct tracer or extension setup and reproduces saved failures.

Inputs

Required: Ruby target path or gem name, sanitizer selection (ASan or UBSan).

Optional: corpus directory path, libFuzzer arguments (e.g., -max_len=1024), crash file to reproduce.

Procedure

1. Confirm target: pure Ruby (requires tracer) or C extension (single harness). Done when: the target kind is confirmed as pure Ruby or C extension.
2. Confirm sanitizer: ASan (Ruzzy::ASAN_PATH) or UBSan (Ruzzy::UBSAN_PATH). Done when: the sanitizer is selected and the selected Ruzzy::ASAN_PATH or Ruzzy::UBSAN_PATH constant is confirmed.
3. For pure Ruby targets, write a tracer script calling Ruzzy.trace('harness.rb') and a separate harness script calling Ruzzy.fuzz(test_one_input). For C extensions, write one harness script calling Ruzzy.fuzz(test_one_input); no tracer required. Done when: the harness and, for pure Ruby, the tracer script are written.
4. Write the harness as a lambda named test_one_input that accepts data and returns 0. Catch Ruby exceptions in C extension harnesses; let them propagate in pure Ruby harnesses. Done when: the harness lambda is written with the correct exception handling for the target kind.
5. Set ASAN_OPTIONS=allocator_may_return_null=1:detect_leaks=0:use_sigaltstack=0. Do not export LD_PRELOAD; use it inline with the ruby command. Done when: ASAN_OPTIONS is set and LD_PRELOAD is prepared for inline use.
6. Record gem list --local (each gem's name and version) before any install. Then install the gem with clang and sanitizer flags: set CC=clang, CXX=clang++, LDSHARED="clang -shared", and LDSHAREDXX="clang++ -shared"; set CFLAGS and CXXFLAGS to -fsanitize=address,fuzzer-no-link -fno-omit-frame-pointer -fno-common -fPIC -g for an ASan build, or -fsanitize=undefined,fuzzer-no-link -fno-omit-frame-pointer -fno-common -fPIC -g for a UBSan build, matching the sanitizer selected in step 2 so the instrumented library the run preloads matches the build. Also set MAKE="make --environment-overrides V=1" so GNU make lets environment CC, CFLAGS, and related values override the mkmf Makefile; without --environment-overrides, Ruby's extension build can ignore those flags and install an uninstrumented native library. The -shared flag is required for LDSHARED and LDSHAREDXX; without it the native extension link fails. Done when: the pre-install gem list is recorded and the gem is installed with clang and the flags matching the selected sanitizer.
7. Run: LD_PRELOAD=$(ruby -e 'require "ruzzy"; print Ruzzy::ASAN_PATH') ruby "<harness-or-tracer>.rb" [corpus] [libfuzzer-options] for ASan, or set SAN_PATH=$(ruby -e 'require "ruzzy"; print Ruzzy::UBSAN_PATH') and run LD_PRELOAD="$SAN_PATH" ruby "<harness-or-tracer>.rb" [corpus] [libfuzzer-options] for UBSan. Done when: the fuzzer runs with the correct LD_PRELOAD and harness.
8. On ERROR: AddressSanitizer: or ERROR: UndefinedBehaviorSanitizer:, capture the crash file path, Base64 content, and reproducer command. Write crash-* files to the working directory. Done when: any sanitizer error is captured with crash file path, content, and reproducer command, or the campaign completes without error.
9. To reproduce a saved failure, run the same command passing the crash file path as the final argument. Done when: the saved failure is reproduced or confirmed non-reproducible.