From 3789da0579121914d42010baba0c5ba450bcce19 Mon Sep 17 00:00:00 2001 From: Mikhail Klementev Date: Sat, 17 Aug 2019 00:33:50 +0000 Subject: [PATCH] Documentation: brief introduction and installation steps --- docs/index.rst | 28 +++++++++++- docs/installation.rst | 68 ++++++++++++++++++++++++++++ docs/introduction.rst | 100 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 docs/installation.rst create mode 100644 docs/introduction.rst diff --git a/docs/index.rst b/docs/index.rst index b146ea1..6216eba 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,30 @@ out-of-tree =========== -out-of-tree kernel {module, exploit} development tool +*out-of-tree* is the kernel {module, exploit} development tool. + +*out-of-tree* was created on the purpose of decreasing complexity of +environment for developing, testing and debugging Linux kernel +exploits and out-of-tree kernel modules (that's why tool got a name +"out-of-tree"). + +While I'm trying to keep that documentation up-to-date, there may be +some missing information. Use ``out-of-tree --help-long`` for checking +all features. + +If you found anything missed here, please make a pull request or send +patches to patch@dumpstack.io. + +If you need personal support, your company is interested in the +project or you just want to share some thoughts -- feel free to write +to root@dumpstack.io. + +Contents +======== + +:ref:`Keyword Index ` + +.. toctree:: + + introduction.rst + installation.rst diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000..11de760 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,68 @@ +Installation +============ + +OS/Distro-specific +================== + +Ubuntu +------ + +Install dependencies:: + + $ sudo snap install go --classic + $ sudo snap install docker + $ sudo apt install qemu-system-x86 build-essential gdb + +macOS +----- + +Install dependencies:: + + $ brew install go qemu + $ brew cask install docker + +NixOS +----- + +There's a minimal configuration that you need to apply:: + + #!nix + { config, pkgs, ... }: + { + virtualisation.docker.enable = true; + virtualisation.libvirtd.enable = true; + environment.systemPackages = with pkgs; [ + go git + ]; + } + +Common +====== + +Setup Go environment:: + + $ echo 'export GOPATH=$HOME' >> ~/.bashrc + $ echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc + $ source ~/.bashrc + +Build *out-of-tree*:: + + $ go get -u code.dumpstack.io/tools/out-of-tree + +.. note:: + On a GNU/Linux you need to add your user to docker group if you want + to use *out-of-tree* without sudo. Note that this has a **serious** + security implications. Check *Docker* documentation for more + information. + +Bootstrap:: + + $ out-of-tree bootstrap + +Test that everything works:: + + $ cd $GOPATH/src/code.dumpstack.io/tools/out-of-tree/examples/kernel-exploit + $ out-of-tree kernel autogen --max=1 + $ out-of-tree pew --max=1 + +Enjoy! diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..a26f8cc --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,100 @@ +Introduction +============ + +*out-of-tree* is written in *Go*, it uses *Docker* for generating +kernel/filesystem images and *Qemu* for virtualization. + +Also it possible to generate kernels from the host system and use the +custom one. + +*out-of-tree* supports *GNU/Linux* (usually it's tested on NixOS and +latest Ubuntu LTS) and *macOS*. Technically all systems that supported +by Go, Docker, and Qemu must work well. Create the issue if you'll +notice any issue in integration for your operating system. + +All *Qemu* interaction is stateless. + +*out-of-tree* is allow and require metadata (``.out-of-tree.toml``) +for work. TOML (Tom's Obvious, Minimal Language) is used for kernel +module/exploit description. + +``.out-of-tree.toml`` is mandatory, you need to have in the current +directory (usually, it's a project of kernel module/exploit) or use +the ``--path`` flag. + +Files +----- + +All data is stored in ``~/.out-of-tree/``. + +- *db.sqlite* contains logs related to run with ``out-of-tree pew``, + debug mode (``out-of-tree debug``) is not store any data. + +- *images* used for filesystem images (rootfs images that used for + ``qemu -hda ...``) that can be generated with the + ``tools/qemu-*-img/...``. + +- *kernels* stores all kernel ``vmlinuz/initrd/config/...`` files that + generated previously with a some *Docker magic*. + +- *kernels.toml* contains metadata for generated kernels. It's not + supposed to be edited by hands. + +- *kernels.user.toml* is default path for custom kernels definition. + +- *Ubuntu* (or *Centos*/*Debian*/...) is the Dockerfiles tree + (DistroName/DistroVersion/Dockerfile). Each Dockerfile contains a + base layer and incrementally updated list of kernels that must be + installed. + +Overview +--------- + +*out-of-tree* creating debugging environment based on **defined** kernels:: + + $ out-of-tree debug --kernel 'Ubuntu:4.15.0-58-generic' + [*] KASLR SMEP SMAP + [*] gdb runned on tcp::1234 + [*] build result copied to /tmp/exploit + + ssh -o StrictHostKeyChecking=no -p 29308 root@127.133.45.236 + gdb /usr/lib/debug/boot/vmlinux-4.15.0-58-generic -ex 'target remote tcp::1234' + + out-of-tree> help + help : print this help message + log : print qemu log + clog : print qemu log and cleanup buffer + cleanup : cleanup qemu log buffer + ssh : print arguments to ssh command + quit : quit + out-of-tree> + +*out-of-tree* uses three stages for automated runs: + +- Build + - Inside the docker container (default). + - Binary version (de facto skip stage). + - On host. +- Run + - Insmod for the kernel module. + - This step is skipped for exploits. +- Test + - Run the test.sh script on the target machine. + - Test script is run from *root* for the kernel module. + - Test script is run from *user* for the kernel exploit. + - Test script for the kernel module is fully custom (only return + value is checked). + - Test script for the kernel exploit receives two parameters: + - Path to exploit + - Path to file that must be created with root privileges. + +Security +-------- + +*out-of-tree* is not supposed to be used on multi-user systems or with +an untrusted input. + +Meanwhile, all modern hypervisors are supporting nested +virtualization, which means you can use it for isolating *out-of-tree* +if you want to work with an untrusted input (e.g. with a mass-scale +testing public proofs-of-concept).