Crate memprocfs

Source
Expand description

§The MemProcFS API Documentation

The MemProcFS crate contains a wrapper API around the MemProcFS physical memory analysis framework. The native library in the form of vmm.dll, vmm.dylib, vmm.so must be downloaded or compiled in order to make use of the memprocfs crate.

Physical memory analysis may take place on memory dump files for forensic purposes. Analysis may also take place on live memory - either captured by using PCILeech PCIe DMA devices or by using a driver - such as WinPMEM, LiveCloudKd, VMware or similar.

The base of the MemProcFS API is the Vmm struct. Once the native vmm has been initialized it’s possible to retrieve processes in the form of the VmmProcess struct. Using the Vmm and VmmProcess it’s possible to undertake a wide range of actions - such as reading/writing memory or retrieve various information.

The use of the low-level LeechCore library is also possible. LeechCore is used for low-level tasks such as setting a memory map, implementing raw PCIe Transaction Layer Packet (TLP), PCIe Base Address Register (BAR) support and more.

Read and write memory by using the methods mem_read(), mem_read_ex(), mem_read_as() and mem_write() / mem_write_as(). Virtual memory is read from VmmProcess struct. Physical memory is read from the Vmm struct.

Efficiently read and write memory using the VmmScatterMemory struct. The scatter struct is retrieved by calling mem_scatter() on either the base Vmm struct or the individual VmmProcess structs.

Access information about loaded modules, memory regions, registry, process handles, kernel pool allocations and much more!

Access the Virtual File System (VFS) using the Rust API to get access to the full range of built-in and external plugins. The VFS is accessed by using the methods vfs_list(), vfs_read() and vfs_write() on the Vmm struct.

The MemProcFS crate and API also supports creation of native MemProcFS plugins in the form of a library .dll or .so.

§Example projects

Check out the Example Project and the Example Plugin.

§Project documentation

Check out the project documentation for MemProcFS, LeechCore and pcileech-fpga:

§Support PCILeech/MemProcFS development:

PCILeech and MemProcFS is free and open source!

I put a lot of time and energy into PCILeech and MemProcFS and related research to make this happen. Some aspects of the projects relate to hardware and I put quite some money into my projects and related research. If you think PCILeech and/or MemProcFS are awesome tools and/or if you had a use for them it’s now possible to contribute by becoming a sponsor!

If you like what I’ve created with PCIleech and MemProcFS with regards to DMA, Memory Analysis and Memory Forensics and would like to give something back to support future development please consider becoming a sponsor at: https://github.com/sponsors/ufrisk

To all my sponsors, Thank You 💖

§Questions and Comments

Please feel free to contact me!

§Get Started!

Check out the Vmm documentation and the Example Project!

Best wishes with your memory analysis project!

Structs§

