===================================================
LMAP - Linux Physical Memory acquisition tool
===================================================
Author: Johannes Stuettgen (johannes.stuettgen@gmail.com)
Version: @LMAP_VERSION_MAJOR@.@LMAP_VERSION_MINOR@

Summary:
========
LMAP is a binary linux memory acquisition tool that works on any kernel and
distribution without having to build anything on the target system.

How it works:
=============
Memory acquisition on Linux requires loading a kernel module. For stability
reasons, this has to be compiled on the system where it will be loaded. LMAP
avoids this requirement by bringing along a minimal memory acquisition kernel
module that doesn't use the kernel and thus is compatible with most kernel
versions.

To ensure compatibility and stability on the target system LMAP borrows a
compatible kernel module from the current system (it searches /lib/modules) as
a host. LMAP then injects it's code and data into a copy of the host in memory
and loads the result into the kernel.

The integrated kernel module is kernel-independent and works on any Linux
x86-64 system from kernel 2.6 to 3.X [2]. The usermode 'lmap' binary is
statically linked to avoid libc version dependencies. You can find further
technical details in our paper published at DFRWS EU [1].

Usage:
======
Copy the 'lmap' binary to a Linux system where memory should be acquired.

LMAP can dump memory directly and create an ELF coredump file using the '-a'
option. It can also load the pmem module with the '-l' option, then acquire
memory by reading from the created '/dev/pmem' device file (e.g. with 'dd').

There are multiple other options, a complete list can be found here or by
running 'lmap' without any options:

modes of operation:
  -a dumpfile  Main use case. Find a suitable host module, use it to load pmem
               and then dump memory into an ELF core dump file.
  -l           Find a host, use it to load the acquisition module. The pmem
               module can be used by seeking and reading the file '/dev/pmem'.
  -d           Find a host and inject pmem, then dump the generated module
               to the filesystem as 'infected_module.ko'.
  -f           Scan for and list suitable hosts, don't inject or load anything.

optional arguments:
  -o outfile   The output file for '-d' (default: infected_module.ko).
  -i inputfile Don't inject the bundled pmem module, use this one instead.
  -h module    Don't search for a suitable host module, use this one instead.
  -p path      Path to kernel modules to scan for hosts.
  -m           Print the systems physical memory map.
  -v           Verbose, produces detailed debug logging.

Limitations:
============
LMAP relies on finding a valid kernel module on the target system that serves
as a host for it's pmem module. Not every module satisfies the requirements,
so it might be possible that no suitable host module exists on the target. In
that case you will have to compile a module (e.g. pmem) on the target itself,
or on a build system with identical kernel version and config.

Also, some modules might be suitable hosts, but require other modules to
function. For example the 'pg.ko' and 'pt.ko' modules import symbols from
'paride.ko'. If LMAP fails to load it's module and your 'dmesg' output shows
missing symbols, try another host by first scanning with '-f' and then selecting
it with the '-h' option.

LMAP only supports one open file descriptor at once. If you open() the device
file multiple times simultaneously, seek() and read() on one fd will change the
file position on all other fds. This is not an issue when operating lmap in it's
intended mode with the '-a' switch, but you might run into it if you're loading
the module manually with '-l'.

Ftrace is a kernel feature that patches all kernel and module functions with
calls to certain tracing functions to enable debugging and performance
monitoring. This is partially done at compile- and run-time. LMAP should always
be built without ftrace, as it introduces symbol dependencies to ftrace and the
generated module won't be loadable into kernels compiled without ftrace. If the
target system runs ftrace, LMAP is still able to load it's module. However,
ftrace will complain about not being able to hook into the module. This results
in a warning in the targets kernel debug buffer:
  'WARNING: CPU: ... at ... ftrace_bug ...'
This is normal and does not compromise lmap, the module or the acquisition
process in any way. Note that ftrace shuts down after that, so you will need to
reboot the machine if you intend to use ftrace for debugging after running LMAP.

If you're using the 'build.sh' script to build LMAP the CMake scripts will
create a copy of your kernel headers and config in 'build/kernel_headers'.
Any FTRACE options enabled in your original kernel config will be disabled there
and the pmem module will be compiled with this config to guarantee an FTRACE
free build.

Compatibility:
==============
The entire tool suite is only compatible with x86-64 processors and binaries.
32 Bit x86 and ARM support is still in development.

Building from Source:
=====================
See the README in the projects root ('tools/linux/lmap').

References:
===========
[1] Stüttgen, Johannes, and Michael Cohen.
  "Robust Linux Memory Acquisition with Minimal Target Impact"
  Digital Investigation 11 (2014): P112-P119.
[2] Stüttgen, Johannes, and Michael Cohen.
  "Anti-forensic resilient memory acquisition"
  Digital Investigation 10 (2013): P105-P115.
