Skip to content

Commit 428a8f4

Browse files
WenzelWenzel
authored
Merge pull request #196 from IntelLabs/docs/kafl.actions
Document kafl.actions Github Action and Self-hosted runner setup
2 parents 0b8687a + 696baea commit 428a8f4

3 files changed

Lines changed: 116 additions & 0 deletions

File tree

‎docs/source/how_to/github_actions.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# Github Actions CI/CD
2+
3+
kAFL can be integrated into your Github Actions CI/CD pipeline, thanks to the [`IntelLabs/kafl.actions`](https://github.com/IntelLabs/kafl.actions).
4+
5+
It acts as a basic-block to compose your workflows with kAFL.
6+
7+
With this Action you can:
8+
9+
- automate the fuzzing process of your target and building a reusable workflow
10+
- delegate the kAFL setup from your local machine to a reproducible infrastucture
11+
- build a regression test suite, continuously updated with new seeds, to be executed at your convenience (every PR, day, week, ...)
12+
13+
Requirements:
14+
15+
- A kAFL-compatible server (**Intel PT**) acting as [Github Action Self-Hosted Runner](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners)
16+
17+
18+
## 1 - Deploying the kernel
19+
20+
This first step will install the kAFL on the server of your choice.
21+
22+
We can leverage kAFL's [Ansible playbook](../reference/deployment.md) to automate this part.
23+
24+
```bash
25+
cd kAFL
26+
# rewrite the Ansible inventory to deploy remotely on a specified server
27+
echo 'kafl-actions-runner.example.com' > deploy/inventory
28+
# only deploy the kernel
29+
make deploy -- --tags kernel
30+
```
31+
32+
:::{note}
33+
This command will:
34+
- install the kernel
35+
- update GRUB
36+
- **reboot** the server
37+
:::
38+
39+
➡️ Once this is done, you should find a `-nyx` tag in your server's `uname`
40+
```bash
41+
uname -a | grep nyx
42+
... 6.0.0-nyx+ ...
43+
```
44+
45+
## 2 - Setting up Docker
46+
47+
[`kafl.actions`](https://github.com/IntelLabs/kafl.actions) will pull the latest [`intellabs/kafl`](https://hub.docker.com/r/intellabs/kafl) Docker image to run the kAFL userspace.
48+
49+
Let's setup Docker on the runner as well !
50+
51+
➡️ [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)
52+
53+
## 3 - Setup the Github Actions Runner
54+
55+
Finally you can follow Github's official guide to add a [Self-Hosted Runner](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#adding-a-self-hosted-runner-to-a-repository) to your repository.
56+
57+
You should now have a runner available under `Settings` `Actions` `Runners`
58+
59+
![kafl_runner](kafl_runner_added.png)
60+
61+
## 4 - Using `kafl.actions`
62+
63+
Go check [`kafl.actions`](https://github.com/IntelLabs/kafl.actions)'s README and the example [`kernel.yml`](https://github.com/IntelLabs/kafl.actions/blob/master/.github/workflows/kernel.yml) to fuzz the Linux kernel !
64+
65+
It boils down to invoking the action, specifing the subcommand, the workdir (to be mounted in the container), and a few `extra_args` for the kAFL command line.
66+
67+
```yaml
68+
- name: Fuzz Linux kernel
69+
uses: IntelLabs/kafl.actions@master
70+
with:
71+
action: fuzz
72+
```
73+
74+
Build your own workflows, automate and fuzz all the things (continuously) !
75+
76+
:::{note}
77+
The default timeout for a Github Action's job is limited to `6h`.
78+
79+
It's possible to bypass this limit by specifying a higher value in [`jobs.<job_id>.timeout-minutes`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes).
80+
81+
For example, you can set it to 2 weeks:
82+
```yaml
83+
jobs:
84+
fuzz:
85+
# bypass 6h limitation
86+
# set to 2 weeks max job execution time
87+
# 60 * 24 * 7 * 2 = 20160 minutes
88+
timeout-minutes: 20160
89+
```
90+
91+
And then limit your target fuzzing to any value you want (under that threshold):
92+
```yaml
93+
- name: Fuzz Linux kernel
94+
uses: IntelLabs/kafl.actions@master
95+
with:
96+
action: fuzz
97+
# 3 days
98+
# 60 * 60 * 24 * 3 = 259200 seconds
99+
timeout: 259200
100+
```
101+
````{warning}
102+
[kafl.actions](https://github.com/IntelLabs/kafl.actions)'s fuzz timeout is specified in **seconds**, not minutes.
103+
````
104+
:::
105+
106+
## References
107+
108+
The [`kafl.actions`](https://github.com/IntelLabs/kafl.actions) Github Action has been introduced to the [Tianocore community meeting](https://www.youtube.com/watch?v=0adtDjSdSjc&t=230s) on May 4th 2023.

‎docs/source/how_to/kafl_runner_added.png‎

22.4 KB
Loading

‎docs/source/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ The project is structured around multiple components:
2626
- [`IntelLabs/kafl.qemu`](https://github.com/IntelLabs/kafl.qemu): Modified QEMU with fast-snapshots support
2727
- [`IntelLabs/kafl.libxdc`](https://github.com/IntelLabs/kafl.libxdc): Fast Intel PT decoding library
2828
- [`IntelLabs/kafl.targets`](https://github.com/IntelLabs/kafl.targets): Example kAFL targets
29+
- [`IntelLabs/kafl.actions`](https://github.com/IntelLabs/kafl.actions): Github Action for CI/CD integration
2930

3031
## Contents
3132

@@ -38,6 +39,13 @@ tutorials/installation
3839
tutorials/fuzzing_linux_kernel
3940
```
4041

42+
```{toctree}
43+
:maxdepth: 2
44+
:caption: How-to guides
45+
46+
how_to/github_actions
47+
```
48+
4149
```{toctree}
4250
:maxdepth: 2
4351
:caption: Reference

0 commit comments

Comments
 (0)