[PATCH v2 7/7] fuzz: Add build targets, namespace setup and documentation

[Anshu Kumari <anskuma@redhat.com>]

Add Makefile targets for building and running AFL++ fuzzing:

- fuzz:        AFL++-instrumented binary with AddressSanitizer
- fuzz-server: host-side test server

Add supporting scripts and data:

- fuzzing/fuzz-setup.sh: creates a rootless user+network namespace
  with AnyIP routing so fuzz-server intercepts all outbound TCP
  from passt, no root access needed
- fuzzing/testcase_dir/empty.bin: minimal seed input
- fuzzing/README.fuzzing.md: prerequisites, build instructions,
  namespace setup, single and multi-core fuzzing invocations,
  architecture overview, seed inputs, reproducing crashes

Signed-off-by: Anshu Kumari <anskuma@redhat.com>
---
 Makefile                       |  21 +++++-
 fuzzing/README.fuzzing.md      | 129 +++++++++++++++++++++++++++++++++
 fuzzing/fuzz-setup.sh          |  24 ++++++
 fuzzing/testcase_dir/empty.bin | Bin 0 -> 12 bytes
 4 files changed, 173 insertions(+), 1 deletion(-)
 create mode 100644 fuzzing/README.fuzzing.md
 create mode 100755 fuzzing/fuzz-setup.sh
 create mode 100644 fuzzing/testcase_dir/empty.bin

diff --git a/Makefile b/Makefile
index cce9ffd0..5167929a 100644
--- a/Makefile
+++ b/Makefile
@@ -127,11 +127,30 @@ valgrind: BASE_CPPFLAGS += -DVALGRIND
 valgrind: BASE_CFLAGS += -g
 valgrind: all
 
+FUZZ_CC ?= afl-clang-fast
+FUZZ_CPPFLAGS := -DFUZZING -DNDEBUG
+
+.PHONY: fuzz-objs-clean fuzz
+
+fuzz-objs-clean:
+	$(RM) $(BIN) *~ *.o seccomp.h seccomp_repair.h seccomp_pesto.h pasta.1
+
+fuzz: fuzz-server
+	$(MAKE) fuzz-objs-clean
+	$(MAKE) CC="$(FUZZ_CC)" CPPFLAGS="$(FUZZ_CPPFLAGS)" \
+		CFLAGS="-g -fsanitize=address" passt
+	mv passt passt.fuzz
+
+
+fuzz-server: fuzz-server.c fuzz-testbuf.h
+	$(CC) -D_GNU_SOURCE -O2 -o $@ $<
+
 .PHONY: clean
 clean:
 	$(RM) $(BIN) *~ *.o seccomp.h seccomp_repair.h seccomp_pesto.h pasta.1 \
 		passt.tar passt.tar.gz *.deb *.rpm \
-		passt.pid README.plain.md
+		passt.pid README.plain.md \
+		fuzz-server passt.fuzz
 
 install: $(BIN) $(MANPAGES) docs
 	mkdir -p $(DESTDIR)$(bindir) $(DESTDIR)$(man1dir)
