Home

The LeechCore and LeechAgent Wiki and Guide

Welcome to the Wiki and Guide for the LeechCore memory acquisition library and the LeechAgent remote memory acquisition and analysis agent! In addition to this guide please check out the project README for general information.

For individual guide items please have a look at the sidebar to the right.

The LeechCore library is a physical memory acquisition library used by other applications such as PCILeech and MemProcFS. The LeechCore library exists for Windows as a .dll and for Linux as a .so. Some features such as the remote connection capability as well as the DumpIt/WinPMEM/Hyper-V Saved State functionality only exists in the Windows version of the library - while other functionality such as File/USB3380/FPGA/iLO exists in both versions of the library. LeechCore also contains functionality for sending and receiving raw PCI Express Transaction Layer Packets (TLPs) if FPGA devices are used.

The LeechCore library does not exist as a stand-alone component. The LeechCore is only meant to be included in other applications. The supported devices and their connection options are however documented in this wiki.

Some supported devices are supported through separate plugin module .so/.dll files. Some plugins are documented in this guide. For all plugins and drivers please also see the LeechCore plugin Github repository.

LeechCore is available on Python PIP. Please also have a look at the Python API examples in this guide.

The LeechAgent Remote Acquisition and Analysis Agent:

A separate LeechAgent application exists for Windows.

The LeechAgent service exposes the LeechCore library API via a remote network connection secured by mutually authenticated Kerberos RPC (if running within an Active Directory environment). It is also possible to optionally run the LeechAgent in an insecure unauthenticated mode.

Start the LeechAgent in either interactive mode or in service mode to allow for remote users of the LeechCore library to connect to the LeechAgent and use any of the supported memory acquisition methods transparently and remotely.

Components using the LeechCore library - such as The Memory Process File System is working fairly well even over low-bandwidth high-latency (up to 100ms).

Submit remote memory analysis jobs to the LeechAgent; in the form of python scripts using the MemProcFS API to the remote LeechAgent for processing. This is ideal for complicated processing intense tasks, or tasks that should run on a large number of hosts in parallel. This approach works extremely well even over low-bandwidth high-latency connections.

Memory Acquisition Methods:

Software based memory acquisition methods:

Please find a summary of the supported software based memory acquisition methods listed below. Please note that the LeechAgent only provides a network connection to a remote LeechCore library. It's possible to use both hardware and software based memory acquisition once connected.

Device	Type	Volatile	Write	Linux Support	Plugin
RAW physical memory dump	File	No	No	Yes	No
Full Microsoft Crash Dump	File	No	No	Yes	No
Full ELF Core Dump	File	No	No	Yes	No
QEMU	Live Memory	Yes	Yes	No	No
VMware	Live Memory	Yes	Yes	No	No
VMware memory save file	File	No	No	Yes	No
TotalMeltdown	CVE-2018-1038	Yes	Yes	No	No
DumpIt /LIVEKD	Live Memory	Yes	No	No	No
LiveCloudKd	Live Memory	Yes	No	No	No
LiveKd	Live Memory	Yes	No	No	No
WinPMEM	Live Memory	Yes	No	No	No
Hyper-V Saved State	File	No	No	No	Yes
LeechAgent*	Remote			No	No

Hardware based memory acquisition methods:

Please find a summary of the supported hardware based memory acquisition methods listed below. All hardware based memory acquisition methods are supported on both Windows and Linux. The FPGA based methods however sports a slight performance penalty on Linux and will max out at approx: 90MB/s compared to 150MB/s on Windows.

Device	Type	Interface	Speed	64-bit memory access	PCIe TLP access	Project Sponsor
Screamer PCIe Squirrel	FPGA	USB-C	190MB/s	Yes	Yes	💖
ZDMA	FPGA	Thunderbolt3	800MB/s	Yes	Yes	💖
LeetDMA	FPGA	USB-C	190MB/s	Yes	Yes	💖
AC701/FT601	FPGA	USB3	190MB/s	Yes	Yes
USB3380-EVB	USB3380	USB3	150MB/s	No	No
PP3380	USB3380	USB3	150MB/s	No	No
DMA patched HP iLO	BMC	TCP	1MB/s	Yes	No