Deploying to gh-pages from @ 11d2879 🚀

IntelLabs · Oct 23, 2023 · 17f66e0 · 17f66e0
1 parent 97ba4fe
commit 17f66e0
Show file tree

Hide file tree

Showing 33 changed files with 465 additions and 9 deletions.
diff --git a/_sources/index.md.txt b/_sources/index.md.txt
@@ -36,6 +36,7 @@ The project is structured around multiple components:
 
 tutorials/introduction
 tutorials/installation
+tutorials/concepts
 tutorials/fuzzing_linux_kernel
 tutorials/windows/index
 ```

diff --git a/_sources/reference/hypercall_api.md.txt b/_sources/reference/hypercall_api.md.txt
@@ -8,7 +8,7 @@ control and start injecting inputs at any point in VM guest execution.
 
 The hypercall API can be found in the [nyx_api.h](https://github.com/IntelLabs/kafl.targets/blob/master/nyx_api.h) C header.
 
-The following hypercalls should be prefixed by `kAFL_HYPERCALL_`.
+The following hypercalls should be prefixed by `HYPERCALL_KAFL_`.
 
 ## Essential hypercalls
 

diff --git a/_sources/tutorials/concepts.md.txt b/_sources/tutorials/concepts.md.txt
@@ -0,0 +1,47 @@
+# Concepts
+
+Before we dive into a specific target, we need to introduce the concept of a _kAFL Agent_ that will used at the next step of the tutorial
+
+We assume you are already familiar with fuzzing vocabulary ([Google's fuzzing glossary](https://github.com/google/fuzzing/blob/master/docs/glossary.md) can be helpful here).
+
+## kAFL Agent
+
+The term _kAFL Agent_ simply refers to the implementation of a fuzzing harness in the guest.
+
+The _Agent_ is responsible for both instrumenting and overseeing a specific portion of the SUT (_System Under Test_) through a set of [hypercalls](../reference/hypercall_api.md).
+
+Considering that these hypercalls constitues a communication channel with the external virtual machine environment, the term _agent_ has been employed, akin to a guest agent.
+
+```{mermaid}
+graph LR
+    fuzzer["kAFL Fuzzer"] <--> QEMU["QEMU/KVM"]
+    subgraph Virtual Machine
+        Agent["kAFL Agent"] <-- Instruments --> SUT["Software Under Test"]
+    end
+    QEMU <-- Hypercalls --> Agent
+```
+
+```{code-block} C
+---
+caption: Example of a simplified kAFL Agent fuzzing a target function called `target()`
+---
+// 🤝 kAFL handshake 
+kAFL_hypercall(HYPERCALL_KAFL_ACQUIRE, 0);
+kAFL_hypercall(HYPERCALL_KAFL_RELEASE, 0);
+// allocate kAFL payload buffer
+kAFL_payload *payload_buffer = malloc(PAYLOAD_SIZE);
+// kAFL configuration, filters, etc...
+// 🟢 Enable feedback collection
+kAFL_hypercall(KAFL_HYPERCALL_ACQUIRE);
+// ⚡call target func ...
+target(payload_buffer->data, payload_buffer->size);
+// ⚪ Disable feedback collection
+kAFL_hypercall(KAFL_HYPERCALL_RELEASE);
+```
+
+## Pick a Target !
+
+Now you are ready to configure one of our pre-baked kAFL targets, and start the fuzzer !
+
+- ➡️ Continue by [fuzzing the Linux Kernel](./fuzzing_linux_kernel.md)
+- ➡️ Continue by [fuzzing Windows programs](./windows/index.md)
diff --git a/context/research_papers.html b/context/research_papers.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/dev/documentation.html b/dev/documentation.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/genindex.html b/genindex.html
@@ -158,6 +158,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/how_to/github_actions.html b/how_to/github_actions.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/index.html b/index.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
@@ -285,6 +286,11 @@ <h2>Contents<a class="headerlink" href="#contents" title="Permalink to this head
 <li class="toctree-l2"><a class="reference internal" href="tutorials/installation.html#on-to-the-next-steps">6. On to the next steps !</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/concepts.html">Concepts</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="tutorials/concepts.html#kafl-agent">kAFL Agent</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tutorials/concepts.html#pick-a-target">Pick a Target !</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="tutorials/fuzzing_linux_kernel.html#download-patched-linux-kernel-or-port-to-your-preferred-kernel">1. Download patched Linux kernel (or port to your preferred kernel)</a></li>
 <li class="toctree-l2"><a class="reference internal" href="tutorials/fuzzing_linux_kernel.html#configure-and-build-target-kernel">2. Configure and build target kernel</a></li>

diff --git a/objects.inv b/objects.inv
diff --git a/reference/deployment.html b/reference/deployment.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/reference/fuzzer_configuration.html b/reference/fuzzer_configuration.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/reference/hypercall_api.html b/reference/hypercall_api.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
@@ -249,7 +250,7 @@ <h1>kAFL/Nyx Hypercall API<a class="headerlink" href="#kafl-nyx-hypercall-api" t
 <p>This approach offers a minimal low-level interface that can be used to take
 control and start injecting inputs at any point in VM guest execution.</p>
 <p>The hypercall API can be found in the <a class="reference external" href="https://github.com/IntelLabs/kafl.targets/blob/master/nyx_api.h">nyx_api.h</a> C header.</p>
-<p>The following hypercalls should be prefixed by <code class="docutils literal notranslate"><span class="pre">kAFL_HYPERCALL_</span></code>.</p>
+<p>The following hypercalls should be prefixed by <code class="docutils literal notranslate"><span class="pre">HYPERCALL_KAFL_</span></code>.</p>
 <section id="essential-hypercalls">
 <h2>Essential hypercalls<a class="headerlink" href="#essential-hypercalls" title="Permalink to this heading">#</a></h2>
 <section id="acquire-release">

diff --git a/reference/user_interface.html b/reference/user_interface.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/reference/workdir_layout.html b/reference/workdir_layout.html
@@ -160,6 +160,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="../tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="../tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/search.html b/search.html
@@ -157,6 +157,7 @@
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/introduction.html">Introduction</a></li>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/installation.html">Installation</a></li>
+<li class="toctree-l1"><a class="reference internal" href="tutorials/concepts.html">Concepts</a></li>
 <li class="toctree-l1"><a class="reference internal" href="tutorials/fuzzing_linux_kernel.html">Linux Kernel target</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="tutorials/windows/index.html">Windows Target</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" role="switch" type="checkbox"/><label for="toctree-checkbox-1"><div class="visually-hidden">Toggle navigation of Windows Target</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>
 <li class="toctree-l2 has-children"><a class="reference internal" href="tutorials/windows/driver/index.html">Driver</a><input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" role="switch" type="checkbox"/><label for="toctree-checkbox-2"><div class="visually-hidden">Toggle navigation of Driver</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label><ul>

diff --git a/searchindex.js b/searchindex.js