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
---
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
+
+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