LcBar
PCIe BAR info struct.
LcBarContext
PCIe BAR Context: Supplied by LeechCore to the BAR callback function.
LcBarContextWrap
PCIe BAR wrapper context - returned to the caller of the BAR enable function.
LcBarRequest
PCIe BAR request struct.
LcTlpContext
PCIe TLP Context: Supplied by LeechCore to the TLP callback function.
LcTlpContextWrap
PCIe TLP wrapper context - returned to the caller of the TLP enable function.
LeechCore
LeechCore API Base Struct.
Vmm
MemProcFS API Base Struct.
VmmKernel
Kernel information.
VmmMapKDeviceEntry
Info: Kernel device entries.
VmmMapKDriverEntry
Info: Kernel driver entries.
VmmMapKObjectEntry
Info: Kernel named object manager entries.
VmmMapMemoryEntry
Info: Physical memory map entries.
VmmMapNetEntry
Info: Network connections.
VmmMapPfnEntry
Info: Memory PFN (Page Frame Number).
VmmMapPoolEntry
Info: Kernel pool entries.
VmmMapServiceEntry
Info: Services.
VmmMapUserEntry
Info: Users.
VmmMapVirtualMachineEntry
Info: Virtual Machines (VMs).
VmmPdb
Debug Symbol API.
VmmPluginContext
Plugin Context: Supplied by MemProcFS to plugin callback functions.
VmmPluginFileList
Plugin File List: Supplied by MemProcFS to plugin list callback function.
VmmPluginInitializationContext
Plugin Initialization Context.
VmmPluginInitializationInfo
Plugin Initialization System Information.
VmmProcess
Process API Base Struct.
VmmProcessInfo
Process Information.
VmmProcessMapDirectoryEntry
Info: Process Module: PE data directories.
VmmProcessMapEatEntry
Info: Process Module: PE exported entries.
VmmProcessMapHandleEntry
Info: Process: Handles.
VmmProcessMapHeapAllocEntry
Info: Process: Heap allocations.
VmmProcessMapHeapEntry
Info: Process: Heaps.
VmmProcessMapIatEntry
Info: Process Module: PE imported entries.
VmmProcessMapModuleDebugEntry
Info: Process: Modules (loaded DLLs) debug information.
VmmProcessMapModuleEntry
Info: Process: Modules (loaded DLLs).
VmmProcessMapModuleVersionEntry
Info: Process: Modules (loaded DLLs) version information.
VmmProcessMapPteEntry
Info: Process: PTE memory map entries.
VmmProcessMapThreadCallstackEntry
Info: Process: Thread Callstack.
VmmProcessMapThreadEntry
Info: Process: Threads.
VmmProcessMapUnloadedModuleEntry
Info: Process: Unloaded modules.
VmmProcessMapVadEntry
Info: Process: VAD (Virtual Address Descriptor) memory map entries.
VmmProcessMapVadExEntry
Info: Process: Extended VAD memory map entries.
VmmProcessSectionEntry
Info: Process Module: PE sections.
VmmRegHive
Registry Hive API.
VmmRegKey
Registry Key API.
VmmRegValue
Registry Value API.
VmmScatterMemory
Efficient Memory Reading API.
VmmSearch
Search API.
VmmSearchResult
Info: Search Progress/Result.
VmmVfsEntry
VFS (Virtual File System) entry information - file or directory.
VmmYara
Yara Search API.
VmmYaraMatch
Info: Yara search match.
VmmYaraMatchString
Info: Yara search match string.
VmmYaraResult
Info: Yara search Progress/Result.

Enums§

VmmIntegrityLevelType
VmmLogLevel
VmmMapPfnType
VmmMapPfnTypeExtended
VmmMemoryModelType
VmmProcessMapHeapAllocType
VmmProcessMapHeapType
VmmProcessMapModuleType
VmmProcessMapVadExType
VmmRegValueType
VmmSystemType

Constants§

