Deploying to gh-pages from @ 1f5373e 🚀

_sources/tutorials/linux/dvkm/results.md.txt

@@ -222,7 +222,7 @@ The `kafl debug` subcommand provides various utilities for debugging your fuzzin
 
 By using this subcommand, you can replay payloads to better understand the control flow leading to a crash, verify the stability and determinism of a payload, and even debug the guest state live while replaying the payload.
 
-In this section, we'll explore two key [`actions`](../../../reference/fuzzer_configuration.md#action) provided by the kafl debug subcommand:
+In this section, we'll explore two key [`actions`](../../../reference/fuzzer_configuration.md#action) provided by `kafl debug`:
 
 - `single`
 - `gdb`
@@ -234,9 +234,7 @@ The `single` action let's you replay a single payload and observe its results:
 The payload should be specified throught the [`--input`](../../../reference/fuzzer_configuration.md#input) parameter.
 
 :::{Important}
-We should always specify [`--resume`](../../../reference/fuzzer_configuration.md#resume) when using either `kafl cov` or `kafl debug`, since it will replay from the original snapshot taken by the first call on [`NEXT_PAYLAOD`](../../../reference/hypercall_api.md#next_payload), and will make our execution deterministic.
-
-That's one of the key benefits of snapshot fuzzers !
+When replaying a payload from an previous kAFL run at $KAFL_WORKDIR, it is recommended to use [`--resume`](../../../reference/fuzzer_configuration.md#resume) so that the tool will use the exact same snapshot and page cache as in the fuzzing run. This improves our odds at reproducing the crash. If the workdir does not exist anymore or the snapshot is not found, running kafl single without `--resume` will simply boot a new VM with the given configuration and execute the agent a single time with the given input.
 :::
 
 :::{code-block} shell
@@ -396,7 +394,7 @@ For example when the target code will be fixed, we could replay that payload and
 
 The `gdb` action is particularly valuable for deep-diving into the issues discovered during fuzzing.
 
-When using this action, QEMU is started in `gdbserver` mode, which allows it to act as a server for the GDB debugger. This means you can interact with the target application in real-time as the payload is being executed.
+This action working similar to `single`, but QEMU is started in `gdbserver` mode, allowing it to act as a server for the GDB debugger. This means you can interact with the target application in real-time as the payload is being executed.
 
 The use of GDB provides fine-grained control over the execution of the program and allows you to inspect the program's state, variables, and call stack, offering a clear view into what led to a particular crash or unexpected behavior.
 
@@ -580,16 +578,15 @@ Breakpoint 2, oops_enter () at kernel/panic.c:623
 
 :::{Important}
 We need to use GDB hardware breakpoints, as software breakpoints in QEMU's embedded GDB server seems unrealiable.
-
-::::{Note}
+:::
+:::{Note}
 To reach the `dvkm_ioctl` hardware breakpoint, we had to send a `CTRL-C` to the GDB client.
 The execution was hanging somewhere, for reasons that are not clear at the time of this writing.
-::::
-::::{Note}
-Also remember that in order to load the symbols reliably, at the same location, we had to disable the Kernel `ASLR`.
+:::
+:::{Note}
+Additionaly, in order to load the symbols reliably, at the same location, Kernel `ASLR` (_Address Space Layout Randomization_) had to be disabled.
 
 Have a look at the `kafl.yaml` `qemu_append` line, where [`nokaslr`](https://www.kernel.org/doc/html/v4.14/admin-guide/kernel-parameters.html) option is set.
-::::
 :::
 
 Hopefully by now, you should have a better understanding of the kAFL workdir's corpus directory, the captured logs and how to interpret them, as well as having the capacity to replay payloads as you will !

_sources/tutorials/linux/dvkm/target.md.txt

@@ -2,7 +2,7 @@
 
 ## Objectives
 
-The aim is to fuzz the [DVKM (Damned Vulnerable Kernel Module)](https://github.com/hardik05/Damn_Vulnerable_Kernel_Module), an example kernel module developed by[Hardik Shah](https://github.com/hardik05).
+The aim is to fuzz the [DVKM (Damned Vulnerable Kernel Module)](https://github.com/hardik05/Damn_Vulnerable_Kernel_Module), an example kernel module developed by [Hardik Shah](https://github.com/hardik05).
 
 Designed for fuzzing training, DVKM contains deliberately vulnerable code that exposes to a range of security vulnerabilities, including:
 - integer overflow / underflow

_sources/tutorials/linux/dvkm/workflow.md.txt

@@ -59,16 +59,14 @@ Additionally, you must set up a communication channel with the VM. Several optio
 - [Ansible playbook](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)
 
 :::{note}
-If you want to have a look at this kind of workflow, the [Windows driver](../../windows/driver/index.md) target is a good example.
-
-It combines [Packer](https://www.packer.io/), [Vagrant](https://www.vagrantup.com/), and [Ansible](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html) with [WinRM](https://learn.microsoft.com/en-us/windows/win32/winrm/portal) channel to provide a convenient setup.
+The [Windows driver](../../windows/driver/index.md) example target demonstrates how to combine [Packer](https://www.packer.io/), [Vagrant](https://www.vagrantup.com/), and [Ansible](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html) with [WinRM](https://learn.microsoft.com/en-us/windows/win32/winrm/portal) channel to provide a convenient setup.
 :::
 
 ### Direct Kernel Boot and initrd
 
-For targets that are kernel-based, such as ours, a more efficient approach is to use QEMU's [Direct Linux Boot](https://qemu-project.gitlab.io/qemu/system/linuxboot.html) feature in tandem with a custom initrd.
+Open source kernel and firmware targets can often be booted using QEMU's [Direct Linux Boot](https://qemu-project.gitlab.io/qemu/system/linuxboot.html) feature.
 
-This configuration forms a lightweight execution environment that can bypass the need for a full OS image.
+This approach is often more efficient than bootng a full-VM image and easier to customize and script.
 
 ```{code-block} shell
 ---
@@ -77,8 +75,6 @@ caption: Example using `qemu_kernel` (`--kernel`) and `qemu_initrd` (`--initrd`)
 (venv) $ kafl fuzz --kernel /path/to/linux/arch/x86/boot/bzImage --initrd /path/to/initrd.cpio.gz
 ```
 
-Below, we outline how to construct an efficient development workflow leveraging this approach.
-
 ## Initrd and `agent.sh` workflow
 
 The approach outlined here relies on crafting a custom initrd that boots into a minimal BusyBox root filesystem.

tutorials/linux/dvkm/results.html

@@ -462,7 +462,7 @@ <h2>Crash logs<a class="headerlink" href="#crash-logs" title="Link to this headi
 <h2><code class="docutils literal notranslate"><span class="pre">kafl</span> <span class="pre">debug</span></code><a class="headerlink" href="#kafl-debug" title="Link to this heading">#</a></h2>
 <p>The <code class="docutils literal notranslate"><span class="pre">kafl</span> <span class="pre">debug</span></code> subcommand provides various utilities for debugging your fuzzing campaign.</p>
 <p>By using this subcommand, you can replay payloads to better understand the control flow leading to a crash, verify the stability and determinism of a payload, and even debug the guest state live while replaying the payload.</p>
-<p>In this section, we’ll explore two key <a class="reference internal" href="../../../reference/fuzzer_configuration.html#action"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">actions</span></code></span></a> provided by the kafl debug subcommand:</p>
+<p>In this section, we’ll explore two key <a class="reference internal" href="../../../reference/fuzzer_configuration.html#action"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">actions</span></code></span></a> provided by <code class="docutils literal notranslate"><span class="pre">kafl</span> <span class="pre">debug</span></code>:</p>
 <ul class="simple">
 <li><p><code class="docutils literal notranslate"><span class="pre">single</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">gdb</span></code></p></li>
@@ -473,8 +473,7 @@ <h3>Action <code class="docutils literal notranslate"><span class="pre">single</
 <p>The payload should be specified throught the <a class="reference internal" href="../../../reference/fuzzer_configuration.html#input"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">--input</span></code></span></a> parameter.</p>
 <div class="admonition important">
 <p class="admonition-title">Important</p>
-<p>We should always specify <a class="reference internal" href="../../../reference/fuzzer_configuration.html#resume"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">--resume</span></code></span></a> when using either <code class="docutils literal notranslate"><span class="pre">kafl</span> <span class="pre">cov</span></code> or <code class="docutils literal notranslate"><span class="pre">kafl</span> <span class="pre">debug</span></code>, since it will replay from the original snapshot taken by the first call on <a class="reference internal" href="../../../reference/hypercall_api.html#next-payload"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">NEXT_PAYLAOD</span></code></span></a>, and will make our execution deterministic.</p>
-<p>That’s one of the key benefits of snapshot fuzzers !</p>
+<p>When replaying a payload from an previous kAFL run at $KAFL_WORKDIR, it is recommended to use <a class="reference internal" href="../../../reference/fuzzer_configuration.html#resume"><span class="std std-ref"><code class="docutils literal notranslate"><span class="pre">--resume</span></code></span></a> so that the tool will use the exact same snapshot and page cache as in the fuzzing run. This improves our odds at reproducing the crash. If the workdir does not exist anymore or the snapshot is not found, running kafl single without <code class="docutils literal notranslate"><span class="pre">--resume</span></code> will simply boot a new VM with the given configuration and execute the agent a single time with the given input.</p>
 </div>
 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="o">(</span>.venv<span class="o">)</span><span class="w"> </span>mtarral@b49691bd4b34:~/kafl/kafl/examples/linux-user/dvkm$<span class="w"> </span>kafl<span class="w"> </span>debug<span class="w"> </span><span class="se">\</span>
 <span class="w">    </span>--resume<span class="w"> </span><span class="se">\</span>
@@ -629,7 +628,7 @@ <h3>Action <code class="docutils literal notranslate"><span class="pre">single</
 <section id="action-gdb">
 <h3>Action <code class="docutils literal notranslate"><span class="pre">gdb</span></code><a class="headerlink" href="#action-gdb" title="Link to this heading">#</a></h3>
 <p>The <code class="docutils literal notranslate"><span class="pre">gdb</span></code> action is particularly valuable for deep-diving into the issues discovered during fuzzing.</p>
-<p>When using this action, QEMU is started in <code class="docutils literal notranslate"><span class="pre">gdbserver</span></code> mode, which allows it to act as a server for the GDB debugger. This means you can interact with the target application in real-time as the payload is being executed.</p>
+<p>This action working similar to <code class="docutils literal notranslate"><span class="pre">single</span></code>, but QEMU is started in <code class="docutils literal notranslate"><span class="pre">gdbserver</span></code> mode, allowing it to act as a server for the GDB debugger. This means you can interact with the target application in real-time as the payload is being executed.</p>
 <p>The use of GDB provides fine-grained control over the execution of the program and allows you to inspect the program’s state, variables, and call stack, offering a clear view into what led to a particular crash or unexpected behavior.</p>
 <p>Upon executing this command, QEMU will pause its execution and wait for a GDB client to connect. Once connected, you can use all the GDB commands to step through code, set breakpoints, and inspect memory and variables, thus enabling a thorough analysis of the crash scenario.</p>
 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="o">(</span>.venv<span class="o">)</span><span class="w"> </span>mtarral@b49691bd4b34:~/kafl/kafl/examples/linux-user/dvkm$<span class="w"> </span>kafl<span class="w"> </span>debug<span class="w"> </span><span class="se">\</span>
@@ -797,21 +796,19 @@ <h3>Action <code class="docutils literal notranslate"><span class="pre">gdb</spa
 <div class="admonition important">
 <p class="admonition-title">Important</p>
 <p>We need to use GDB hardware breakpoints, as software breakpoints in QEMU’s embedded GDB server seems unrealiable.</p>
+</div>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>To reach the <code class="docutils literal notranslate"><span class="pre">dvkm_ioctl</span></code> hardware breakpoint, we had to send a <code class="docutils literal notranslate"><span class="pre">CTRL-C</span></code> to the GDB client.
 The execution was hanging somewhere, for reasons that are not clear at the time of this writing.</p>
 </div>
-</div>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>Also remember that in order to load the symbols reliably, at the same location, we had to disable the Kernel <code class="docutils literal notranslate"><span class="pre">ASLR</span></code>.</p>
+<p>Additionaly, in order to load the symbols reliably, at the same location, Kernel <code class="docutils literal notranslate"><span class="pre">ASLR</span></code> (<em>Address Space Layout Randomization</em>) had to be disabled.</p>
 <p>Have a look at the <code class="docutils literal notranslate"><span class="pre">kafl.yaml</span></code> <code class="docutils literal notranslate"><span class="pre">qemu_append</span></code> line, where <a class="reference external" href="https://www.kernel.org/doc/html/v4.14/admin-guide/kernel-parameters.html"><code class="docutils literal notranslate"><span class="pre">nokaslr</span></code></a> option is set.</p>
 </div>
-<div class="docutils">
 <p>Hopefully by now, you should have a better understanding of the kAFL workdir’s corpus directory, the captured logs and how to interpret them, as well as having the capacity to replay payloads as you will !</p>
 <p>The next section will focus on improving the fuzzing campaign and finding more crashes by compiling our target under <code class="docutils literal notranslate"><span class="pre">KASAN</span></code>, stay tuned !</p>
-</div>
 </section>
 </section>
 </section>

tutorials/linux/dvkm/target.html

@@ -259,7 +259,7 @@
 <h1>1 - Target analysis<a class="headerlink" href="#target-analysis" title="Link to this heading">#</a></h1>
 <section id="objectives">
 <h2>Objectives<a class="headerlink" href="#objectives" title="Link to this heading">#</a></h2>
-<p>The aim is to fuzz the <a class="reference external" href="https://github.com/hardik05/Damn_Vulnerable_Kernel_Module">DVKM (Damned Vulnerable Kernel Module)</a>, an example kernel module developed by<a class="reference external" href="https://github.com/hardik05">Hardik Shah</a>.</p>
+<p>The aim is to fuzz the <a class="reference external" href="https://github.com/hardik05/Damn_Vulnerable_Kernel_Module">DVKM (Damned Vulnerable Kernel Module)</a>, an example kernel module developed by <a class="reference external" href="https://github.com/hardik05">Hardik Shah</a>.</p>
 <p>Designed for fuzzing training, DVKM contains deliberately vulnerable code that exposes to a range of security vulnerabilities, including:</p>
 <ul class="simple">
 <li><p>integer overflow / underflow</p></li>

tutorials/linux/dvkm/workflow.html

@@ -329,21 +329,19 @@ <h3>QEMU Image<a class="headerlink" href="#qemu-image" title="Link to this headi
 </ul>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>If you want to have a look at this kind of workflow, the <a class="reference internal" href="../../windows/driver/index.html"><span class="std std-doc">Windows driver</span></a> target is a good example.</p>
-<p>It combines <a class="reference external" href="https://www.packer.io/">Packer</a>, <a class="reference external" href="https://www.vagrantup.com/">Vagrant</a>, and <a class="reference external" href="https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html">Ansible</a> with <a class="reference external" href="https://learn.microsoft.com/en-us/windows/win32/winrm/portal">WinRM</a> channel to provide a convenient setup.</p>
+<p>The <a class="reference internal" href="../../windows/driver/index.html"><span class="std std-doc">Windows driver</span></a> example target demonstrates how to combine <a class="reference external" href="https://www.packer.io/">Packer</a>, <a class="reference external" href="https://www.vagrantup.com/">Vagrant</a>, and <a class="reference external" href="https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html">Ansible</a> with <a class="reference external" href="https://learn.microsoft.com/en-us/windows/win32/winrm/portal">WinRM</a> channel to provide a convenient setup.</p>
 </div>
 </section>
 <section id="direct-kernel-boot-and-initrd">
 <h3>Direct Kernel Boot and initrd<a class="headerlink" href="#direct-kernel-boot-and-initrd" title="Link to this heading">#</a></h3>
-<p>For targets that are kernel-based, such as ours, a more efficient approach is to use QEMU’s <a class="reference external" href="https://qemu-project.gitlab.io/qemu/system/linuxboot.html">Direct Linux Boot</a> feature in tandem with a custom initrd.</p>
-<p>This configuration forms a lightweight execution environment that can bypass the need for a full OS image.</p>
+<p>Open source kernel and firmware targets can often be booted using QEMU’s <a class="reference external" href="https://qemu-project.gitlab.io/qemu/system/linuxboot.html">Direct Linux Boot</a> feature.</p>
+<p>This approach is often more efficient than bootng a full-VM image and easier to customize and script.</p>
 <div class="literal-block-wrapper docutils container" id="id2">
 <div class="code-block-caption"><span class="caption-text">Example using <code class="docutils literal notranslate"><span class="pre">qemu_kernel</span></code> (<code class="docutils literal notranslate"><span class="pre">--kernel</span></code>) and <code class="docutils literal notranslate"><span class="pre">qemu_initrd</span></code> (<code class="docutils literal notranslate"><span class="pre">--initrd</span></code>) kAFL parameters</span><a class="headerlink" href="#id2" title="Link to this code">#</a></div>
 <div class="highlight-shell notranslate"><div class="highlight"><pre><span></span><span class="o">(</span>venv<span class="o">)</span><span class="w"> </span>$<span class="w"> </span>kafl<span class="w"> </span>fuzz<span class="w"> </span>--kernel<span class="w"> </span>/path/to/linux/arch/x86/boot/bzImage<span class="w"> </span>--initrd<span class="w"> </span>/path/to/initrd.cpio.gz
 </pre></div>
 </div>
 </div>
-<p>Below, we outline how to construct an efficient development workflow leveraging this approach.</p>
 </section>
 </section>
 <section id="initrd-and-agent-sh-workflow">