test: fuzz target for the message parser

__msg_parse() turns bytes off a socket into pointers, before anything
has vouched for the peer, and it is the only place in libink that
does.  It had no test of its own beyond whatever the other tests
happened to send it, all of it well-formed.

The target checks the parser's contract, not merely that it survived.
A header field must point into the header field array, and terminate
inside it, and the parse must never claim more bytes than it was
handed.  Crash-only would pass a parser that walked into the body and
returned fields from there, since those bytes were handed over too.
The expected bounds are derived from the raw header rather than from
the parser, so the two have to agree independently.

Every input is copied into an allocation sized to it first.  Reading
past the end of a roomy buffer stays inside the allocation and the
sanitizer never sees it; against an exact one the same read is a
fault, which is where the sharpest findings come from.

Under libFuzzer it is an ordinary fuzz target and named files replay,
which is how a find gets reproduced.  With no arguments it runs a
fixed sweep -- every truncation, every single-byte corruption, every
value of the length that decides where the header ends, and seeded
garbage -- so the suite covers the same contract on every build,
without clang or a corpus in the tree.  It takes 40 ms.

CI fuzzes it properly on every pull request, keeps the crashers, and
carries the corpus between runs so it reaches deeper over time than
any single run can.  Note that clang links the fuzzer runtime against
the newest GCC tree it finds, so the libstdc++ headers have to match
that one and not the default compiler, which is worth saying since
installing the obvious package leaves you exactly where you started.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

doc/build.md

@@ -126,6 +126,60 @@ Linux config to:
 > `/etc/fstab`.
 
 
+Testing
+-------
+
+`make check` runs the test suite in a private namespace, so it is safe
+on a running system.  It needs `unshare` and, on Ubuntu, unprivileged
+user namespaces enabled:
+
+```shell
+sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0
+make check
+```
+
+The D-Bus message parser is the only place in Finit where bytes off a
+socket become pointers, so it also has a fuzz target.  `make check`
+runs it as a fixed sweep, which takes milliseconds and needs nothing
+beyond the normal build.  To fuzz it properly, build it with clang and
+libFuzzer:
+
+```shell
+clang -fsanitize=fuzzer,address -DLINK_FUZZ_LIBFUZZER -D_GNU_SOURCE \
+      -I libink -I . -o fuzz-msg-parse                              \
+      test/src/fuzz-msg-parse.c libink/*.c
+mkdir -p .fuzz-corpus
+./fuzz-msg-parse .fuzz-corpus -max_total_time=300
+```
+
+Give it a corpus directory as above and it saves what it learns there,
+so the next run picks up where this one left off instead of starting
+cold.  Nothing writes to it unless you name it: without the argument
+libFuzzer keeps everything in memory and the run leaves only crashes
+behind.  `make distclean` clears the corpus and the target.
+
+Once a corpus has grown, most of it reaches code some earlier input
+already reached.  Minimise it:
+
+```shell
+./fuzz-msg-parse -merge=1 .fuzz-corpus-min .fuzz-corpus
+rm -rf .fuzz-corpus && mv .fuzz-corpus-min .fuzz-corpus
+```
+
+Run `./configure` first, the target needs the generated `config.h`.
+If the link fails with `cannot find -lstdc++`, install the `libstdc++`
+headers matching the newest GCC on the system, not the default one:
+clang picks the newest tree it finds, and that is the one that needs
+them.  CI runs this target on every pull request, carrying its
+corpus between runs so it reaches deeper over time.
+
+Feed a file back to the target to reproduce a find:
+
+```shell
+./fuzz-msg-parse crash-3f2a...
+```
+
+
 Running
 -------