microchip-ung · jeso-mchp · Apr 9, 2026 · Apr 9, 2026 · Mar 15, 2026 · Mar 15, 2026
diff --git a/.gitignore b/.gitignore
@@ -1 +1,3 @@
 build
+build-fuzz
+corpus-workdir
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -2,6 +2,7 @@
 cmake_minimum_required(VERSION 3.20)
 
 option(TEST_ENABLE "Enable tests" off)
+option(FUZZ_ENABLE "Enable fuzz targets (requires clang with libFuzzer)" off)
 
 if (${TEST_ENABLE})
     project(easyframes)
@@ -95,6 +96,7 @@ add_executable(ef-tests
     test/ef-test.cxx
     test/ef-tests.cxx
     test/test-ef-parse-bytes.cxx
+    test/test-padding.cxx
     test/ifh-ignore.cxx
 )
 
@@ -103,3 +105,27 @@ include(CTest)
 add_test(ef-tests ./ef-tests)
 add_test(parser-tests.rb ${CMAKE_CURRENT_SOURCE_DIR}/test/parser-tests.rb)
 endif()
+
+if (${FUZZ_ENABLE})
+    # libFuzzer's runtime is C++; clang may not find GCC's libstdc++.
+    # Ask GCC for the path as a fallback.
+    find_library(_STDCXX stdc++)
+    if (NOT _STDCXX)
+        execute_process(
+            COMMAND gcc --print-file-name=libstdc++.so
+            OUTPUT_VARIABLE _STDCXX_PATH OUTPUT_STRIP_TRAILING_WHITESPACE)
+        if (_STDCXX_PATH AND NOT _STDCXX_PATH STREQUAL "libstdc++.so")
+            get_filename_component(_STDCXX_DIR "${_STDCXX_PATH}" DIRECTORY)
+        endif()
+    endif()
+
+    foreach(target fuzz-parse-bytes fuzz-argc-frame fuzz-roundtrip)
+        add_executable(${target} fuzz/${target}.c)
+        target_link_libraries(${target} libef stdc++)
+        target_compile_options(${target} PRIVATE -fsanitize=fuzzer,address)
+        target_link_options(${target} PRIVATE -fsanitize=fuzzer,address)
+        if (_STDCXX_DIR)
+            target_link_directories(${target} PRIVATE ${_STDCXX_DIR})
+        endif()
+    endforeach()
+endif()
diff --git a/README.md b/README.md
@@ -96,3 +96,42 @@ To learn more, have a look at the help message below.
     $ sudo make install
 
 
