diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index e545caaf..c0748f2f 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -9,10 +9,12 @@ on: paths-ignore: - '**/README.md' - '.github/RELEASE.md' + - 'docs' pull_request: paths-ignore: - '**/README.md' - '.github/RELEASE.md' + - 'docs' env: image_name: intellabs/kafl diff --git a/docs/source/index.md b/docs/source/index.md index 2b57a079..4c59852a 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -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/docs/source/reference/hypercall_api.md b/docs/source/reference/hypercall_api.md index 1e15672d..1aaf7216 100644 --- a/docs/source/reference/hypercall_api.md +++ b/docs/source/reference/hypercall_api.md @@ -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/docs/source/tutorials/concepts.md b/docs/source/tutorials/concepts.md new file mode 100644 index 00000000..9d82e530 --- /dev/null +++ b/docs/source/tutorials/concepts.md @@ -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)