fuzzer

Author: lws-team

.gitignore

@@ -49,6 +49,7 @@ build/
 doc
 /build2/
 /build3/
+/build-fuzz/
 /cov-int/
 /.vs/
 /build-mtls/

CMakeLists.txt

@@ -218,6 +218,7 @@ option(LWS_WITH_SYS_METRICS "Lws Metrics API" OFF)
 option(LWS_WITH_LATENCY "Event loop latency tracking and monitoring (see ../READMEs/README.LWS_WITH_LATENCY.md)" OFF)
 option(LWS_WITH_UPNG "Enable stateful PNG stream decoder" ON)
 option(LWS_WITH_GZINFLATE "Enable internal minimal gzip inflator" ON)
+option(LWS_WITH_FUZZERS "Build libFuzzer targets against untrusted-input parsers in ./fuzz (needs clang)" OFF)
 option(LWS_WITH_JPEG "Enable stateful JPEG stream decoder" ON)
 option(LWS_WITH_DLO "Enable Display List Objects" ON)
 option(LWS_WITH_WEBRTC "Enable WebRTC" OFF)
@@ -1373,6 +1374,15 @@ list(APPEND LIB_LIST ${LIB_LIST_AT_END})
 # Second-level CMakeLists
 #
 
+if (LWS_WITH_FUZZERS)
+	#
+	# Instrument the whole lib for libFuzzer coverage + ASan, for the
+	# targets in ./fuzz.  The fuzz targets themselves add the libFuzzer
+	# runtime when they link.  Requires clang and libclang-rt-*-dev.
+	#
+	set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fsanitize=fuzzer-no-link,address -fno-omit-frame-pointer -g")
+endif()
+
 include_directories("${PROJECT_SOURCE_DIR}/lib")
 add_subdirectory(lib)
 
@@ -1444,6 +1454,10 @@ if (NOT LWS_WITHOUT_TESTAPPS)
 	add_subdirectory(test-apps)
 endif()
 
+if (LWS_WITH_FUZZERS)
+	add_subdirectory(fuzz)
+endif()
+
 if (NOT LWS_WITH_PLUGINS_BUILTIN)
 add_subdirectory(plugins)
 endif()

fuzz/CMakeLists.txt

@@ -0,0 +1,87 @@
+#
+# libwebsockets - fuzz targets for untrusted-input parsers
+#
+# Copyright (C) 2010 - 2026 Andy Green <andy@warmcat.com>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+#
+# Each fuzz target lives in fuzz-<name>/ with the harness in main.c and
+# committed starting inputs in fuzz-<name>/seeds/.  ctest runs each target
+# against its seeds only, as a fast smoke test of the harness under ASan; use
+# ./fuzz/run.sh for actual fuzzing campaigns with persistent corpora.
+#
+
+if (NOT CMAKE_C_COMPILER_ID MATCHES "Clang")
+	message(FATAL_ERROR "LWS_WITH_FUZZERS needs clang for libFuzzer support (found '${CMAKE_C_COMPILER_ID}').  Install clang and libclang-rt-*-dev and set CC=clang.")
+endif()
+
+#
+# Inputs:	<name>		 target name, fuzz-<name>/main.c etc
+#
+macro(lws_add_fuzz_target name)
+
+	add_executable(fuzz-${name} fuzz-${name}/main.c)
+	target_compile_options(fuzz-${name} PRIVATE -fsanitize=fuzzer,address)
+	target_link_options(fuzz-${name} PRIVATE -fsanitize=fuzzer,address)
+	target_link_libraries(fuzz-${name} websockets ${LIBWEBSOCKETS_DEP_LIBS})
+
+	# run the harness once over each seed under ASan, deterministically
+
+	add_test(NAME fuzz-${name}-smoke
+		 COMMAND fuzz-${name}
+			 ${CMAKE_CURRENT_SOURCE_DIR}/fuzz-${name}/seeds
+			 -runs=0)
+	set_tests_properties(fuzz-${name}-smoke PROPERTIES TIMEOUT 300)
+
+endmacro()
+
+if (LWS_WITH_LEJP)
+	lws_add_fuzz_target(lejp)
+endif()
+
+if (LWS_WITH_CBOR)
+	lws_add_fuzz_target(lecp)
+endif()
+
+if (LWS_WITH_HTTP3 AND LWS_WITH_NETWORK)
+	lws_add_fuzz_target(qpack)
+endif()
+
+if (LWS_WITH_UPNG AND LWS_WITH_GZINFLATE)
+	lws_add_fuzz_target(upng)
+endif()
+
+if (LWS_WITH_LHP AND LWS_WITH_DLO)
+	lws_add_fuzz_target(lhp)
+endif()
+
+# the wsi-bound protocol parsers need the evil-peer helper in peer.h, which
+# uses socketpair + adopt, so they are POSIX-only
+
+if (UNIX AND LWS_WITH_NETWORK)
+	lws_add_fuzz_target(h1)
+
+	if (LWS_WITH_HTTP2)
+		lws_add_fuzz_target(h2)
+	endif()
+
+	if (LWS_ROLE_WS)
+		lws_add_fuzz_target(ws)
+	endif()
+endif()

