8ad2b0d630
Add some docs for using fuzzing with U-Boot, including building, running tests, and adding new tests. Co-developed-by: Claude <noreply@anthropic.com> Signed-off-by: Simon Glass <sjg@chromium.org>
220 lines
6.3 KiB
ReStructuredText
220 lines
6.3 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0+
|
|
|
|
Building U-Boot with Fuzzing Support
|
|
=====================================
|
|
|
|
U-Boot supports fuzzing through libFuzzer when built for the sandbox
|
|
architecture. Fuzzing helps identify security vulnerabilities and crashes by
|
|
testing with randomly generated inputs.
|
|
|
|
Prerequisites
|
|
-------------
|
|
|
|
The following tools are required:
|
|
|
|
* Clang compiler with fuzzing support
|
|
* libstdc++ development libraries
|
|
|
|
On Ubuntu/Debian systems, install the required packages::
|
|
|
|
sudo apt install clang libstdc++-dev
|
|
|
|
Building with Fuzzing
|
|
---------------------
|
|
|
|
The recommended approach is to use buildman, which handles the configuration
|
|
automatically:
|
|
|
|
1. Build with buildman (recommended)::
|
|
|
|
buildman --bo sandbox -a FUZZ=y -O clang -L -o /tmp/fuzz -w
|
|
|
|
The buildman options:
|
|
|
|
* ``--booard sandbox`` - Build for sandbox board only
|
|
* ``-a FUZZ=y`` - Enable fuzzing support via CONFIG_FUZZ=y
|
|
* ``-O clang`` - Use Clang compiler (required for fuzzing)
|
|
* ``-L`` - Disable LTO to avoid sanitizer coverage linker issues
|
|
* ``-o /tmp/fuzz`` - Output directory
|
|
* ``-w`` - Use the output directory as the work directory
|
|
|
|
Alternative: Manual build
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To build manually with make:
|
|
|
|
1. Configure the build with fuzzing enabled::
|
|
|
|
make HOSTCC=clang CC=clang O=/tmp/fuzz LTO_ENABLE= sandbox_defconfig
|
|
scripts/config --file /tmp/fuzz/.config --enable FUZZ
|
|
|
|
2. Build the fuzzing-enabled binary::
|
|
|
|
make HOSTCC=clang CC=clang O=/tmp/fuzz LTO_ENABLE= -j$(nproc)
|
|
|
|
Build Output
|
|
------------
|
|
|
|
The fuzzing build produces:
|
|
|
|
* ``u-boot`` - Main fuzzing binary with AddressSanitizer and fuzzer
|
|
instrumentation
|
|
* Significantly larger binary size due to instrumentation (typically 40-50MB)
|
|
* Debug symbols included for better crash analysis
|
|
|
|
Fuzzing Architecture
|
|
--------------------
|
|
|
|
The U-Boot fuzzing implementation consists of:
|
|
|
|
* **Fuzzing Engine**: Sandbox-specific driver that interfaces with libFuzzer
|
|
* **Threading Model**: Separate threads for fuzzing harness and U-Boot
|
|
execution
|
|
* **Input Handling**: ``LLVMFuzzerTestOneInput()`` entry point processes
|
|
fuzz inputs
|
|
* **Command Fuzzing**: Tests U-Boot commands with generated inputs via
|
|
``fuzz`` command
|
|
|
|
Key source files:
|
|
|
|
* ``arch/sandbox/cpu/fuzz.c`` - Main fuzzing implementation
|
|
* ``drivers/fuzz/`` - Fuzzing engine drivers
|
|
* ``test/fuzz/`` - Fuzzing test cases
|
|
* ``include/fuzzing_engine.h`` - Fuzzing engine interface
|
|
|
|
Running Fuzz Tests
|
|
------------------
|
|
|
|
To run fuzzing tests, set the test name via environment variable and run the
|
|
fuzzing binary from the build directory:
|
|
|
|
1. Change to the build directory::
|
|
|
|
cd /tmp/fuzz
|
|
|
|
2. Set the fuzz test to run::
|
|
|
|
export UBOOT_SB_FUZZ_TEST=fuzz_vring
|
|
|
|
3. Run the fuzzer::
|
|
|
|
./u-boot
|
|
|
|
The fuzzer will start libFuzzer with coverage-guided input generation. You
|
|
should see output similar to::
|
|
|
|
INFO: Running with entropic power schedule (0xFF, 100).
|
|
INFO: Seed: 1626867009
|
|
INFO: Loaded 1 modules (104150 inline 8-bit counters): ...
|
|
#2 INITED cov: 28 ft: 29 corp: 1/1b exec/s: 0 rss: 318Mb
|
|
#4 NEW cov: 29 ft: 30 corp: 2/3b lim: 4 exec/s: 0 rss: 319Mb
|
|
|
|
Available fuzz tests include:
|
|
|
|
* ``fuzz_vring`` - Tests VirtIO ring buffer handling
|
|
|
|
To stop fuzzing, use Ctrl+C. The fuzzer will automatically save any crash-
|
|
inducing inputs for later analysis.
|
|
|
|
Understanding Fuzzer Output
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The fuzzer output shows:
|
|
|
|
* ``cov: N`` - Number of code coverage points reached
|
|
* ``ft: N`` - Number of features discovered
|
|
* ``corp: N/Mb`` - Corpus size (number of test cases / total bytes)
|
|
* ``exec/s: N`` - Executions per second (performance metric)
|
|
* ``rss: NMb`` - Memory usage
|
|
|
|
Error messages from the target code (like VirtIO "out of range" errors) are
|
|
expected and indicate the fuzzer is finding edge cases.
|
|
|
|
Adding New Fuzz Tests
|
|
---------------------
|
|
|
|
To create a new fuzz test, follow these steps:
|
|
|
|
1. **Create the test file** in ``test/fuzz/`` directory::
|
|
|
|
/* SPDX-License-Identifier: GPL-2.0+ */
|
|
#include <test/fuzz.h>
|
|
|
|
static int fuzz_my_component(const uint8_t *data, size_t size)
|
|
{
|
|
/* Your fuzzing logic here */
|
|
if (size < 4)
|
|
return 0; /* Not enough data */
|
|
|
|
/* Test your component with fuzzed data */
|
|
my_component_function(data, size);
|
|
|
|
return 0;
|
|
}
|
|
FUZZ_TEST(fuzz_my_component, 0);
|
|
|
|
2. **Add to Makefile** in ``test/fuzz/Makefile``::
|
|
|
|
obj-$(CONFIG_MY_COMPONENT) += my_component.o
|
|
|
|
Or for tests that should always be included::
|
|
|
|
obj-y += my_component.o
|
|
|
|
3. **Test the new fuzzer**::
|
|
|
|
export UBOOT_SB_FUZZ_TEST=fuzz_my_component
|
|
./u-boot
|
|
|
|
**Best practices for fuzz tests:**
|
|
|
|
* **Input validation**: Check minimum data size requirements
|
|
* **Error handling**: Handle invalid inputs gracefully, don't panic
|
|
* **Resource cleanup**: Free any allocated resources
|
|
* **Focused testing**: Target specific functions or code paths
|
|
* **Deterministic**: Same input should produce same behavior
|
|
|
|
**Example patterns:**
|
|
|
|
* Parse structured data (protocols, file formats)
|
|
* Test buffer handling with varying sizes
|
|
* Exercise error paths with malformed inputs
|
|
* Stress test with boundary conditions
|
|
|
|
Troubleshooting
|
|
---------------
|
|
|
|
**Linker errors about missing libstdc++**:
|
|
Install libstdc++ development libraries as shown in Prerequisites.
|
|
|
|
**Sanitizer coverage linker errors**:
|
|
Ensure LTO is disabled with ``LTO_ENABLE=`` in the make command.
|
|
|
|
**Build fails with GCC**:
|
|
Fuzzing requires Clang. Ensure both CC and HOSTCC are set to clang.
|
|
|
|
**Fuzzer exits with "fdtdec_setup() failed"**:
|
|
Run the fuzzer from the build directory where u-boot.dtb is located.
|
|
The sandbox requires access to its device tree file.
|
|
|
|
Security Considerations
|
|
-----------------------
|
|
|
|
Fuzzing builds include:
|
|
|
|
* **AddressSanitizer**: Detects buffer overflows, use-after-free, and other
|
|
memory errors
|
|
* **Fuzzer Coverage**: Instruments code for coverage-guided fuzzing
|
|
* **Debug Information**: Retained for crash analysis and debugging
|
|
|
|
These features significantly increase binary size and runtime overhead, making
|
|
fuzzing builds unsuitable for production use.
|
|
|
|
Further Reading
|
|
---------------
|
|
|
|
* :doc:`/arch/sandbox/sandbox` - General sandbox architecture documentation
|
|
* libFuzzer documentation: https://llvm.org/docs/LibFuzzer.html
|
|
* AddressSanitizer documentation:
|
|
https://clang.llvm.org/docs/AddressSanitizer.html
|