One Hat Cyber Team
Your IP :
216.73.216.115
Server IP :
194.44.31.54
Server :
Linux zen.imath.kiev.ua 4.18.0-553.77.1.el8_10.x86_64 #1 SMP Fri Oct 3 14:30:23 UTC 2025 x86_64
Server Software :
Apache/2.4.37 (Rocky Linux) OpenSSL/1.1.1k
PHP Version :
5.6.40
Buat File
|
Buat Folder
Eksekusi
Dir :
~
/
usr
/
share
/
doc
/
qemu-kvm
/
devel
/
View File Name :
fuzzing.html
<!DOCTYPE html> <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Fuzzing — QEMU qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4 documentation</title> <link rel="shortcut icon" href="../_static/qemu_32x32.png"/> <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="next" title="Control-Flow Integrity (CFI)" href="control-flow-integrity.html" /> <link rel="prev" title="Testing in QEMU" href="testing.html" /> <script src="../_static/js/modernizr.min.js"></script> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="../index.html" class="icon icon-home"> QEMU <img src="../_static/qemu_128x128.png" class="logo" alt="Logo"/> </a> <div class="version"> 6.2.0 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="../search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> <p class="caption"><span class="caption-text">Contents:</span></p> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../about/index.html">About QEMU</a></li> <li class="toctree-l1"><a class="reference internal" href="../system/index.html">System Emulation</a></li> <li class="toctree-l1"><a class="reference internal" href="../user/index.html">User Mode Emulation</a></li> <li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Tools</a></li> <li class="toctree-l1"><a class="reference internal" href="../interop/index.html">System Emulation Management and Interoperability</a></li> <li class="toctree-l1"><a class="reference internal" href="../specs/index.html">System Emulation Guest Hardware Specifications</a></li> <li class="toctree-l1 current"><a class="reference internal" href="index.html">Developer Information</a><ul class="current"> <li class="toctree-l2"><a class="reference internal" href="code-of-conduct.html">Code of Conduct</a></li> <li class="toctree-l2"><a class="reference internal" href="conflict-resolution.html">Conflict Resolution Policy</a></li> <li class="toctree-l2"><a class="reference internal" href="build-system.html">The QEMU build system architecture</a></li> <li class="toctree-l2"><a class="reference internal" href="style.html">QEMU Coding Style</a></li> <li class="toctree-l2"><a class="reference internal" href="kconfig.html">QEMU and Kconfig</a></li> <li class="toctree-l2"><a class="reference internal" href="testing.html">Testing in QEMU</a></li> <li class="toctree-l2 current"><a class="current reference internal" href="#">Fuzzing</a><ul> <li class="toctree-l3"><a class="reference internal" href="#basics">Basics</a></li> <li class="toctree-l3"><a class="reference internal" href="#building-the-fuzzers">Building the fuzzers</a></li> <li class="toctree-l3"><a class="reference internal" href="#useful-libfuzzer-flags">Useful libFuzzer flags</a></li> <li class="toctree-l3"><a class="reference internal" href="#generating-coverage-reports">Generating Coverage Reports</a></li> <li class="toctree-l3"><a class="reference internal" href="#adding-a-new-fuzzer">Adding a new fuzzer</a></li> <li class="toctree-l3"><a class="reference internal" href="#the-generic-fuzzer">The Generic Fuzzer</a></li> <li class="toctree-l3"><a class="reference internal" href="#oss-fuzz">OSS-Fuzz</a></li> <li class="toctree-l3"><a class="reference internal" href="#building-crash-reproducers">Building Crash Reproducers</a></li> <li class="toctree-l3"><a class="reference internal" href="#implementation-details-fuzzer-lifecycle">Implementation Details / Fuzzer Lifecycle</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="control-flow-integrity.html">Control-Flow Integrity (CFI)</a></li> <li class="toctree-l2"><a class="reference internal" href="loads-stores.html">Load and Store APIs</a></li> <li class="toctree-l2"><a class="reference internal" href="memory.html">The memory API</a></li> <li class="toctree-l2"><a class="reference internal" href="migration.html">Migration</a></li> <li class="toctree-l2"><a class="reference internal" href="atomics.html">Atomic operations in QEMU</a></li> <li class="toctree-l2"><a class="reference internal" href="stable-process.html">QEMU and the stable process</a></li> <li class="toctree-l2"><a class="reference internal" href="ci.html">CI</a></li> <li class="toctree-l2"><a class="reference internal" href="qtest.html">QTest Device Emulation Testing Framework</a></li> <li class="toctree-l2"><a class="reference internal" href="decodetree.html">Decodetree Specification</a></li> <li class="toctree-l2"><a class="reference internal" href="secure-coding-practices.html">Secure Coding Practices</a></li> <li class="toctree-l2"><a class="reference internal" href="tcg.html">Translator Internals</a></li> <li class="toctree-l2"><a class="reference internal" href="tcg-icount.html">TCG Instruction Counting</a></li> <li class="toctree-l2"><a class="reference internal" href="tracing.html">Tracing</a></li> <li class="toctree-l2"><a class="reference internal" href="multi-thread-tcg.html">Multi-threaded TCG</a></li> <li class="toctree-l2"><a class="reference internal" href="tcg-plugins.html">QEMU TCG Plugins</a></li> <li class="toctree-l2"><a class="reference internal" href="bitops.html">Bitwise operations</a></li> <li class="toctree-l2"><a class="reference internal" href="ui.html">QEMU UI subsystem</a></li> <li class="toctree-l2"><a class="reference internal" href="reset.html">Reset in QEMU: the Resettable interface</a></li> <li class="toctree-l2"><a class="reference internal" href="s390-dasd-ipl.html">Booting from real channel-attached devices on s390x</a></li> <li class="toctree-l2"><a class="reference internal" href="clocks.html">Modelling a clock tree in QEMU</a></li> <li class="toctree-l2"><a class="reference internal" href="qom.html">The QEMU Object Model (QOM)</a></li> <li class="toctree-l2"><a class="reference internal" href="modules.html">QEMU modules</a></li> <li class="toctree-l2"><a class="reference internal" href="block-coroutine-wrapper.html">block-coroutine-wrapper</a></li> <li class="toctree-l2"><a class="reference internal" href="multi-process.html">Multi-process QEMU</a></li> <li class="toctree-l2"><a class="reference internal" href="ebpf_rss.html">eBPF RSS virtio-net support</a></li> <li class="toctree-l2"><a class="reference internal" href="vfio-migration.html">VFIO device Migration</a></li> <li class="toctree-l2"><a class="reference internal" href="qapi-code-gen.html">How to use the QAPI code generator</a></li> <li class="toctree-l2"><a class="reference internal" href="writing-monitor-commands.html">How to write monitor commands</a></li> <li class="toctree-l2"><a class="reference internal" href="trivial-patches.html">Trivial Patches</a></li> <li class="toctree-l2"><a class="reference internal" href="submitting-a-patch.html">Submitting a Patch</a></li> <li class="toctree-l2"><a class="reference internal" href="submitting-a-pull-request.html">Submitting a Pull Request</a></li> </ul> </li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="top navigation"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="../index.html">QEMU</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="../index.html">Docs</a> »</li> <li><a href="index.html">Developer Information</a> »</li> <li>Fuzzing</li> <li class="wy-breadcrumbs-aside"> <a href="https://gitlab.com/qemu-project/qemu/blob/master/docs/devel/fuzzing.rst" class="fa fa-gitlab"> Edit on GitLab</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="fuzzing"> <h1>Fuzzing<a class="headerlink" href="#fuzzing" title="Permalink to this headline">¶</a></h1> <p>This document describes the virtual-device fuzzing infrastructure in QEMU and how to use it to implement additional fuzzers.</p> <div class="section" id="basics"> <h2>Basics<a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2> <p>Fuzzing operates by passing inputs to an entry point/target function. The fuzzer tracks the code coverage triggered by the input. Based on these findings, the fuzzer mutates the input and repeats the fuzzing.</p> <p>To fuzz QEMU, we rely on libfuzzer. Unlike other fuzzers such as AFL, libfuzzer is an <em>in-process</em> fuzzer. For the developer, this means that it is their responsibility to ensure that state is reset between fuzzing-runs.</p> </div> <div class="section" id="building-the-fuzzers"> <h2>Building the fuzzers<a class="headerlink" href="#building-the-fuzzers" title="Permalink to this headline">¶</a></h2> <p><em>NOTE</em>: If possible, build a 32-bit binary. When forking, the 32-bit fuzzer is much faster, since the page-map has a smaller size. This is due to the fact that AddressSanitizer maps ~20TB of memory, as part of its detection. This results in a large page-map, and a much slower <code class="docutils literal notranslate"><span class="pre">fork()</span></code>.</p> <p>To build the fuzzers, install a recent version of clang: Configure with (substitute the clang binaries with the version you installed). Here, enable-sanitizers, is optional but it allows us to reliably detect bugs such as out-of-bounds accesses, use-after-frees, double-frees etc.:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">CC</span><span class="o">=</span><span class="n">clang</span><span class="o">-</span><span class="mi">8</span> <span class="n">CXX</span><span class="o">=</span><span class="n">clang</span><span class="o">++-</span><span class="mi">8</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">configure</span> <span class="o">--</span><span class="n">enable</span><span class="o">-</span><span class="n">fuzzing</span> \ <span class="o">--</span><span class="n">enable</span><span class="o">-</span><span class="n">sanitizers</span> </pre></div> </div> <p>Fuzz targets are built similarly to system targets:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">qemu</span><span class="o">-</span><span class="n">fuzz</span><span class="o">-</span><span class="n">i386</span> </pre></div> </div> <p>This builds <code class="docutils literal notranslate"><span class="pre">./qemu-fuzz-i386</span></code></p> <p>The first option to this command is: <code class="docutils literal notranslate"><span class="pre">--fuzz-target=FUZZ_NAME</span></code> To list all of the available fuzzers run <code class="docutils literal notranslate"><span class="pre">qemu-fuzz-i386</span></code> with no arguments.</p> <p>For example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">qemu</span><span class="o">-</span><span class="n">fuzz</span><span class="o">-</span><span class="n">i386</span> <span class="o">--</span><span class="n">fuzz</span><span class="o">-</span><span class="n">target</span><span class="o">=</span><span class="n">virtio</span><span class="o">-</span><span class="n">scsi</span><span class="o">-</span><span class="n">fuzz</span> </pre></div> </div> <p>Internally, libfuzzer parses all arguments that do not begin with <code class="docutils literal notranslate"><span class="pre">"--"</span></code>. Information about these is available by passing <code class="docutils literal notranslate"><span class="pre">-help=1</span></code></p> <p>Now the only thing left to do is wait for the fuzzer to trigger potential crashes.</p> </div> <div class="section" id="useful-libfuzzer-flags"> <h2>Useful libFuzzer flags<a class="headerlink" href="#useful-libfuzzer-flags" title="Permalink to this headline">¶</a></h2> <p>As mentioned above, libFuzzer accepts some arguments. Passing <code class="docutils literal notranslate"><span class="pre">-help=1</span></code> will list the available arguments. In particular, these arguments might be helpful:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">CORPUS_DIR/</span></code> : Specify a directory as the last argument to libFuzzer. libFuzzer stores each “interesting” input in this corpus directory. The next time you run libFuzzer, it will read all of the inputs from the corpus, and continue fuzzing from there. You can also specify multiple directories. libFuzzer loads existing inputs from all specified directories, but will only write new ones to the first one specified.</li> <li><code class="docutils literal notranslate"><span class="pre">-max_len=4096</span></code> : specify the maximum byte-length of the inputs libFuzzer will generate.</li> <li><code class="docutils literal notranslate"><span class="pre">-close_fd_mask={1,2,3}</span></code> : close, stderr, or both. Useful for targets that trigger many debug/error messages, or create output on the serial console.</li> <li><code class="docutils literal notranslate"><span class="pre">-jobs=4</span> <span class="pre">-workers=4</span></code> : These arguments configure libFuzzer to run 4 fuzzers in parallel (4 fuzzing jobs in 4 worker processes). Alternatively, with only <code class="docutils literal notranslate"><span class="pre">-jobs=N</span></code>, libFuzzer automatically spawns a number of workers less than or equal to half the available CPU cores. Replace 4 with a number appropriate for your machine. Make sure to specify a <code class="docutils literal notranslate"><span class="pre">CORPUS_DIR</span></code>, which will allow the parallel fuzzers to share information about the interesting inputs they find.</li> <li><code class="docutils literal notranslate"><span class="pre">-use_value_profile=1</span></code> : For each comparison operation, libFuzzer computes <code class="docutils literal notranslate"><span class="pre">(caller_pc&4095)</span> <span class="pre">|</span> <span class="pre">(popcnt(Arg1</span> <span class="pre">^</span> <span class="pre">Arg2)</span> <span class="pre"><<</span> <span class="pre">12)</span></code> and places this in the coverage table. Useful for targets with “magic” constants. If Arg1 came from the fuzzer’s input and Arg2 is a magic constant, then each time the Hamming distance between Arg1 and Arg2 decreases, libFuzzer adds the input to the corpus.</li> <li><code class="docutils literal notranslate"><span class="pre">-shrink=1</span></code> : Tries to make elements of the corpus “smaller”. Might lead to better coverage performance, depending on the target.</li> </ul> <p>Note that libFuzzer’s exact behavior will depend on the version of clang and libFuzzer used to build the device fuzzers.</p> </div> <div class="section" id="generating-coverage-reports"> <h2>Generating Coverage Reports<a class="headerlink" href="#generating-coverage-reports" title="Permalink to this headline">¶</a></h2> <p>Code coverage is a crucial metric for evaluating a fuzzer’s performance. libFuzzer’s output provides a “cov: ” column that provides a total number of unique blocks/edges covered. To examine coverage on a line-by-line basis we can use Clang coverage:</p> <blockquote> <div><ol class="arabic"> <li><p class="first">Configure libFuzzer to store a corpus of all interesting inputs (see CORPUS_DIR above)</p> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">./configure</span></code> the QEMU build with</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">--</span><span class="n">enable</span><span class="o">-</span><span class="n">fuzzing</span> \ <span class="o">--</span><span class="n">extra</span><span class="o">-</span><span class="n">cflags</span><span class="o">=</span><span class="s2">"-fprofile-instr-generate -fcoverage-mapping"</span> </pre></div> </div> </li> <li><p class="first">Re-run the fuzzer. Specify $CORPUS_DIR/* as an argument, telling libfuzzer to execute all of the inputs in $CORPUS_DIR and exit. Once the process exits, you should find a file, “default.profraw” in the working directory.</p> </li> <li><p class="first">Execute these commands to generate a detailed HTML coverage-report:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">llvm</span><span class="o">-</span><span class="n">profdata</span> <span class="n">merge</span> <span class="o">-</span><span class="n">output</span><span class="o">=</span><span class="n">default</span><span class="o">.</span><span class="n">profdata</span> <span class="n">default</span><span class="o">.</span><span class="n">profraw</span> <span class="n">llvm</span><span class="o">-</span><span class="n">cov</span> <span class="n">show</span> <span class="o">./</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">qemu</span><span class="o">-</span><span class="n">fuzz</span><span class="o">-</span><span class="n">i386</span> <span class="o">-</span><span class="n">instr</span><span class="o">-</span><span class="n">profile</span><span class="o">=</span><span class="n">default</span><span class="o">.</span><span class="n">profdata</span> \ <span class="o">--</span><span class="nb">format</span> <span class="n">html</span> <span class="o">-</span><span class="n">output</span><span class="o">-</span><span class="nb">dir</span><span class="o">=/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">output</span><span class="o">/</span><span class="n">report</span> </pre></div> </div> </li> </ol> </div></blockquote> </div> <div class="section" id="adding-a-new-fuzzer"> <h2>Adding a new fuzzer<a class="headerlink" href="#adding-a-new-fuzzer" title="Permalink to this headline">¶</a></h2> <p>Coverage over virtual devices can be improved by adding additional fuzzers. Fuzzers are kept in <code class="docutils literal notranslate"><span class="pre">tests/qtest/fuzz/</span></code> and should be added to <code class="docutils literal notranslate"><span class="pre">tests/qtest/fuzz/meson.build</span></code></p> <p>Fuzzers can rely on both qtest and libqos to communicate with virtual devices.</p> <ol class="arabic simple"> <li>Create a new source file. For example <code class="docutils literal notranslate"><span class="pre">tests/qtest/fuzz/foo-device-fuzz.c</span></code>.</li> <li>Write the fuzzing code using the libqtest/libqos API. See existing fuzzers for reference.</li> <li>Add the fuzzer to <code class="docutils literal notranslate"><span class="pre">tests/qtest/fuzz/meson.build</span></code>.</li> </ol> <p>Fuzzers can be more-or-less thought of as special qtest programs which can modify the qtest commands and/or qtest command arguments based on inputs provided by libfuzzer. Libfuzzer passes a byte array and length. Commonly the fuzzer loops over the byte-array interpreting it as a list of qtest commands, addresses, or values.</p> </div> <div class="section" id="the-generic-fuzzer"> <h2>The Generic Fuzzer<a class="headerlink" href="#the-generic-fuzzer" title="Permalink to this headline">¶</a></h2> <p>Writing a fuzz target can be a lot of effort (especially if a device driver has not be built-out within libqos). Many devices can be fuzzed to some degree, without any device-specific code, using the generic-fuzz target.</p> <p>The generic-fuzz target is capable of fuzzing devices over their PIO, MMIO, and DMA input-spaces. To apply the generic-fuzz to a device, we need to define two env-variables, at minimum:</p> <ul> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">QEMU_FUZZ_ARGS=</span></code> is the set of QEMU arguments used to configure a machine, with the device attached. For example, if we want to fuzz the virtio-net device attached to a pc-i440fx machine, we can specify:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">QEMU_FUZZ_ARGS</span><span class="o">=</span><span class="s2">"-M pc -nodefaults -netdev user,id=user0 </span><span class="se">\</span> <span class="s2">-device virtio-net,netdev=user0"</span> </pre></div> </div> </li> <li><p class="first"><code class="docutils literal notranslate"><span class="pre">QEMU_FUZZ_OBJECTS=</span></code> is a set of space-delimited strings used to identify the MemoryRegions that will be fuzzed. These strings are compared against MemoryRegion names and MemoryRegion owner names, to decide whether each MemoryRegion should be fuzzed. These strings support globbing. For the virtio-net example, we could use one of</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">QEMU_FUZZ_OBJECTS</span><span class="o">=</span><span class="s1">'virtio-net'</span> <span class="n">QEMU_FUZZ_OBJECTS</span><span class="o">=</span><span class="s1">'virtio*'</span> <span class="n">QEMU_FUZZ_OBJECTS</span><span class="o">=</span><span class="s1">'virtio* pcspk'</span> <span class="c1"># Fuzz the virtio devices and the speaker</span> <span class="n">QEMU_FUZZ_OBJECTS</span><span class="o">=</span><span class="s1">'*'</span> <span class="c1"># Fuzz the whole machine``</span> </pre></div> </div> </li> </ul> <p>The <code class="docutils literal notranslate"><span class="pre">"info</span> <span class="pre">mtree"</span></code> and <code class="docutils literal notranslate"><span class="pre">"info</span> <span class="pre">qom-tree"</span></code> monitor commands can be especially useful for identifying the <code class="docutils literal notranslate"><span class="pre">MemoryRegion</span></code> and <code class="docutils literal notranslate"><span class="pre">Object</span></code> names used for matching.</p> <p>As a generic rule-of-thumb, the more <code class="docutils literal notranslate"><span class="pre">MemoryRegions</span></code>/Devices we match, the greater the input-space, and the smaller the probability of finding crashing inputs for individual devices. As such, it is usually a good idea to limit the fuzzer to only a few <code class="docutils literal notranslate"><span class="pre">MemoryRegions</span></code>.</p> <p>To ensure that these env variables have been configured correctly, we can use:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">qemu</span><span class="o">-</span><span class="n">fuzz</span><span class="o">-</span><span class="n">i386</span> <span class="o">--</span><span class="n">fuzz</span><span class="o">-</span><span class="n">target</span><span class="o">=</span><span class="n">generic</span><span class="o">-</span><span class="n">fuzz</span> <span class="o">-</span><span class="n">runs</span><span class="o">=</span><span class="mi">0</span> </pre></div> </div> <p>The output should contain a complete list of matched MemoryRegions.</p> </div> <div class="section" id="oss-fuzz"> <h2>OSS-Fuzz<a class="headerlink" href="#oss-fuzz" title="Permalink to this headline">¶</a></h2> <p>QEMU is continuously fuzzed on <a class="reference external" href="https://github.com/google/oss-fuzz">OSS-Fuzz</a>. By default, the OSS-Fuzz build will try to fuzz every fuzz-target. Since the generic-fuzz target requires additional information provided in environment variables, we pre-define some generic-fuzz configs in <code class="docutils literal notranslate"><span class="pre">tests/qtest/fuzz/generic_fuzz_configs.h</span></code>. Each config must specify:</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">.name</span></code>: To identify the fuzzer config</li> <li><code class="docutils literal notranslate"><span class="pre">.args</span></code> OR <code class="docutils literal notranslate"><span class="pre">.argfunc</span></code>: A string or pointer to a function returning a string. These strings are used to specify the <code class="docutils literal notranslate"><span class="pre">QEMU_FUZZ_ARGS</span></code> environment variable. <code class="docutils literal notranslate"><span class="pre">argfunc</span></code> is useful when the config relies on e.g. a dynamically created temp directory, or a free tcp/udp port.</li> <li><code class="docutils literal notranslate"><span class="pre">.objects</span></code>: A string that specifies the <code class="docutils literal notranslate"><span class="pre">QEMU_FUZZ_OBJECTS</span></code> environment variable.</li> </ul> <p>To fuzz additional devices/device configuration on OSS-Fuzz, send patches for either a new device-specific fuzzer or a new generic-fuzz config.</p> <p>Build details:</p> <ul class="simple"> <li>The Dockerfile that sets up the environment for building QEMU’s fuzzers on OSS-Fuzz can be fund in the OSS-Fuzz repository __(<a class="reference external" href="https://github.com/google/oss-fuzz/blob/master/projects/qemu/Dockerfile">https://github.com/google/oss-fuzz/blob/master/projects/qemu/Dockerfile</a>)</li> <li>The script responsible for building the fuzzers can be found in the QEMU source tree at <code class="docutils literal notranslate"><span class="pre">scripts/oss-fuzz/build.sh</span></code></li> </ul> </div> <div class="section" id="building-crash-reproducers"> <h2>Building Crash Reproducers<a class="headerlink" href="#building-crash-reproducers" title="Permalink to this headline">¶</a></h2> <p>When we find a crash, we should try to create an independent reproducer, that can be used on a non-fuzzer build of QEMU. This filters out any potential false-positives, and improves the debugging experience for developers. Here are the steps for building a reproducer for a crash found by the generic-fuzz target.</p> <ul> <li><p class="first">Ensure the crash reproduces:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">qemu</span><span class="o">-</span><span class="n">fuzz</span><span class="o">-</span><span class="n">i386</span> <span class="o">--</span><span class="n">fuzz</span><span class="o">-</span><span class="n">target</span><span class="o">...</span> <span class="o">./</span><span class="n">crash</span><span class="o">-...</span> </pre></div> </div> </li> <li><p class="first">Gather the QTest output for the crash:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">QEMU_FUZZ_TIMEOUT</span><span class="o">=</span><span class="mi">0</span> <span class="n">QTEST_LOG</span><span class="o">=</span><span class="mi">1</span> <span class="n">FUZZ_SERIALIZE_QTEST</span><span class="o">=</span><span class="mi">1</span> \ <span class="n">qemu</span><span class="o">-</span><span class="n">fuzz</span><span class="o">-</span><span class="n">i386</span> <span class="o">--</span><span class="n">fuzz</span><span class="o">-</span><span class="n">target</span><span class="o">...</span> <span class="o">./</span><span class="n">crash</span><span class="o">-...</span> <span class="o">&></span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">trace</span> </pre></div> </div> </li> <li><p class="first">Reorder and clean-up the resulting trace:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">scripts</span><span class="o">/</span><span class="n">oss</span><span class="o">-</span><span class="n">fuzz</span><span class="o">/</span><span class="n">reorder_fuzzer_qtest_trace</span><span class="o">.</span><span class="n">py</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">trace</span> <span class="o">></span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">reproducer</span> </pre></div> </div> </li> <li><p class="first">Get the arguments needed to start qemu, and provide a path to qemu:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">less</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">trace</span> <span class="c1"># The args should be logged at the top of this file</span> <span class="n">export</span> <span class="n">QEMU_ARGS</span><span class="o">=</span><span class="s2">"-machine ..."</span> <span class="n">export</span> <span class="n">QEMU_PATH</span><span class="o">=</span><span class="s2">"path/to/qemu-system"</span> </pre></div> </div> </li> <li><p class="first">Ensure the crash reproduces in qemu-system:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$QEMU_PATH $QEMU_ARGS -qtest stdio < /tmp/reproducer </pre></div> </div> </li> <li><p class="first">From the crash output, obtain some string that identifies the crash. This can be a line in the stack-trace, for example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">CRASH_TOKEN</span><span class="o">=</span><span class="s2">"hw/usb/hcd-xhci.c:1865"</span> </pre></div> </div> </li> <li><p class="first">Minimize the reproducer:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">scripts</span><span class="o">/</span><span class="n">oss</span><span class="o">-</span><span class="n">fuzz</span><span class="o">/</span><span class="n">minimize_qtest_trace</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">M1</span> <span class="o">-</span><span class="n">M2</span> \ <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">reproducer</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">reproducer</span><span class="o">-</span><span class="n">minimized</span> </pre></div> </div> </li> <li><p class="first">Confirm that the minimized reproducer still crashes:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$QEMU_PATH $QEMU_ARGS -qtest stdio < /tmp/reproducer-minimized </pre></div> </div> </li> <li><p class="first">Create a one-liner reproducer that can be sent over email:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">scripts</span><span class="o">/</span><span class="n">oss</span><span class="o">-</span><span class="n">fuzz</span><span class="o">/</span><span class="n">output_reproducer</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">bash</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">reproducer</span><span class="o">-</span><span class="n">minimized</span> </pre></div> </div> </li> <li><p class="first">Output the C source code for a test case that will reproduce the bug:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">scripts</span><span class="o">/</span><span class="n">oss</span><span class="o">-</span><span class="n">fuzz</span><span class="o">/</span><span class="n">output_reproducer</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">owner</span> <span class="s2">"John Smith <john@smith.com>"</span>\ <span class="o">-</span><span class="n">name</span> <span class="s2">"test_function_name"</span> <span class="o">/</span><span class="n">tmp</span><span class="o">/</span><span class="n">reproducer</span><span class="o">-</span><span class="n">minimized</span> </pre></div> </div> </li> <li><p class="first">Report the bug and send a patch with the C reproducer upstream</p> </li> </ul> </div> <div class="section" id="implementation-details-fuzzer-lifecycle"> <h2>Implementation Details / Fuzzer Lifecycle<a class="headerlink" href="#implementation-details-fuzzer-lifecycle" title="Permalink to this headline">¶</a></h2> <p>The fuzzer has two entrypoints that libfuzzer calls. libfuzzer provides it’s own <code class="docutils literal notranslate"><span class="pre">main()</span></code>, which performs some setup, and calls the entrypoints:</p> <p><code class="docutils literal notranslate"><span class="pre">LLVMFuzzerInitialize</span></code>: called prior to fuzzing. Used to initialize all of the necessary state</p> <p><code class="docutils literal notranslate"><span class="pre">LLVMFuzzerTestOneInput</span></code>: called for each fuzzing run. Processes the input and resets the state at the end of each run.</p> <p>In more detail:</p> <p><code class="docutils literal notranslate"><span class="pre">LLVMFuzzerInitialize</span></code> parses the arguments to the fuzzer (must start with two dashes, so they are ignored by libfuzzer <code class="docutils literal notranslate"><span class="pre">main()</span></code>). Currently, the arguments select the fuzz target. Then, the qtest client is initialized. If the target requires qos, qgraph is set up and the QOM/LIBQOS modules are initialized. Then the QGraph is walked and the QEMU cmd_line is determined and saved.</p> <p>After this, the <code class="docutils literal notranslate"><span class="pre">vl.c:qemu_main</span></code> is called to set up the guest. There are target-specific hooks that can be called before and after qemu_main, for additional setup(e.g. PCI setup, or VM snapshotting).</p> <p><code class="docutils literal notranslate"><span class="pre">LLVMFuzzerTestOneInput</span></code>: Uses qtest/qos functions to act based on the fuzz input. It is also responsible for manually calling <code class="docutils literal notranslate"><span class="pre">main_loop_wait</span></code> to ensure that bottom halves are executed and any cleanup required before the next input.</p> <p>Since the same process is reused for many fuzzing runs, QEMU state needs to be reset at the end of each run. There are currently two implemented options for resetting state:</p> <ul> <li><p class="first">Reboot the guest between runs. - <em>Pros</em>: Straightforward and fast for simple fuzz targets.</p> <ul class="simple"> <li><em>Cons</em>: Depending on the device, does not reset all device state. If the device requires some initialization prior to being ready for fuzzing (common for QOS-based targets), this initialization needs to be done after each reboot.</li> <li><em>Example target</em>: <code class="docutils literal notranslate"><span class="pre">i440fx-qtest-reboot-fuzz</span></code></li> </ul> </li> <li><dl class="first docutils"> <dt>Run each test case in a separate forked process and copy the coverage</dt> <dd><p class="first last">information back to the parent. This is fairly similar to AFL’s “deferred” fork-server mode [3]</p> </dd> </dl> <ul class="simple"> <li><em>Pros</em>: Relatively fast. Devices only need to be initialized once. No need to do slow reboots or vmloads.</li> <li><dl class="first docutils"> <dt><em>Cons</em>: Not officially supported by libfuzzer. Does not work well for</dt> <dd>devices that rely on dedicated threads.</dd> </dl> </li> <li><em>Example target</em>: <code class="docutils literal notranslate"><span class="pre">virtio-net-fork-fuzz</span></code></li> </ul> </li> </ul> </div> </div> </div> </div> <footer> <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> <a href="control-flow-integrity.html" class="btn btn-neutral float-right" title="Control-Flow Integrity (CFI)" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a> <a href="testing.html" class="btn btn-neutral" title="Testing in QEMU" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a> </div> <hr/> <div role="contentinfo"> <p> © Copyright 2021, The QEMU Project Developers. </p> </div> Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. <!-- Empty para to force a blank line after "Built with Sphinx ..." --> <p></p> <p>This documentation is for QEMU version 6.2.0.</p> <p><a href="../about/license.html">QEMU and this manual are released under the GNU General Public License, version 2.</a></p> </footer> </div> </div> </section> </div> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT:'../', VERSION:'qemu-kvm-6.2.0-53.module+el8.10.0+2055+8eb7870b.4', LANGUAGE:'None', COLLAPSE_INDEX:false, FILE_SUFFIX:'.html', HAS_SOURCE: false, SOURCELINK_SUFFIX: '.txt' }; </script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <script type="text/javascript" src="../_static/js/theme.js"></script> <script type="text/javascript"> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>