yams/tools/fuzzing

YAMS Fuzzing Infrastructure

AFL++ fuzzing harnesses for CLI/daemon IPC protocol testing per issue #8.

Targets

Protocol Layer

• fuzz_ipc_protocol - MessageFramer, CRC32 validation, frame header parsing
• fuzz_add_document - AddDocumentRequest/UpdateDocumentRequest deserialization

Daemon Services & IPC Bus

• fuzz_proto_serializer - Protobuf encoding/decoding of IPC message payloads
• fuzz_request_handler - Request processing, message framing, and handler configuration
• fuzz_streaming_processor - Chunked streaming response handling and processor delegation

Fuzzers run in aflplusplus/aflplusplus Docker container for reproducibility.

Usage

Build fuzzers:

./tools/fuzzing/fuzz-docker.sh build

Run fuzzer:

./tools/fuzzing/fuzz-docker.sh fuzz ipc_protocol
./tools/fuzzing/fuzz-docker.sh fuzz add_document
./tools/fuzzing/fuzz-docker.sh fuzz proto_serializer
./tools/fuzzing/fuzz-docker.sh fuzz request_handler
./tools/fuzzing/fuzz-docker.sh fuzz streaming_processor

Monitor:

./tools/fuzzing/fuzz-docker.sh exec afl-whatsup /fuzz/findings/ipc_protocol
./tools/fuzzing/fuzz-docker.sh exec afl-whatsup /fuzz/findings/proto_serializer

Reproduce crash:

./tools/fuzzing/fuzz-docker.sh exec \
  /build/tools/fuzzing/fuzz_ipc_protocol /fuzz/findings/ipc_protocol/crashes/id:000000*
./tools/fuzzing/fuzz-docker.sh exec \
  /build/tools/fuzzing/fuzz_proto_serializer /fuzz/findings/proto_serializer/crashes/id:000000*

Architecture

Directory Structure

tools/fuzzing/
├── README.md                       # This file
├── fuzz-docker.sh                 # Docker wrapper script
├── meson.build                    # Build definitions
├── fuzz_ipc_protocol.cpp          # IPC protocol fuzzer harness
├── fuzz_add_document.cpp          # Document fuzzer harness
├── fuzz_proto_serializer.cpp      # Protobuf serializer fuzzer
├── fuzz_request_handler.cpp       # Request handler fuzzer
├── fuzz_streaming_processor.cpp   # Streaming processor fuzzer
└── generate_corpus.sh             # Seed corpus generator

data/fuzz/
├── corpus/                        # Input seeds (read-only for fuzzer)
│   ├── ipc_protocol/             # IPC protocol seeds
│   ├── add_document/             # Document request seeds
│   ├── proto_serializer/         # Protobuf message seeds
│   ├── request_handler/          # Request handler seeds
│   └── streaming_processor/      # Streaming processor seeds
└── findings/                      # AFL++ output (crashes, hangs, queue)
    ├── ipc_protocol/
    ├── add_document/
    ├── proto_serializer/
    ├── request_handler/
    └── streaming_processor/

Instrumentation Flow

1. Conan Profile       → conan/profiles/aflplusplus-docker
                         Sets: AFL_USE_ASAN=1, AFL_HARDEN=1
                         Compiler: afl-clang-fast++

2. Setup Script        → ./setup.sh Fuzzing
                         Build type: Debug (for symbols)
                         Enables: -Dbuild-fuzzers=true

3. Meson Build         → tools/fuzzing/meson.build
                         Flags: -fsanitize=fuzzer (AFL++ libFuzzer mode)
                         Links: Static daemon IPC libraries

4. Fuzzer Binary       → build/fuzzing/tools/fuzzing/fuzz_*
                         Entry: LLVMFuzzerTestOneInput()
                         ASAN: Memory safety checks
                         AFL++: Coverage-guided mutation

Configuration

Conan profile (conan/profiles/aflplusplus-docker):

• AFL_HARDEN=1 - Stack protector, fortify source
• AFL_USE_ASAN=1 - Address sanitizer
• AFL_LLVM_INSTRUMENT=AFL - AFL instrumentation mode
• Compiler: afl-clang-fast++
• libcxx: libc++ (container default)

Compiler flags:

• -fsanitize=fuzzer (compile and link)
• Enables AFL++ libFuzzer compatibility mode with automatic persistent mode

Advanced

Parallel fuzzing (main + secondary workers):

# Terminal 1
./tools/fuzzing/fuzz-docker.sh fuzz ipc

# Terminal 2-N
docker run -ti --rm -v "$(pwd):/src:ro" -v "$(pwd)/build/fuzzing:/build" \
  -v "$(pwd)/data/fuzz:/fuzz" aflplusplus/aflplusplus \
  afl-fuzz -i /fuzz/corpus/ipc -o /fuzz/findings/ipc \
  -S worker1 -m none /build/tools/fuzzing/fuzz_ipc_protocol

Corpus minimization:

./tools/fuzzing/fuzz-docker.sh exec bash -c \
  "afl-cmin -i /fuzz/findings/ipc/queue -o /fuzz/corpus/ipc_min -m none \
   -- /build/tools/fuzzing/fuzz_ipc_protocol"

Crash minimization:

./tools/fuzzing/fuzz-docker.sh exec bash -c \
  "afl-tmin -i /fuzz/findings/ipc/crashes/id:000000 -o crash_min -m none \
   -- /build/tools/fuzzing/fuzz_ipc_protocol"

Seed Corpus

Location: data/fuzz/corpus/<target>/

Generate minimal seeds:

./tools/fuzzing/generate_corpus.sh

Add custom seeds from:

• Integration test traffic capture
• Sanitized CLI→daemon messages
• Manual construction

Corpus should cover request types, edge cases, and real-world patterns. Do not include secrets.

CI Integration

See .github/workflows/fuzzing.yml:

• PR smoke tests: 5 min timeout
• Nightly: 1+ hour for deeper coverage

Crash Triage

Reproduce:

./tools/fuzzing/fuzz-docker.sh exec \
  /build/tools/fuzzing/fuzz_ipc_protocol /fuzz/findings/ipc/crashes/id:000000*

ASAN provides automatic stack traces. After fixing:

1. Rebuild fuzzers
2. Verify crash input no longer crashes
3. Add crash input to corpus for regression prevention

Troubleshooting

AFL++ compiler not detected: Use ./tools/fuzzing/fuzz-docker.sh build

No instrumentation: Verify Conan profile conan/profiles/aflplusplus-docker sets afl-clang-fast++

Out of memory: Increase Docker limit or disable ASAN for throughput fuzzing

Corpus too large: Run afl-cmin for minimization

References

• Issue #8: Crash Fuzzing & Stability Hardening
• AFL++ docs: https://github.com/AFLplusplus/AFLplusplus/tree/stable/docs
• AFL++ container: https://hub.docker.com/r/aflplusplus/aflplusplus