Fuzz harnesses for the command parser and the reply stream (#144)

.github/workflows/fuzz.yml

@@ -0,0 +1,71 @@
+name: fuzz
+
+# The libFuzzer harnesses of fuzz/ (fuzz/README.md), on every push and pull request: each built with clang under
+# AddressSanitizer and UndefinedBehaviorSanitizer and fuzzed for 60 s from its seed corpus, every mutant of
+# fuzz/mutants/ found by its own property, the coverage witness held to its floor, and the corpus current. An input
+# that crashes a harness is uploaded as the fuzz-findings artifact. The command socket's chunking test stays in ci.yml.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  fuzz:
+    name: fuzz the command parser and the reply stream
+    runs-on: ubuntu-latest
+    # a backstop: fuzz-run spends 60 s on each harness and fuzz-sabotage runs seeds only, so the job ends well inside it
+    timeout-minutes: 30
+    container:
+      image: fedora:44
+    steps:
+      - name: Install clang, libFuzzer and llvm-cov
+        run: |
+          dnf install -y --setopt=install_weak_deps=False git dnf5-plugins clang compiler-rt llvm make gawk diffutils \
+            python3 pkgconf-pkg-config
+
+      - uses: actions/checkout@v4
+
+      # the harnesses read mod-host's protocol headers: the FreeMixer channel's mod-host-protocol-devel, at or above the
+      # floor the spec declares for the build
+      - name: Install the mod-host protocol headers from the FreeMixer channel
+        run: |
+          set -euo pipefail
+          dnf config-manager addrepo --setopt=retries=10 --from-repofile=https://freemixer.github.io/rpm/freemixer.repo
+          floor=$(sed -n 's/^BuildRequires:[[:space:]]*mod-host-protocol-devel[[:space:]]*>=[[:space:]]*\([^[:space:]]*\).*/\1/p' packaging/plugin-hostd.spec | head -n 1)
+          test -n "$floor"
+          dnf install -y --setopt=retries=10 "mod-host-protocol-devel >= $floor"
+
+      # fuzz-sabotage applies each mutant with git and restores it with git checkout
+      - name: Let git work in the checkout
+        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+      - name: Build the harnesses (clang, libFuzzer, ASan, UBSan)
+        run: make fuzz
+
+      - name: The seed corpus is what the declared protocol gives
+        run: make fuzz-corpus-check
+
+      - name: Fuzz each harness for 60 s
+        run: make fuzz-run FUZZ_TIME=60
+
+      # a property no mutant can break checks nothing: each one-line mutant must make its harness abort on a seed, in
+      # that property's own check
+      - name: Find every mutant, each by its own property
+        run: make fuzz-sabotage
+
+      # the seed corpus must keep reaching the lines it reaches today (fuzz/coverage-floor.txt) and every property
+      # check of every harness
+      - name: Hold the coverage floor
+        run: make fuzz-coverage
+
+      - name: Upload the crashing inputs
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fuzz-findings
+          path: fuzz/findings/
+          if-no-files-found: ignore

.gitignore

@@ -20,3 +20,5 @@ tests/gesture-alloc-test
 tests/lv2-alloc-test
 tests/lv2-alloc-lv2.o
 tests/transforms-test
+/build/
+fuzz/findings/

Makefile

@@ -158,9 +158,75 @@ private-refs:
 	tools/private-refs-check.sh
 	tools/private-refs-check.sh --self-test
 
+# libFuzzer harnesses (fuzz/README.md): the command parser and dispatcher, src/verbs.c with the mod-host side replaced by
+# a recorder, and the reply stream, src/relay.c with its sockets answered by the harness; clang with libFuzzer,
+# AddressSanitizer and UndefinedBehaviorSanitizer, into build/fuzz/. Nothing of the ordinary build is touched.
+#   make fuzz                  build every harness
+#   make fuzz-run FUZZ_TIME=60 fuzz each one from its seed corpus; red on any crash
+#   make fuzz-sabotage         each mutant of fuzz/mutants/ must make its harness abort on a seed, in its own property
+#   make fuzz-coverage         the coverage witness: llvm-cov over the corpus, held to fuzz/coverage-floor.txt
+#   make fuzz-corpus           write fuzz/corpus/ again from the declared protocol and the README examples
+FUZZ_CC        ?= clang
+FUZZ_TIME      ?= 60
+FUZZ_BUILD     := build/fuzz
+FUZZ_HARNESSES := command reply
+FUZZ_SAN       := -fsanitize=address,undefined -fno-sanitize-recover=all
+FUZZ_CFLAGS    := -O1 -g -std=c11 -D_GNU_SOURCE -Wall -Wextra -Werror -fno-omit-frame-pointer
+FUZZ_INCS      := -Iinclude -Isrc -Ifuzz $(PROTOCOL_CFLAGS)
+# what each harness is built from beside its own file: the command harness links the parser and the recorder, the
+# reply harness includes src/relay.c itself
+FUZZ_SRC_command := src/verbs.c fuzz/recorder.c
+FUZZ_SRC_reply   :=
+FUZZ_DEPS        := fuzz/fuzz.h fuzz/syntax.h fuzz/recorder.h src/relay.c src/verbs.h include/plugin-hostd/protocol.h
+
+$(FUZZ_BUILD)/fuzz_%: fuzz/fuzz_%.c $(FUZZ_DEPS) $(FUZZ_SRC_command)
+	@mkdir -p $(dir $@)
+	$(FUZZ_CC) $(FUZZ_CFLAGS) $(FUZZ_SAN) -fsanitize=fuzzer $(FUZZ_INCS) $< $(FUZZ_SRC_$*) -pthread -o $@
+
+fuzz: $(FUZZ_HARNESSES:%=$(FUZZ_BUILD)/fuzz_%)
+
+fuzz-run: fuzz
+	FUZZ_BUILD=$(FUZZ_BUILD) FUZZ_TIME=$(FUZZ_TIME) fuzz/run.sh $(FUZZ_HARNESSES)
+
+fuzz-sabotage:
+	FUZZ_BUILD=$(FUZZ_BUILD) MAKE="$(MAKE)" fuzz/sabotage.sh
+
+# the coverage witness: the same harnesses without sanitizers, instrumented for llvm-cov, each run once over its seed
+# corpus (-runs=0 executes the corpus and nothing else); the llvm-cov and llvm-profdata of FUZZ_CC's own LLVM
+FUZZ_COV_BUILD := $(FUZZ_BUILD)/cov
+FUZZ_COV_FLAGS := -O0 -g -std=c11 -D_GNU_SOURCE -fprofile-instr-generate -fcoverage-mapping
+LLVM_COV       ?= llvm-cov
+LLVM_PROFDATA  ?= llvm-profdata
+
+$(FUZZ_COV_BUILD)/fuzz_%: fuzz/fuzz_%.c $(FUZZ_DEPS) $(FUZZ_SRC_command)
+	@mkdir -p $(dir $@)
+	$(FUZZ_CC) $(FUZZ_COV_FLAGS) -fsanitize=fuzzer $(FUZZ_INCS) $< $(FUZZ_SRC_$*) -pthread -o $@
+
+fuzz-coverage: $(FUZZ_HARNESSES:%=$(FUZZ_COV_BUILD)/fuzz_%)
+	@set -e; for h in $(FUZZ_HARNESSES); do \
+	  rm -f $(FUZZ_COV_BUILD)/$$h.profraw; \
+	  LLVM_PROFILE_FILE=$(FUZZ_COV_BUILD)/$$h.profraw $(FUZZ_COV_BUILD)/fuzz_$$h -runs=0 fuzz/corpus/$$h/ \
+	      >$(FUZZ_COV_BUILD)/$$h.log 2>&1 || \
+	    { cat $(FUZZ_COV_BUILD)/$$h.log; echo "fuzz-coverage: fuzz_$$h failed on its own corpus"; exit 1; }; \
+	  $(LLVM_PROFDATA) merge -sparse $(FUZZ_COV_BUILD)/$$h.profraw -o $(FUZZ_COV_BUILD)/$$h.profdata; \
+	done
+	@LLVM_COV=$(LLVM_COV) fuzz/coverage.sh $(FUZZ_COV_BUILD) $(FUZZ_HARNESSES)
+
+# the seed corpus is written from protocol/plugin-hostd.json, protocol/mod-host.json and the send lines of README.md and
+# docs/own-host.md, never from a network, and committed; fuzz-corpus-check fails when it is not what they give
+fuzz-corpus:
+	python3 fuzz/gen_corpus.py fuzz/corpus
+
+fuzz-corpus-check:
+	@set -e; tmp=$$(mktemp -d); trap 'rm -rf $$tmp' EXIT; \
+	python3 fuzz/gen_corpus.py $$tmp; diff -r $$tmp fuzz/corpus; echo "the seed corpus is current"
+
+.PHONY: fuzz fuzz-run fuzz-sabotage fuzz-coverage fuzz-corpus fuzz-corpus-check
+
 # clean rule
 clean:
 	@rm -f src/*.o $(PROG) $(PROBE) tests/probe-child tests/lv2-probe-child tests/rt_interpose.so $(FAKE) $(PIN_TEST) $(RELAY_TEST) tests/relay-test-relay.o $(FORMAT_TEST) $(GESTURE_ALLOC_TEST) $(LV2_ALLOC_TEST) tests/lv2-alloc-lv2.o $(TRANSFORMS_TEST) $(GEN) tests/stress.clap tests/jack_levels tests/host_scenarios $(LV2_FIXTURE)
+	@rm -rf build
 
 # the daemon against workers that are not plugin hosts at all (tests/fake-host speaks the same protocol and can be
 # made to die on cue): placement, forwarding, ledger, replay, attribution, the storm bound; no jack, no plugin

debian/changelog

@@ -1,3 +1,22 @@
+plugin-hostd (0.9.2) unstable; urgency=medium
+
+  * worker_list, supervisor_reset and quit answer -902 to a word past
+    their grammar instead of acting on it: worker_list x no longer lists,
+    supervisor_reset all x no longer resets, and quit now no longer stops
+    the daemon.
+  * A tab at the end of a command is trimmed like a space: a command
+    ending in a carriage return and a tab no longer reaches the worker with
+    both.
+  * The end of a held gesture longer than 1024 bytes reaches the controller
+    whole, with its end word; before, it was cut short and the control stayed
+    held.
+  * The build needs mod-host's protocol headers of mod-host-protocol-devel
+    0.10.6.f14a230-11 or newer (libmod-host-protocol-dev 0.1.0-5 or newer), the
+    first with param_info, remote_pages and track_info.
+  * Fuzz harnesses for the command parser and the reply stream (#144).
+
+ -- Pau Aliagas <linuxnow@gmail.com>  Sat, 24 Oct 2026 22:40:03 +0200
+
 plugin-hostd (0.9.1) unstable; urgency=medium
 
   * The preset schema, protocol/preset.schema.json, is installed in

debian/control

@@ -3,7 +3,7 @@ Section: sound
 Priority: optional
 Maintainer: Pau Aliagas <linuxnow@gmail.com>
 Build-Depends: debhelper-compat (= 13),
-               libmod-host-protocol-dev,
+               libmod-host-protocol-dev (>= 0.1.0-5),
                libomx-contract-dev (>= 3.0.0~),
                omx-clap-host-tests (>= 0.9.0~) <!nocheck>,
                pkgconf,

doc/plugin-hostd-probe.1

@@ -1,4 +1,4 @@
-.TH PLUGIN\-HOSTD\-PROBE 1 "October 2026" "plugin-hostd 0.9.1" "User Commands"
+.TH PLUGIN\-HOSTD\-PROBE 1 "October 2026" "plugin-hostd 0.9.2" "User Commands"
 .SH NAME
 plugin\-hostd\-probe \- run a plugin prober under limits and write what happened
 .SH SYNOPSIS

doc/plugin-hostd.1

@@ -1,4 +1,4 @@
-.TH PLUGIN\-HOSTD 1 "October 2026" "plugin-hostd 0.9.1" "User Commands"
+.TH PLUGIN\-HOSTD 1 "October 2026" "plugin-hostd 0.9.2" "User Commands"
 .SH NAME
 plugin\-hostd \- supervisor of plugin host processes behind one mod\-host protocol socket
 .SH SYNOPSIS

fuzz/README.md

@@ -0,0 +1,108 @@
+Fuzzing plugin-hostd
+====================
+
+The daemon reads two streams it does not control: the commands of any local client, and what each worker writes on its
+feedback socket. Each has a libFuzzer harness here, built with clang under AddressSanitizer and
+UndefinedBehaviorSanitizer and run in CI on every push and pull request (`.github/workflows/fuzz.yml`).
+
+Each harness is one C file defining `LLVMFuzzerTestOneInput`. It reads its input as a small program, a sequence of
+messages or operations, until the input ends; every input means something. No harness opens a socket, starts a
+process or a thread, reads a clock, the environment or a file, or calls `dlopen`. Properties are checked with
+`if (!cond) abort();`, never `assert()`; every outcome an input can choose returns 0, nothing calls `exit()`, and an
+input of 64 MiB or more is refused. The header comment of each harness gives its input format and its properties.
+
+The harnesses
+-------------
+
+| Harness | Code it drives | Input |
+| --- | --- | --- |
+| `fuzz_command` | `verbs_receive` and the dispatcher of `src/verbs.c`, with everything below it replaced by the recorder of `fuzz/recorder.c` | up to 32 messages, each a flags byte (accept, or refuse with a declared code) and the message's bytes |
+| `fuzz_reply` | the feedback reader of `src/relay.c`: `drain`, the gesture table, `relay_remove`, `relay_instance_gone`, `relay_event` | up to 512 operations: a worker writes, is read, closes, is removed; an instance goes; the controller takes short sends or goes away |
+
+The recorder stands in for the supervisor, the pins, the descriptors and the socket's send. It answers every call with
+the reply its verb declares in `include/plugin-hostd/protocol.h`, or with the refusal the input chose, and folds what an
+accepted call changes into a digest of the daemon's state. `fuzz_reply` includes `src/relay.c` and answers its `recv`
+and `send` itself, and builds it with a line limit of 6000 bytes so that small inputs reach the drop of a long line.
+
+What each harness proves, beyond no sanitizer report:
+
+- **command / reply**: every message gets one reply, a NUL-terminated string of a declared shape, the supervisor's
+  answer unchanged.
+- **command / arity**: a verb the daemon parses itself is acted on only with an argument count its declared syntax
+  allows.
+- **command / round-trip**: a command's words joined by one space, as the declaration writes them, make the same calls,
+  the same reply and the same state.
+- **command / refusal**: a refused command leaves the daemon's state as it was.
+- **reply / bounded**: an unfinished line held for a worker never passes the line limit, and its buffer stays bounded.
+- **reply / no-loss**: the controller reads every complete line a worker wrote once, in order, however the stream was
+  cut and wherever its NULs fell, as a reference splitter over the same bytes reads them.
+- **reply / shape**: every line the relay writes of its own is an event as written or the end of a gesture still held,
+  once each.
+
+The harnesses found what is fixed with them: `worker_list`, `supervisor_reset` and `quit` took words their grammar
+does not, a tab at the end of a command was not trimmed as a space is, and the end of a held gesture longer than 1024
+bytes went out cut short.
+
+The seed corpus
+---------------
+
+`fuzz/corpus/<harness>/` is written by `fuzz/gen_corpus.py` (`make fuzz-corpus`) and committed. The command seeds are
+every verb of `protocol/plugin-hostd.json` and `protocol/mod-host.json` with sample arguments, each with its optional
+words, with one word too many, refused by the supervisor and split by tabs, the placements of `add`, and the `send`
+lines of `README.md` and `docs/own-host.md`. The reply seeds cut worker feedback at every byte and before every NUL,
+hold, end and abandon gestures, and put lines at and past the line limit. Nothing is fetched; `make fuzz-corpus-check`
+fails when the committed corpus is not what the generator writes.
+
+The coverage witness
+--------------------
+
+`make fuzz-coverage` builds each harness for `llvm-cov`, runs it once over its corpus and prints the line coverage of
+the functions it drives, then every line no seed reaches. `fuzz/coverage-floor.txt` holds the covered lines of each
+harness, and the target is red below it, or when a property check of a harness file is executed by no seed
+(`fuzz/checks.awk`).
+
+| Harness | Lines | Covered | Lines no seed reaches |
+| --- | ---: | ---: | --- |
+| command | 153 | 100.00% | |
+| reply | 210 | 90.00% | the paths taken when `realloc` fails (`tests/relay_test.c` and `tests/gesture_alloc_test.c` drive them), the relay thread's join and the listening socket in `relay_finish`, and the `fd < 0` guards of `relay_add` and `relay_remove` |
+
+The mutants
+-----------
+
+`fuzz/mutants/<harness>-<property>.patch` is a one-line bug for each property. `make fuzz-sabotage` applies each,
+rebuilds the harness, runs it over every seed one at a time, restores the source with `git checkout --`, and is red
+unless at least one seed makes the harness abort and every seed that does aborts in `check_<property>`: a mutant that
+also breaks another property does not pass.
+
+| Mutant | The bug | Found by |
+| --- | --- | --- |
+| `command-reply` | the reply is sent without its NUL | `add-default` |
+| `command-arity` | `pool_config` takes three words or more | `plugin-hostd-pool_config-extra` |
+| `command-round-trip` | the first word is split at spaces only | `mod-host-add-tabs` |
+| `command-refusal` | a refused `add` still starts a descriptor scan | `add-instance-past-the-table` |
+| `reply-bounded` | the overflow check compares with the capacity, not the line limit | `line-past-the-limit-in-parts` |
+| `reply-no-loss` | a line of exactly the line limit is dropped | `line-at-the-limit` |
+| `reply-shape` | a held gesture is ended with `begin` | `controller-takes-a-few-bytes-a-send` |
+
+Running
+-------
+
+```
+make fuzz                    # build both harnesses into build/fuzz/
+make fuzz-run FUZZ_TIME=60   # fuzz each for 60 s; red on any crash
+make fuzz-sabotage           # every mutant found by its own property
+make fuzz-coverage           # the coverage witness
+make fuzz-corpus             # write fuzz/corpus/ again
+```
+
+They need clang with libFuzzer (`compiler-rt` on Fedora) and, for `fuzz-coverage`, `llvm-cov` and `llvm-profdata`, and
+mod-host's protocol headers, found as for the ordinary build. One harness by hand:
+
+```
+mkdir -p /tmp/new && build/fuzz/fuzz_reply -max_total_time=60 /tmp/new fuzz/corpus/reply
+```
+
+`make fuzz-run` writes an input that crashed a harness to `fuzz/findings/<harness>-crash-<sha1>`, with the log beside
+it; CI uploads the directory as the `fuzz-findings` artifact. `build/fuzz/fuzz_<harness> <that file>` replays it. Once
+the bug is fixed, copy the input into `fuzz/corpus/<harness>/` under a name that says what it is, and add it to
+`fuzz/gen_corpus.py`, so every later run replays it first.

fuzz/checks.awk

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+# Copyright (C) 2026 Pau Aliagas <linuxnow@gmail.com>
+#
+# THE HARNESS FLOOR (fuzz/coverage.sh). Reads `llvm-cov show` of one harness source
+# (`LINE|COUNT|source`) and prints, for every property check in it, one line
+#
+#   <file>:<check line>:<abort line>:<count>:<the check's first source line>
+#
+# A property check is an abort() and the statement that guards it: the `if` whose
+# condition ends in the abort, or, for a bare abort() in a block (an `else` arm, a
+# switch's `default:`), the statement that opens that block. <count> is how often the
+# seed corpus executed that statement's first line; 0 is a property no seed tests.
+# Comments are stripped before anything is matched, so an abort() named in prose is
+# not a site.
+BEGIN { FS = "|" }
+{
+	ln = $1 + 0
+	cnt = $2
+	gsub(/[ \t]/, "", cnt)
+	src = $0
+	sub(/^[^|]*\|[^|]*\|/, "", src)
+	code = src
+	if (incomment) {
+		if (code ~ /\*\//) { sub(/^.*\*\//, "", code); incomment = 0 }
+		else code = ""
+	}
+	while (match(code, /\/\*([^*]|\*+[^*\/])*\*+\//))
+		code = substr(code, 1, RSTART - 1) substr(code, RSTART + RLENGTH)
+	if (code ~ /\/\*/) { sub(/\/\*.*$/, "", code); incomment = 1 }
+	sub(/\/\/.*$/, "", code)
+	gsub(/^[ \t]+|[ \t]+$/, "", code)
+	C[ln] = code; N[ln] = cnt; S[ln] = src
+	if (code ~ /(^|[^A-Za-z0-9_])abort\(\);/) site[++ns] = ln
+}
+
+# The first line of the statement that ends on line l.
+function stmt_start(l) {
+	while (l > 1 && C[l - 1] != "" && C[l - 1] !~ /[;{}:]$/) l--
+	return l
+}
+
+END {
+	for (i = 1; i <= ns; i++) {
+		l = site[i]
+		s = stmt_start(l)
+		if (s == l && C[l] ~ /^abort\(\);/) {
+			d = 0
+			for (s = l - 1; s >= 1 && d >= 0; s--)
+				for (k = length(C[s]); k >= 1; k--) {
+					c = substr(C[s], k, 1)
+					if (c == "}") d++
+					else if (c == "{" && --d < 0) break
+				}
+			s = stmt_start(s + 1)
+		}
+		t = S[s]
+		gsub(/^[ \t]+/, "", t)
+		printf "%s:%d:%d:%s:%s\n", file, s, l, N[s], t
+	}
+}