fuzz/README.md

@@ -0,0 +1,110 @@
+# lws fuzzing
+
+Coverage-guided fuzzing of lws' untrusted-input parsers, using clang's
+libFuzzer + AddressSanitizer.  Everything runs locally with no dependency
+on any external fuzzing infrastructure.
+
+## Quick start
+
+Requirements: `clang` and the libFuzzer runtime (Debian-ish:
+`clang-19 libclang-rt-19-dev`), plus `libgnutls28-dev` if you want the
+`qpack` target (it needs the h3 role, which needs a QUIC-capable TLS
+provider; without gnutls that one target is silently skipped).
+
+```sh
+./fuzz/run.sh              # build + 60s per target against all targets
+./fuzz/run.sh 3600         # an hour per target
+./fuzz/run.sh 600 lejp qpack   # selected targets only
+BUILD=~/fz ./fuzz/run.sh   # non-default build dir
+```
+
+Corpora accumulate per-target in `<build>/fuzz/corpus-<name>/` across runs
+(so coverage keeps advancing between campaigns), seeded from the committed
+inputs in `fuzz/fuzz-<name>/seeds/`.  Anything the fuzzer finds is written
+to `<build>/fuzz/crash-<sha1>`; re-run it directly on the artifact file to
+reproduce:
+
+```sh
+./build-fuzz/bin/fuzz-qpack build-fuzz/fuzz/crash-<sha1>   # repro under ASan
+```
+
+`clang` is autodetected if there is no `clang` binary (eg `clang-19`).
+Additional cmake options can be passed via `FUZZ_CMAKE_OPTS`.
+
+## Reading the output
+
+- `Done N runs in Ts` for a target means its time slice completed with no
+  findings.  Corpus (`corp: N/MKb`) and coverage (`cov:`) growing between
+  runs is the normal steady state, not a problem.
+- Parser error logs during fuzzing are the *expected* face of malformed
+  input being rejected, not findings — the harnesses silence them to keep
+  throughput.  Set `LWS_FUZZ_VERBOSE=1` to replay a specific input with
+  logs, e.g. `LWS_FUZZ_VERBOSE=1 ./build-fuzz/bin/fuzz-qpack <artifact>`.
+- An actual finding is an ASan/UBSan report on stderr plus a
+  `crash-<sha1>` artifact in `<build>/fuzz/`, and `run.sh` exits nonzero.
+- `Ctrl-C` mid-campaign is safe; corpora reached so far are kept, and each
+  target also self-terminates at its `-max_total_time`.
+
+## CI / ctest
+
+The same build registers a fast smoke test per target (`-runs=0`, runs
+each committed seed exactly once under ASan):
+
+```sh
+CC=clang-19 cmake .. --fresh -DLWS_WITH_FUZZERS=ON -DLWS_WITH_CBOR=ON
+cmake --build . --parallel
+ctest -R fuzz-       # seconds, deterministic
+```
+
+`LWS_WITH_FUZZERS` implies whole-lib `-fsanitize=fuzzer-no-link,address`
+instrumentation, so it should stay OFF for normal builds and normal CI.
+Long campaigns belong on a dedicated runner or a nightly job via
+`./fuzz/run.sh`.
+
+## Targets
+
+| target | parser under test | notes |
+|---|---|---|
+| `fuzz-lejp` | lejp JSON parser (`lib/misc/lejp.c`) | policy, JOSE, RPC JSON; fed in two chunks to cover partial-input states |
+| `fuzz-lecp` | lecp CBOR parser (`lib/misc/lecp.c`) | needs `-DLWS_WITH_CBOR=ON` |
+| `fuzz-qpack` | native QPACK decoders (`lib/roles/h3/qpack.c`) | first byte selects encoder-stream vs header-block decode; needs h3 (`LWS_WITH_HTTP3` + gnutls) |
+| `fuzz-upng` | stateful PNG decoder (`lib/misc/upng.c`) | seeds from `test-apps/*.png` |
+| `fuzz-lhp` | HTML5 + CSS parser (`lib/misc/lhp.c`) | builds a dlo document per input and destroys it; leaks and heap errors in teardown are caught |
+| `fuzz-h1` | h1 server header/body parser (`lib/roles/http/`) | evil-peer target, see below |
+| `fuzz-h2` | h2 framing + hpack (`lib/roles/h2/`) | evil-peer: the fuzz input is h2 frames after a canned h2c upgrade + connection preface |
+| `fuzz-ws` | ws server frame parser (`lib/roles/ws/`) | evil-peer: the fuzz input is client frames after a canned upgrade handshake |
+
+The `fuzz-h1`, `fuzz-h2` and `fuzz-ws` targets use the shared evil-peer
+helper in [peer.h](peer.h): one real, adopted server-side connection per
+input over a socketpair, fed the fuzz bytes as if received from the peer,
+serviced deterministically via `lws_service_fd()`, then hung up on so the
+close paths run too.  This exercises the production wsi state machines,
+not just the parsing functions in isolation.  The same pattern will work
+for any other adoptable server-side parser (eg, mqtt).
+
+When a crash is found: reproduce on the artifact, minimize it, fix, then
+commit a minimized seed under the target's `seeds/` and add the same input
+as a case to the corresponding api-test where one exists, so it stays
+covered in normal CI.
+
+## Survey: what to harness next
+
+The wsi-bound h1, h2/hpack and ws parsers are covered via `peer.h`.  The
+remaining untrusted-input surfaces, easiest first:
+
+ - mqtt rx parser (`lib/roles/mqtt/mqtt.c`): an evil-peer target with a
+   canned CONNECT prelude, same shape as `fuzz-ws`
+ - JPEG decoder (`lib/misc/jpeg.c`, `LWS_WITH_JPEG`) — standalone, same
+   shape as `fuzz-upng`
+ - async DNS wire parser (`lib/system/async-dns/async-dns-parse.c`)
+ - auth-dns zone parser (`lib/system/auth-dns/`)
+ - COSE sign/validate (`lib/cose/`), jrpc (`lib/misc/jrpc/`),
+   dht messages (`lib/misc/dht`), sshd userauth / bipacket
+ - `lws_tokenize`, `lws_b64_decode`, iso8601 and friends — standalone,
+   cheap to add
+ - wt (WebTransport) and full h3/QUIC framing: these need the UDP/QUIC
+   stack stood up, a larger project than a socketpair
+
+Fault injection (`lws_fi`) can additionally be used from inside harnesses
+to fail the Nth allocation during parsing, which is where most parser
+lifetime bugs hide.

