internationalcolorconsortium/iccdev/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 bash -n .github/scripts/iccdev-afl-smoke.sh shellcheck .github/scripts/iccdev-afl-smoke.sh ``

1. Validate workflow syntax and governance:

``bash 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 ``

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

``bash .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 ``

1. When changing AFL++ bootstrap behavior, validate the regression-container

path with root inside the image:

``bash 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) afl_ref=2400206be6fe0d93681c8a5c1535209366602eb1 git clone --filter=blob:none --no-checkout https://github.com/AFLplusplus/AFLplusplus.git "$afl_src" git -C "$afl_src" fetch --depth=1 origin "$afl_ref" git -C "$afl_src" checkout --detach FETCH_HEAD test "$(git -C "$afl_src" rev-parse HEAD)" = "$afl_ref" 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 pinned to commit

2400206be6fe0d93681c8a5c1535209366602eb1 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.