diff --git a/fuzzing/README.fuzzing.md b/fuzzing/README.fuzzing.md
new file mode 100644
index 00000000..1eba36ed
--- /dev/null
+++ b/fuzzing/README.fuzzing.md
@@ -0,0 +1,129 @@
+## Fuzzing passt with AFL++
+
+### Prerequisites
+
+- AFL++ (afl-clang-fast, afl-fuzz)
+- Linux kernel with `CONFIG_USER_NS=y` (default on Fedora, Debian, Ubuntu)
+
+### Build
+
+```
+make fuzz           # AFL++-instrumented binary (produces passt.fuzz)
+```
+
+This also builds `fuzz-server` (the host-side test peer) as a prerequisite.
+
+This produces:
+- `passt.fuzz` -- instrumented with AFL++ and AddressSanitizer
+- `fuzz-server` -- host-side test peer (built automatically)
+
+To use a specific AFL++ installation:
+
+```
+make FUZZ_CC=/path/to/afl-clang-fast fuzz
+```
+
+### Network setup
+
+The fuzzer runs in a rootless user + network namespace with AnyIP
+routing so the test server intercepts all outbound IPv4 and IPv6
+TCP from passt, regardless of destination IP or port.  No root
+access is needed -- `fuzz-setup.sh` uses `unshare --user --net`
+to create the namespace pair, matching how pasta itself operates.
+
+The test server listens on ports 1 through 55535 (both IPv4 and
+IPv6), leaving the top 10000 ports free for passt's own
+`connect()` and `bind()` calls.
+
+The namespace exists only while the command runs; no cleanup step
+is required.
+
+### Run
+
+passt automatically fork+execs `fuzz-server` before the AFL++
+forkserver starts, then sleeps 3 seconds to let it finish binding
+all ports.  There is no need to launch it separately.
+
+Basic run:
+
+```
+fuzzing/fuzz-setup.sh -- afl-fuzz -i fuzzing/testcase_dir \
+  -o fuzzing/sync_dir -- ./passt.fuzz --foreground
+```
+
+Multi-core (secondary instances share the corpus):
+
+```
+# Terminal 1 -- main instance:
+fuzzing/fuzz-setup.sh -- afl-fuzz -M main \
+  -i fuzzing/testcase_dir -o fuzzing/sync_dir \
+  -- ./passt.fuzz --foreground
+
+# Terminal 2 -- secondary with different power schedule:
+fuzzing/fuzz-setup.sh -- afl-fuzz -S variant1 -p rare \
+  -i fuzzing/testcase_dir -o fuzzing/sync_dir \
+  -- ./passt.fuzz --foreground
+```
+
+### Architecture
+
+AFL++ controls four regions of the testcase buffer:
+
+- **(a) `ev`** -- array of epoll events injected into passt's
+  main loop alongside real kernel events
+- **(b) `buf`** -- raw tap-side packets (full L2 frames, headers
+  included). AFL++ controls everything: Ethernet, IP, TCP/UDP
+  headers, destination addresses, payload
+- **(c) `test_buf`** -- payload the test server sends to passt
+  on accepted connections
+- **(d) `sockopt_buf`** -- TCP_INFO data returned to passt by the
+  `getsockopt()` wrapper in fuzz.c
+
+The testcase header carries explicit lengths for each region:
+`n_events` (u32), `tap_len` (u16), `testbuf_len` (u16), and
+`sockopt_len` (u16).  Both passt and `fuzz-server` call
+`fuzz_parse_layout()` on the same header, which clamps each
+declared length to the available space and to per-region maximums,
+so the two sides always agree on offsets.  AFL++ controls the
+split directly through mutation of these header fields.
+
+Example flow for a single event:
+
+1. AFL++ writes an EPOLLIN event with type EPOLL_TYPE_TAP_PASST
+   in `ev`, raw packet data in `buf`, and payload in `test_buf`
+2. passt reads the event from `ev`, reads data from `buf`, and
+   hands it to tap_handler()
+3. The data happens to have Ethernet, IP, and TCP headers with
+   the SYN flag set (AFL++ discovered this format). passt calls
+   connect() to the destination in the packet
+4. AnyIP routing makes the destination local and the test server,
+   which listens on ports 1-55535 (IPv4+IPv6), accepts the connection
+5. The test server sends the contents of `test_buf` to passt
+6. A real epoll_wait() fires EPOLLOUT for passt (not from `ev`)
+7. passt marks the connection established and inserts it in the
+   flow table
+8. passt reads data from the test server and generates TCP data
+   back to the "guest"
+
+### Seed inputs
+
+`testcase_dir/empty.bin` provides a minimal starting point.
+AFL++ discovers packet formats through mutation.
+
+### Reproducing crashes
+
+Replay a crash input (`fuzz-server` is fork+exec'd by passt
+automatically):
+
+```
+fuzzing/fuzz-setup.sh -- ./passt.fuzz --foreground < \
+  fuzzing/sync_dir/default/crashes/id:000000,...
+```
+
+Minimize a crash input:
+
+```
+fuzzing/fuzz-setup.sh -- afl-tmin \
+  -i fuzzing/sync_dir/default/crashes/id:000000,... \
+  -o crash_minimized -- ./passt.fuzz --foreground
+```
diff --git a/fuzzing/fuzz-setup.sh b/fuzzing/fuzz-setup.sh
new file mode 100755
index 00000000..130016bc
--- /dev/null
+++ b/fuzzing/fuzz-setup.sh
@@ -0,0 +1,24 @@
+#!/bin/sh
+#
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# fuzzing/fuzz-setup.sh - Rootless network namespace for AFL++ fuzzing
+#
+# Creates a user + network namespace (no root required) with AnyIP
+# routing so the test server intercepts all outbound TCP connections
+# from passt, regardless of destination IP/port or address family.
+#
+# Usage:
+#   fuzzing/fuzz-setup.sh -- afl-fuzz [opts] -- ./passt.fuzz --foreground
+#
+# Copyright Red Hat
+# Author: Anshu Kumari <anskuma@redhat.com>
+
+exec unshare --map-root-user --net -- sh -c '
+	set -e
+	ip link set lo up
+	ip route add local 0.0.0.0/0 dev lo
+	ip -6 route add local ::/0 dev lo
+
+	exec "$@"
+' _ "$@"
diff --git a/fuzzing/testcase_dir/empty.bin b/fuzzing/testcase_dir/empty.bin
new file mode 100644
index 0000000000000000000000000000000000000000..ce58bc9f84b9623e708de4eb8427a57d9f9a160f
GIT binary patch
literal 12
KcmZQzKmY&$3;+QD

literal 0
HcmV?d00001

-- 
2.55.0