fuzz/fuzz-h1/main.c

@@ -0,0 +1,47 @@
+/*
+ * lws fuzz target: h1 server-side header and body parsing
+ *
+ * Written in 2010 - 2026 Andy Green <andy@warmcat.com>
+ *
+ * This file is made available under the Creative Commons CC0 1.0
+ * Universal Public Domain Dedication.
+ *
+ * The input is raw h1 request bytes from an untrusted client, fed to a real
+ * adopted server connection.  Everything the h1 server parser touches is
+ * covered: header tokenizing into the ah, URL and query parsing, body and
+ * chunked body handling, and upgrade requests (ws and h2c role transitions).
+ */
+
+#include "../peer.h"
+
+/*
+ * Fuzzing means constantly feeding the parser garbage, so its rejection
+ * logs are expected noise that dominates the runtime.  Set LWS_FUZZ_VERBOSE=1
+ * to get them back (eg, when replaying a crash artifact).
+ */
+
+int
+LLVMFuzzerInitialize(int *argc, char ***argv)
+{
+	(void)argc;
+	(void)argv;
+
+	if (getenv("LWS_FUZZ_VERBOSE"))
+		/* all lws logs, for triage */
+		lws_set_log_level(0x7fff, NULL);
+	else
+		lws_set_log_level(0, NULL);
+
+	if (fuzz_peer_init())
+		return 1;
+
+	return 0;
+}
+
+int
+LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
+{
+	fuzz_peer_session(NULL, 0, data, size);
+
+	return 0;
+}

fuzz/fuzz-h1/seeds/absuri.http

@@ -0,0 +1,3 @@
+GET http://fuzz/a/b?c=d HTTP/1.1
+Host: fuzz
+

fuzz/fuzz-h1/seeds/chunked.http

@@ -0,0 +1,8 @@
+POST /x HTTP/1.1
+Host: fuzz
+Transfer-Encoding: chunked
+
+5
+hello
+0
+

fuzz/fuzz-h1/seeds/duphdrs.http

@@ -0,0 +1,7 @@
+GET / HTTP/1.1
+Host: fuzz
+X-A: 1
+X-A: 2
+Cookie: a=b
+Cookie: c=d
+

fuzz/fuzz-h1/seeds/get.http

@@ -0,0 +1,3 @@
+GET / HTTP/1.1
+Host: fuzz
+

fuzz/fuzz-h1/seeds/longvalue.http

@@ -0,0 +1,4 @@
+GET / HTTP/1.1
+Host: fuzz
+X-Long: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+