Afl Smoke

AFL++ Smoke Workflow

Use this skill when changing .github/workflows/ci-afl-smoke.yml, .github/scripts/iccdev-afl-smoke.sh, or AFL smoke seed documentation.

Local Checks

1. Validate shell syntax and style:

   bash -n .github/scripts/iccdev-afl-smoke.sh
   shellcheck .github/scripts/iccdev-afl-smoke.sh

2. Validate workflow syntax and governance:

   actionlint .github/workflows/ci-afl-smoke.yml
   yamllint -d '{extends: default, rules: {line-length: disable, document-start: disable, truthy: disable}}' .github/workflows/ci-afl-smoke.yml
   .github/scripts/preflight-safety-checks.sh --require-tools

3. Run a short local AFL smoke before pushing when AFL++ is installed:

   .github/scripts/iccdev-afl-smoke.sh --seconds 10 --targets dump --exec-timeout-ms 30000
   .github/ci/cfl/build.sh --targets dump,toxml,fromxml,tojson,fromjson,roundtrip,profilevisualize,writerserialize --seconds 30

4. When changing AFL++ bootstrap behavior, validate the regression-container path with root inside the image:

   docker run --rm --user 0 ghcr.io/internationalcolorconsortium/iccdev:latest bash -lc '
   set -euo pipefail
   apt-get -o Acquire::Retries=3 -o Dpkg::Use-Pty=0 update -qq
   apt-get install -y -qq --no-install-recommends llvm-22-dev zlib1g-dev >/tmp/apt-install.log
   afl_src=$(mktemp -d)
   git clone --depth 1 --branch dev https://github.com/AFLplusplus/AFLplusplus.git "$afl_src"
   make -C "$afl_src" -j"$(nproc)" CC=clang-22 CXX=clang++-22 afl-fuzz afl-showmap
   make -C "$afl_src" -j"$(nproc)" CC=clang-22 CXX=clang++-22 LLVM_CONFIG=llvm-config-22 -f GNUmakefile.llvm \
     ./afl-cc ./afl-compiler-rt.o ./SanitizerCoveragePCGUARD.so ./cmplog-routines-pass.so
   probe=$(mktemp -d)
   printf "int main(void) { return 0; }\n" > "$probe/test.c"
   printf "int main(void) { return 0; }\n" > "$probe/test.cpp"
   AFL_PATH="$afl_src" AFL_CC=clang-22 AFL_CXX=clang++-22 "$afl_src/afl-clang-fast" -c "$probe/test.c" -o "$probe/test.o"
   AFL_PATH="$afl_src" AFL_CC=clang-22 AFL_CXX=clang++-22 "$afl_src/afl-clang-fast++" -c "$probe/test.cpp" -o "$probe/testxx.o"
   '

Update Rules

• Treat this area as experimental maintainer scaffolding. The workflows should remain manual/reusable entry points for bounded fuzz checks from master or integration branches, not required merge gates.
• Do not review files under .github/ci/fuzz-patches/afl or .github/ci/fuzz-patches/cfl as final upstream hardening changes. They are local validation patches; durable fixes must be promoted separately as normal source changes.
• Keep workflow triggers manual or reusable unless maintainers explicitly widen them.
• Keep CI AFL++ tooling sourced from https://github.com/AFLplusplus/AFLplusplus/tree/dev and rebuilt against the unified image's Clang/LLVM major version.
• The unified image packages the compiler runtime needed by its packaged afl-clang-fast for short local smoke checks. The AFL workflow must still rebuild and probe AFL++ wrappers against the selected LLVM version.
• Require a matching Clang 21 or Clang 22 C/C++ pair. The packaged wrapper uses 21 and the rebuilt workflow wrapper uses 22; reject older or mismatched AFL_CC and AFL_CXX values before configuring iccDEV.
• Keep the workflow bootstrap narrow: build afl-fuzz, afl-showmap, afl-cc, afl-compiler-rt.o, SanitizerCoveragePCGUARD.so, and cmplog-routines-pass.so. Avoid broad AFL++ targets that enter optional GCC plugin or Nyx paths.
• Keep the target allow-list inside .github/scripts/iccdev-afl-smoke.sh.
• Keep the two lanes' target sets distinct. AFL onboarding stays dump,toxml,fromxml,tojson,fromjson,roundtrip,fromcube (the allow-list above); CFL adds the two in-process targets, dump,toxml,fromxml,tojson,fromjson,roundtrip,profilevisualize,writerserialize. profilevisualize and writerserialize are CFL-only and are rejected by the AFL runner. The first six CFL targets remain CLI-fidelity wrappers. Build profilevisualize and writerserialize in-process through public headers, with the engine sources in separate translation units; never include a CLI implementation or call processLuts() from either harness. writerserialize also links Mini{PDF,SVG,TIFF}.cpp to reach the serialization entries (#2116), and needs a corpus that still contains a CLUT seed (#2120).
• Use .github/ci/fuzz-patches/afl and .github/ci/fuzz-patches/cfl for maintainer-local patch stacks when --patches is requested.
• Keep ci-docker.yml manual-dispatch publication and regression-image verification in sync with AFL/CFL patch-stack helpers. Dispatch the container rebuild after the checker, applicator, smoke script, .github/ci/cfl/, or fuzz patches change.
• Run .github/scripts/check-fuzz-patches.sh after editing either patch stack so malformed hunks or stale context are caught before workflow dispatch.
• Keep manual AFL and CFL workflow inputs aligned: target_ref selects the branch, tag, or ref to check out, optional target_sha pins a full 40-character exact commit, and patch_mode selects all or none. CFL duration must be expressed as seconds per target, not LibFuzzer iteration or execution counts.
• Keep selected AFL targets running in parallel with AFL++ affinity fallback enabled, and merge per-target summaries in a deterministic order.
• Treat saved crashes as smoke failures. Report generated saved hangs as warn summary rows only after verifying Linux core_pattern is not piped; otherwise fail on saved hangs because AFL++ can misclassify crashes as timeouts under piped core handlers. Replay and triage hang artifacts before promoting them to regression evidence.
• Upload any saved crash or hang testcase files as the afl-smoke-findings-<run-id> artifact and list them in the workflow summary. Sanitize uploaded artifact filenames and keep a manifest that records the original AFL paths.
• Upload smoke logs and summary TSVs as separate artifacts so maintainers can debug failed builds even when no crash or hang artifact was generated.
• Replay saved findings with .github/scripts/iccdev-fuzz-triage.sh and report the generated summary, logs, and one-line reproducers.
• Keep numeric workflow options validated by the script, not only by the Actions input UI.
• Pass workflow inputs through env: before shell use, but do not use unknown AFL_* variable names for workflow inputs because AFL++ warns on mistyped AFL environment variables.
• Sanitize all summary output.
• Track only tiny deterministic seeds. Do not commit AFL queues, crashes, hangs, coverage reports, profiler data, or generated build trees.