+# Fuzzing
+
+Three [libFuzzer](https://llvm.org/docs/LibFuzzer.html) harnesses exercise
+ef's parsing logic with AddressSanitizer enabled:
+
+- **fuzz-parse-bytes**:  feeds random strings to `parse_bytes()` (numeric,
+  hex, IPv4, IPv6, MAC address parsing)
+- **fuzz-argc-frame**: splits input on null bytes into argv and calls
+  `argc_frame()` (all header and field parsers)
+- **fuzz-roundtrip**: property-based test: parses a frame, serializes it,
+  and asserts that the result matches its own receive filter via
+  `bequal_mask()`. Uses the same input format and corpus as fuzz-argc-frame.
+
+Build (requires clang):
+
+    $ cmake -S . -B build-fuzz -DFUZZ_ENABLE=ON -DCMAKE_C_COMPILER=clang
+    $ cmake --build build-fuzz -j$(nproc)
+
+Run (from build-fuzz/):
+
+    $ cd build-fuzz
+    $ mkdir -p corpus-workdir
+    $ ./fuzz-parse-bytes corpus-workdir ../fuzz/corpus-parse-bytes -dict=../fuzz/ef.dict -max_total_time=1200 -jobs=12 -workers=12
+    $ ./fuzz-argc-frame corpus-workdir ../fuzz/corpus-argc-frame -dict=../fuzz/ef.dict -max_total_time=1200 -jobs=12 -workers=12
+    $ ./fuzz-roundtrip corpus-workdir ../fuzz/corpus-argc-frame -dict=../fuzz/ef.dict -max_total_time=1200 -jobs=12 -workers=12
+
+When two corpus directories are given, libFuzzer reads seeds from both
+but writes new discoveries only to the first. This keeps the checked-in
+seed corpus (`fuzz/corpus-*`) clean. The `corpus-workdir` directory is
+gitignored and can be deleted at any time.
+
+The dictionary helps the fuzzer discover valid keywords. Adjust `-jobs`
+and `-workers` to match available cores. Each job writes its own log to
+`fuzz-<N>.log`.
+
+If a crash is found, libFuzzer writes a `crash-<hash>` file that can be
+reproduced with:
+
+    $ ./fuzz-parse-bytes crash-<hash>
diff --git a/fuzz/corpus-argc-frame/data_ascii b/fuzz/corpus-argc-frame/data_ascii
diff --git a/fuzz/corpus-argc-frame/data_hex b/fuzz/corpus-argc-frame/data_hex
diff --git a/fuzz/corpus-argc-frame/data_pattern_cnt b/fuzz/corpus-argc-frame/data_pattern_cnt
diff --git a/fuzz/corpus-argc-frame/double_vlan b/fuzz/corpus-argc-frame/double_vlan
diff --git a/fuzz/corpus-argc-frame/eth_arp b/fuzz/corpus-argc-frame/eth_arp
diff --git a/fuzz/corpus-argc-frame/eth_basic b/fuzz/corpus-argc-frame/eth_basic
diff --git a/fuzz/corpus-argc-frame/eth_coap b/fuzz/corpus-argc-frame/eth_coap
diff --git a/fuzz/corpus-argc-frame/eth_hsr b/fuzz/corpus-argc-frame/eth_hsr
diff --git a/fuzz/corpus-argc-frame/eth_ign_all b/fuzz/corpus-argc-frame/eth_ign_all
diff --git a/fuzz/corpus-argc-frame/eth_ign_fields b/fuzz/corpus-argc-frame/eth_ign_fields
diff --git a/fuzz/corpus-argc-frame/eth_ign_ipv6 b/fuzz/corpus-argc-frame/eth_ign_ipv6
diff --git a/fuzz/corpus-argc-frame/eth_ipv4 b/fuzz/corpus-argc-frame/eth_ipv4
diff --git a/fuzz/corpus-argc-frame/eth_ipv4_icmp b/fuzz/corpus-argc-frame/eth_ipv4_icmp
diff --git a/fuzz/corpus-argc-frame/eth_ipv4_icmp_fields b/fuzz/corpus-argc-frame/eth_ipv4_icmp_fields
diff --git a/fuzz/corpus-argc-frame/eth_ipv4_igmp b/fuzz/corpus-argc-frame/eth_ipv4_igmp
diff --git a/fuzz/corpus-argc-frame/eth_ipv4_prp b/fuzz/corpus-argc-frame/eth_ipv4_prp
diff --git a/fuzz/corpus-argc-frame/eth_ipv4_tcp b/fuzz/corpus-argc-frame/eth_ipv4_tcp
diff --git a/fuzz/corpus-argc-frame/eth_ipv4_udp b/fuzz/corpus-argc-frame/eth_ipv4_udp
diff --git a/fuzz/corpus-argc-frame/eth_ipv6_mld b/fuzz/corpus-argc-frame/eth_ipv6_mld
diff --git a/fuzz/corpus-argc-frame/eth_ipv6_udp b/fuzz/corpus-argc-frame/eth_ipv6_udp
diff --git a/fuzz/corpus-argc-frame/eth_mrp_lnk b/fuzz/corpus-argc-frame/eth_mrp_lnk
diff --git a/fuzz/corpus-argc-frame/eth_mrp_prop_nack b/fuzz/corpus-argc-frame/eth_mrp_prop_nack
diff --git a/fuzz/corpus-argc-frame/eth_mrp_topo b/fuzz/corpus-argc-frame/eth_mrp_topo
diff --git a/fuzz/corpus-argc-frame/eth_mrp_tst b/fuzz/corpus-argc-frame/eth_mrp_tst
diff --git a/fuzz/corpus-argc-frame/eth_oam_ccm b/fuzz/corpus-argc-frame/eth_oam_ccm
diff --git a/fuzz/corpus-argc-frame/eth_oam_laps b/fuzz/corpus-argc-frame/eth_oam_laps
diff --git a/fuzz/corpus-argc-frame/eth_oam_lb b/fuzz/corpus-argc-frame/eth_oam_lb
diff --git a/fuzz/corpus-argc-frame/eth_oam_lt b/fuzz/corpus-argc-frame/eth_oam_lt
diff --git a/fuzz/corpus-argc-frame/eth_oam_raps b/fuzz/corpus-argc-frame/eth_oam_raps
diff --git a/fuzz/corpus-argc-frame/eth_opcua b/fuzz/corpus-argc-frame/eth_opcua
diff --git a/fuzz/corpus-argc-frame/eth_profinet_rtc b/fuzz/corpus-argc-frame/eth_profinet_rtc
diff --git a/fuzz/corpus-argc-frame/eth_ptp_announce b/fuzz/corpus-argc-frame/eth_ptp_announce
diff --git a/fuzz/corpus-argc-frame/eth_ptp_follow_up b/fuzz/corpus-argc-frame/eth_ptp_follow_up
diff --git a/fuzz/corpus-argc-frame/eth_ptp_peer_request b/fuzz/corpus-argc-frame/eth_ptp_peer_request
diff --git a/fuzz/corpus-argc-frame/eth_ptp_peer_resp_fu b/fuzz/corpus-argc-frame/eth_ptp_peer_resp_fu
diff --git a/fuzz/corpus-argc-frame/eth_ptp_peer_response b/fuzz/corpus-argc-frame/eth_ptp_peer_response
diff --git a/fuzz/corpus-argc-frame/eth_ptp_request b/fuzz/corpus-argc-frame/eth_ptp_request
diff --git a/fuzz/corpus-argc-frame/eth_ptp_response b/fuzz/corpus-argc-frame/eth_ptp_response
diff --git a/fuzz/corpus-argc-frame/eth_ptp_sync b/fuzz/corpus-argc-frame/eth_ptp_sync
diff --git a/fuzz/corpus-argc-frame/eth_rtag_ipv4 b/fuzz/corpus-argc-frame/eth_rtag_ipv4
diff --git a/fuzz/corpus-argc-frame/eth_stag_ctag_ipv4 b/fuzz/corpus-argc-frame/eth_stag_ctag_ipv4
diff --git a/fuzz/corpus-argc-frame/eth_sv b/fuzz/corpus-argc-frame/eth_sv
diff --git a/fuzz/corpus-argc-frame/payload_only b/fuzz/corpus-argc-frame/payload_only
diff --git a/fuzz/corpus-parse-bytes/bin_byte b/fuzz/corpus-parse-bytes/bin_byte
@@ -0,0 +1 @@
+0b10110011
diff --git a/fuzz/corpus-parse-bytes/bin_prefix b/fuzz/corpus-parse-bytes/bin_prefix
@@ -0,0 +1 @@
+0b1111
diff --git a/fuzz/corpus-parse-bytes/decimal b/fuzz/corpus-parse-bytes/decimal
@@ -0,0 +1 @@
+100
diff --git a/fuzz/corpus-parse-bytes/ethertype_oam b/fuzz/corpus-parse-bytes/ethertype_oam
@@ -0,0 +1 @@
+0x8902
diff --git a/fuzz/corpus-parse-bytes/ethertype_ptp b/fuzz/corpus-parse-bytes/ethertype_ptp
@@ -0,0 +1 @@
+0x88f7
diff --git a/fuzz/corpus-parse-bytes/hex_long b/fuzz/corpus-parse-bytes/hex_long
@@ -0,0 +1 @@
+0xdeadbeef
diff --git a/fuzz/corpus-parse-bytes/hex_prefix b/fuzz/corpus-parse-bytes/hex_prefix
@@ -0,0 +1 @@
+0x0800
diff --git a/fuzz/corpus-parse-bytes/int_simple b/fuzz/corpus-parse-bytes/int_simple
@@ -0,0 +1 @@
+5
diff --git a/fuzz/corpus-parse-bytes/ipv4 b/fuzz/corpus-parse-bytes/ipv4
@@ -0,0 +1 @@
+1.2.3.4
diff --git a/fuzz/corpus-parse-bytes/ipv4_private b/fuzz/corpus-parse-bytes/ipv4_private
@@ -0,0 +1 @@
+192.168.1.1
diff --git a/fuzz/corpus-parse-bytes/ipv6_linklocal b/fuzz/corpus-parse-bytes/ipv6_linklocal
@@ -0,0 +1 @@
+fe80::1
diff --git a/fuzz/corpus-parse-bytes/ipv6_multicast b/fuzz/corpus-parse-bytes/ipv6_multicast
@@ -0,0 +1 @@
+ff02::1
diff --git a/fuzz/corpus-parse-bytes/ipv6_short b/fuzz/corpus-parse-bytes/ipv6_short
@@ -0,0 +1 @@
+::1
diff --git a/fuzz/corpus-parse-bytes/mac b/fuzz/corpus-parse-bytes/mac
@@ -0,0 +1 @@
+ff:ff:ff:ff:ff:ff
diff --git a/fuzz/corpus-parse-bytes/mac_oam b/fuzz/corpus-parse-bytes/mac_oam
@@ -0,0 +1 @@
+01:80:c2:00:00:30
diff --git a/fuzz/corpus-parse-bytes/octal b/fuzz/corpus-parse-bytes/octal
@@ -0,0 +1 @@
+0o777
diff --git a/fuzz/corpus-parse-bytes/octal_prefix b/fuzz/corpus-parse-bytes/octal_prefix
@@ -0,0 +1 @@
+0o777
diff --git a/fuzz/corpus-parse-bytes/zero b/fuzz/corpus-parse-bytes/zero
@@ -0,0 +1 @@
+0
diff --git a/fuzz/ef.dict b/fuzz/ef.dict
@@ -0,0 +1,204 @@
+# ef keywords helps libFuzzer discover valid parse paths
+
+# Commands
+"help"
+"hex"
+"ign"
+"ignore"
+"name"
+"pcap"
+"rate"
+"rep"
+"repeat"
+"rx"
+"tx"
+
+# Headers Layer 2
+"ctag"
+"eth"
+"htag"
+"prp"
+"rtag"
+"stag"
+
+# Headers Layer 3/4
+"arp"
+"icmp"
+"igmp"
+"igmpv3_group"
+"ipv4"
+"ipv6"
+"mld"
+"mldv2_group"
+"tcp"
+"udp"
+
+# Headers OAM
+"oam-ccm"
+"oam-laps"
+"oam-lb"
+"oam-lt"
+"oam-raps"
+
+# Headers MRP
+"mrp_lnk"
+"mrp_prop_nack"
+"mrp_topo"
+"mrp_tst"
+
+# Headers PTP
+"ptp-announce"
+"ptp-follow-up"
+"ptp-peer-request"
+"ptp-peer-response"
+"ptp-peer-response-follow-up"
+"ptp-request"
+"ptp-response"
+"ptp-sync"
+"ptp-tlv-org"
+"ptp-tlv-path"
+
+# Headers Industrial / Application
+"coap"
+"coap-opt"
+"coap-parms"
+"opc-ua"
+"profinet-rtc"
+"sv"
+
+# Headers Payload / Padding
+"data"
+"padding"
+
+# Headers IFH (Injection/Extraction Frame Headers)
+"ifh-jr2"
+"ifh-oc1"
+"ifh-sparx5"
+"lp-jr2"
+"lp-oc1"
+"lp-sparx5"
+"sp-jr2"
+"sp-oc1"
+"sp-sparx5"
+
+# Field names Ethernet
+"dmac"
+"smac"
+"et"
+
+# Field names VLAN
+"vid"
+"pcp"
+"dei"
+"seqn"
+"lanid"
+"pathid"
+"recv"
+"suffix"
+"size"
+
+# Field names IPv4
+"ver"
+"ihl"
+"dscp"
+"ecn"
+"id"
+"flags"
+"offset"
+"ttl"
+"proto"
+"chksum"
+"sip"
+"dip"
+
+# Field names IPv6
+"flow"
+"next"
+"hlim"
+
+# Field names TCP/UDP
+"sport"
+"dport"
+"len"
+"seqn"
+"ack"
+"doff"
+"fin"
+"syn"
+"rst"
+"psh"
+"urg"
+"win"
+"urgp"
+
+# Field names ARP
+"htype"
+"ptype"
+"hlen"
+"plen"
+"oper"
+"sha"
+"spa"
+"tha"
+"tpa"
+
+# Field names ICMP
+"type"
+"code"
+"hd"
+
+# Field names IGMP/MLD
+"max_resp"
+"ga"
+"ng"
+"ns"
+"qrv"
+"qqic"
+"rec_type"
+"auxlen"
+
+# Field names PTP
+"hdr-messageType"
+"hdr-versionPTP"
+"hdr-domainNumber"
+"hdr-clockId"
+"hdr-portNumber"
+"hdr-sequenceId"
+"hdr-correctionField"
+"hdr-flagField"
+"hdr-logMessageInterval"
+
+# Field names OAM
+"opcode"
+"mel"
+
+# Parse format keywords
+"ascii"
+"ascii0"
+"pattern"
+"zero"
+"ones"
+"cnt"
+
+# Numeric formats
+"0x"
+"0b"
+"0o"
+"::"
+"0x0800"
+"0x86dd"
+"0x8100"
+"0x88a8"
+"0x88f7"
+"0x8902"
+"0x88e1"
+"ff:ff:ff:ff:ff:ff"
+"01:80:c2:00:00:30"
+"01:19:1b:00:00:00"
+"1.2.3.4"
+"::1"
+"ff02::1"
+"fe80::1"
+"255"
+"1000"
+"0xdeadbeef"