CONFIG_OPT_CONFIG_DEBUG
Set native library internal custom debug.
CONFIG_OPT_CONFIG_IS_PAGING_ENABLED
Get/Set enable paging support 1/0.
CONFIG_OPT_CONFIG_IS_REFRESH_ENABLED
Get whether the refresh is enabled or not (1/0).
CONFIG_OPT_CONFIG_PROCCACHE_TICKS_PARTIAL
Get/Set process refresh (partial) period (in ticks).
CONFIG_OPT_CONFIG_PROCCACHE_TICKS_TOTAL
Get/Set process refresh (full) period (in ticks).
CONFIG_OPT_CONFIG_READCACHE_TICKS
Get/Set memory cache validity period (in ticks).
CONFIG_OPT_CONFIG_STATISTICS_FUNCTIONCALL
Get/Set enable function call statistics (.status/statistics_fncall file).
CONFIG_OPT_CONFIG_TICK_PERIOD
Get/Set base tick period in ms.
CONFIG_OPT_CONFIG_TLBCACHE_TICKS
Get/Set page table (tlb) cache validity period (in ticks).
CONFIG_OPT_CONFIG_VMM_VERSION_MAJOR
Get MemProcFS major version.
CONFIG_OPT_CONFIG_VMM_VERSION_MINOR
Get MemProcFS minor version.
CONFIG_OPT_CONFIG_VMM_VERSION_REVISION
Get MemProcFS revision version.
CONFIG_OPT_CORE_LEECHCORE_HANDLE
Get the LeechCore native handle. (void*) (do not close/free).
CONFIG_OPT_CORE_MAX_NATIVE_ADDRESS
Get max native physical memory address.
CONFIG_OPT_CORE_MEMORYMODEL
Get the numeric memory model type according to the VMM C-API.
CONFIG_OPT_CORE_PRINTF_ENABLE
Get/Set library console printouts.
CONFIG_OPT_CORE_SYSTEM
Get the numeric system type according to VMM C-API.
CONFIG_OPT_CORE_VERBOSE
Get/Set standard verbosity.
CONFIG_OPT_CORE_VERBOSE_EXTRA
Get/Set extra verbosity.
CONFIG_OPT_CORE_VERBOSE_EXTRA_TLP
Get/Set super extra verbosity and PCIe TLP debug.
CONFIG_OPT_CORE_VMM_ID
Get the vmmid that may be used with startup option ‘-create-from-vmmid’ to create a thread-safe duplicate VMM instance.
CONFIG_OPT_FORENSIC_MODE
Get/Set enable/retrieve forensic mode type [0-4].
CONFIG_OPT_PROCESS_DTB
Set custom process directory table base. [LO-DWORD: Process PID].
CONFIG_OPT_REFRESH_ALL
Set - trigger refresh all caches.
CONFIG_OPT_REFRESH_FREQ_FAST
Set - refresh fast frequency - incl. partial process refresh.
CONFIG_OPT_REFRESH_FREQ_MEDIUM
Set - refresh medium frequency - incl. full process refresh.
CONFIG_OPT_REFRESH_FREQ_MEM
Set - refresh memory cache (excl. TLB) (fully).
CONFIG_OPT_REFRESH_FREQ_MEM_PARTIAL
Set - refresh memory cache (excl. TLB) [partial 33%/call].
CONFIG_OPT_REFRESH_FREQ_SLOW
Set - refresh slow frequency.
CONFIG_OPT_REFRESH_FREQ_TLB
Set - refresh page table (TLB) cache (fully)
CONFIG_OPT_REFRESH_FREQ_TLB_PARTIAL
Set - refresh page table (TLB) cache [partial 33%/call].
CONFIG_OPT_WIN_SYSTEM_UNIQUE_ID
Get MemProcFS unique system id.
CONFIG_OPT_WIN_VERSION_BUILD
Get OS version build.
CONFIG_OPT_WIN_VERSION_MAJOR
Get OS version major.
CONFIG_OPT_WIN_VERSION_MINOR
Get OS version minor.
FLAG_CACHE_RECENT_ONLY
Only fetch from the most recent active cache region when reading.
FLAG_FORCECACHE_READ
Force use of data cache - fail non-cached pages.
FLAG_FORCECACHE_READ_DISABLE
Disable/override any use of VMM_FLAG_FORCECACHE_READ.
FLAG_NOCACHE
Do not use internal data cache.
FLAG_NOCACHEPUT
Do not populate the data cache on a successful read.
FLAG_NOPAGING
Do not retrieve memory from paged out memory.
FLAG_NOPAGING_IO
Do not retrieve memory from paged out memory***.
FLAG_NO_PREDICTIVE_READ
Deprecated/Unused.
FLAG_SCATTER_PREPAREEX_NOMEMZERO
Disable clearing of memory supplied to VmmScatterMemory.prepare_ex
FLAG_ZEROPAD_ON_FAIL
Zero pad failed memory reads and report success.
PLUGIN_NOTIFY_FORENSIC_INIT
Forensic mode initialization start.
PLUGIN_NOTIFY_FORENSIC_INIT_COMPLETE
Forensic mode processing is completed.
PLUGIN_NOTIFY_REFRESH_FAST
Fast refresh. Partial process refresh.
PLUGIN_NOTIFY_REFRESH_MEDIUM
Medium refresh. Full process refresh and other refresh tasks.
PLUGIN_NOTIFY_REFRESH_SLOW
Slow refresh. Total refresh of as much as possible.
PLUGIN_NOTIFY_VERBOSITYCHANGE
Verbosity change. Query new verbosity with: vmm.get_config().
PLUGIN_NOTIFY_VM_ATTACH_DETACH
A child VM was attached or detached. Query new state with API.

Functions§

new_plugin_initialization
Initialize plugin information and initialization context.

Type Aliases§

ResultEx
Result type for MemProcFS API.