out-of-tree/README.md

out-of-tree

out-of-tree kernel {module, exploit} development tool

out-of-tree is for automating some routine actions for creating development environments for debugging kernel modules and exploits, generating reliability statistics for exploits, and also provides the ability to easily integrate into CI (Continuous Integration).

Installation

GNU/Linux (with Nix)

$ curl -fsSL https://get.docker.com | sh
$ sudo usermod -aG docker user && newgrp docker
$ curl -L https://nixos.org/nix/install | sh
$ nix-env -iA nixpkgs.out-of-tree # Note: may not be up to date immediately, in this case consider installing from source

Note that adding a user to group docker has serious security implications. Check Docker documentation for more information.

macOS

Note: case-sensitive FS is required for the ~/.out-of-tree directory.

$ brew install podman
$ podman machine stop || true
$ podman machine rm || true
$ podman machine init --cpus=4 --memory=4096 -v $HOME:$HOME
$ podman machine start
$ brew tap out-of-tree/repo
$ brew install out-of-tree

Read documentation for further info.

Examples

Generate all Ubuntu 22.04 kernels:

$ out-of-tree kernel genall --distro=Ubuntu --ver=22.04

Run tests based on .out-of-tree.toml definitions:

$ out-of-tree pew

Test with a specific kernel:

$ out-of-tree pew --kernel='Ubuntu:5.4.0-29-generic'

Run debug environment:

$ out-of-tree debug --kernel='Ubuntu:5.4.0-29-generic'