Documentation: brief introduction and installation steps
This commit is contained in:
parent
c1c5fd4f16
commit
3789da0579
@ -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 <genindex>`
|
||||
|
||||
.. toctree::
|
||||
|
||||
introduction.rst
|
||||
installation.rst
|
||||
|
68
docs/installation.rst
Normal file
68
docs/installation.rst
Normal file
@ -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!
|
100
docs/introduction.rst
Normal file
100
docs/introduction.rst
Normal file
@ -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).
|
Loading…
Reference in New Issue
Block a user