**************************************************************************
* libplayground                                                          *
* A simple framework for developing Linux kernel heap exploit techniques *
**************************************************************************

Warning: this will deliberately introduce vulnerabilities into your kernel for
the purposes of exploit development. Additionally, use of this module may, by
design, cause corruption of kernel heap memory that may impact system
stability, including the integrity of files stored on disk. It is highly
recommended that all testing be performed on a disposable virtual machine.

libplayground is composed of two parts. A Linux kernel module, located in
module/, creates a device file at /dev/playground.  This device file supports
ioctls designed to simulate various exploitation primitives useful when
developing Linux kernel heap exploits.  Currently supported is the ability to
allocate and free heap chunks, the ability to read and write arbitrary data to
and from specific heap chunks (for example to simulate a heap overflow), the
ability to cause a double-free of a heap chunk, and the ability to trigger the
invocation of a function pointer stored at a specified offset from the
beginning of a heap chunk.  All chunks are allocated using kmalloc(), which
will invoke whichever slab layer is running on the testing kernel.  At the time
of this writing, SLUB is the default allocator, but other allocators, such as
SLAB or SLOB, may be configured at compile time.

The pointers to chunks allocated using libplayground are stored in an array and
can be accessed by referring to the "slot" the chunk pointer is stored in.  For
example, to allocate a 32-byte chunk and store its pointer in slot 200, you can
call:

	kmalloc(200, 32);

It's important to remember that the slot numbers just represent numeric
identifiers that will allow you to keep track of heap chunks you're
manipulating; think of them as handles to kernel heap chunks.  The order in
which the chunk pointers are stored in the libplayground array has nothing to
do with the order of the actual chunks in memory.  Slots 32 and 33 may point to
chunks living in entirely different parts of the kernel heap.  If you want to
cause kernel heap allocations to be sequential, you'll have to do that yourself
by manipulating the behavior of the allocator with your allocations.

The module can be built using a simple "make", and loaded into the kernel using
"insmod playground.ko".

To make interacting with this kernel module a little easier, a simple userland
library is included in lib/.  After building and installing this library and
its associated header file ("make install"), test cases may be built against it
by including "<playground.h>" and linking against the library.  An example
provided in examples/ can be built as follows:

	gcc chunk-growth.c -o chunk-growth -lplayground

Or, if you built the library but didn't install it:

	gcc chunk-growth.c -o chunk-growth -I../lib/ -L../lib/ -lplayground

Take a look at lib/playground.h and the example for the provided functions and
usage.  Happy hacking!