{"id":13593660,"url":"https://github.com/ufrisk/LeechCore","last_synced_at":"2025-04-09T05:31:55.962Z","repository":{"id":45334449,"uuid":"168605784","full_name":"ufrisk/LeechCore","owner":"ufrisk","description":"LeechCore - Physical Memory Acquisition Library \u0026 The LeechAgent Remote Memory Acquisition Agent","archived":false,"fork":false,"pushed_at":"2025-03-01T14:08:39.000Z","size":2300,"stargazers_count":592,"open_issues_count":3,"forks_count":109,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-04-04T23:01:35.376Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ufrisk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"ufrisk"}},"created_at":"2019-01-31T22:20:10.000Z","updated_at":"2025-04-01T11:53:46.000Z","dependencies_parsed_at":"2024-02-21T01:00:19.372Z","dependency_job_id":"f5632889-b863-4d27-b041-c3333b3b00ec","html_url":"https://github.com/ufrisk/LeechCore","commit_stats":{"total_commits":131,"total_committers":4,"mean_commits":32.75,"dds":0.06106870229007633,"last_synced_commit":"161cde3d201cac148e3704a8a592d5a07905be1c"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ufrisk%2FLeechCore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ufrisk%2FLeechCore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ufrisk%2FLeechCore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ufrisk%2FLeechCore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ufrisk","download_url":"https://codeload.github.com/ufrisk/LeechCore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247509221,"owners_count":20950232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T16:01:22.827Z","updated_at":"2025-04-09T05:31:55.947Z","avatar_url":"https://github.com/ufrisk.png","language":"C","readme":"The LeechCore Physical Memory Acquisition Library:\n=========================================\nThe LeechCore Memory Acquisition Library focuses on Physical Memory Acquisition using various hardware and software based methods.\n\nLeechCore provides API-based access to various hardware and software based memory sources via its `C/C++`, `Python` and `C#` APIs. Download the latest [release](https://github.com/ufrisk/LeechCore/releases/latest) of the library here on Github. If using Python it's recommended to install the [`leechcorepyc`](https://pypi.org/project/leechcorepyc/) **python pip** package which is available for 64-bit Linux and Windows.\n\nUse the LeechCore library locally or connect to, over the network, a LeechAgent to acquire physical memory or run commands remotely. The connection is by default compressed and secured with mutually authenticated kerberos - making it ideal in incident response when combined with analysis and live memory capture using Comae DumpIt or WinPMEM - even over high latency low-bandwidth connections!\n\nThe LeechCore library is used by [PCILeech](https://github.com/ufrisk/pcileech) and [The Memory Process File System (MemProcFS)](https://github.com/ufrisk/MemProcFS).\n\nThe LeechCore library is supported on 32/64-bit **Windows** (`.dll`), x64 and arm64 **Linux** (`.so`) and **macOS**. No executable exists for LeechCore - the library is always loaded by other applications using it - such as PCILeech and MemProcFS.\n\nFor detailed information about individual memory acquisition methods, the API and related examples please check out the [LeechCore wiki](https://github.com/ufrisk/LeechCore/wiki).\n\n\n\nMemory Acquisition Methods:\n===========================\n### Software based memory aqusition methods:\n\nPlease 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.\n\n| Device                     | Type             | Volatile | Write | Linux Support | Plugin |\n| ---------------------------------------------------------------------------------------- | ---------------- | -------- | ----- | ------------- | ------ |\n| [RAW physical memory dump](https://github.com/ufrisk/LeechCore/wiki/Device_File)         | File             | No  | No  | Yes | No  |\n| [Full Microsoft Crash Dump](https://github.com/ufrisk/LeechCore/wiki/Device_File)        | File             | No  | No  | Yes | No  |\n| [Full ELF Core Dump](https://github.com/ufrisk/LeechCore/wiki/Device_File)               | File             | No  | No  | Yes | No  |\n| [QEMU](https://github.com/ufrisk/LeechCore/wiki/Device_QEMU)                             | Live\u0026nbsp;Memory | Yes | Yes | No  | No  |\n| [VMware](https://github.com/ufrisk/LeechCore/wiki/Device_VMWare)                         | Live\u0026nbsp;Memory | Yes | Yes | No  | No  |\n| [VMware memory save file](https://github.com/ufrisk/LeechCore/wiki/Device_File)          | File             | No  | No  | Yes | No  |\n| [TotalMeltdown](https://github.com/ufrisk/LeechCore/wiki/Device_Totalmeltdown)           | CVE-2018-1038    | Yes | Yes | No  | No  |\n| [DumpIt /LIVEKD](https://github.com/ufrisk/LeechCore/wiki/Device_DumpIt)                 | Live\u0026nbsp;Memory | Yes | No  | No  | No  |\n| [WinPMEM](https://github.com/ufrisk/LeechCore/wiki/Device_WinPMEM)                       | Live\u0026nbsp;Memory | Yes | No  | No  | No  |\n| [LiveKd](https://github.com/ufrisk/LeechCore/wiki/Device_LiveKd)                         | Live\u0026nbsp;Memory | Yes | No  | No  | No  |\n| [LiveCloudKd](https://github.com/ufrisk/LeechCore/wiki/Device_LiveCloudKd)               | Live\u0026nbsp;Memory | Yes | Yes | No  | Yes |\n| [libmicrovmi](https://github.com/ufrisk/LeechCore-plugins#leechcore_device_microvmi)     | Live\u0026nbsp;Memory | Yes | Yes | Yes | Yes |\n| [Hyper-V Saved State](https://github.com/ufrisk/LeechCore/wiki/Device_HyperV_SavedState) | File             | No  | No  | No  | Yes |\n| [LeechAgent*](https://github.com/ufrisk/LeechCore/wiki/Device_Remote)                    | Remote           |     |     | No  | No  |\n\n### Hardware based memory aqusition methods:\n\nPlease 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.\n| Device                                                                                     | Type | Interface | Speed | 64-bit memory access | PCIe TLP access | Project\u003cbr\u003eSponsor |\n| -------------------------------------------------------------------------------------------| ---- | --------- | ----- | -------------------- | --------------- | ------------------ |\n| [Screamer PCIe Squirrel](https://github.com/ufrisk/pcileech-fpga/tree/master/PCIeSquirrel) | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)          | USB-C | 190MB/s  | Yes | Yes | 💖 |\n| [ZDMA](https://github.com/ufrisk/pcileech-fpga-dev/blob/master/ZDMA)                       | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)   | Thunderbolt3 | 1000MB/s | Yes | Yes | 💖 |\n| [GBOX](https://github.com/ufrisk/pcileech-fpga-dev/blob/master/GBOX)                       | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)        | OCuLink |  400MB/s | Yes | Yes | 💖 |\n| [LeetDMA](https://github.com/ufrisk/pcileech-fpga)                                         | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)          | USB-C | 190MB/s  | Yes | Yes | 💖 |\n| [CaptainDMA M2](https://github.com/ufrisk/pcileech-fpga)                                   | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)          | USB-C | 190MB/s  | Yes | Yes | 💖 |\n| [CaptainDMA 4.1th](https://github.com/ufrisk/pcileech-fpga)                                | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)          | USB-C | 190MB/s  | Yes | Yes | 💖 |\n| [CaptainDMA 75T](https://github.com/ufrisk/pcileech-fpga)                                  | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)          | USB-C | 200MB/s  | Yes | Yes | 💖 |\n| [CaptainDMA 100T](https://github.com/ufrisk/pcileech-fpga)                                 | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)          | USB-C | 220MB/s  | Yes | Yes | 💖 |\n| [AC701/FT601](https://github.com/ufrisk/pcileech-fpga/tree/master/ac701_ft601)             | [FPGA](https://github.com/ufrisk/LeechCore/wiki/Device_FPGA)          | USB3  | 190MB/s  | Yes | Yes |    |\n| USB3380-EVB                                                                                | [USB3380](https://github.com/ufrisk/LeechCore/wiki/Device_USB3380)    | USB3  | 150MB/s  | No  | No  |    |\n| DMA patched HP iLO                                                                         | [BMC](https://github.com/ufrisk/LeechCore/wiki/Device_RawTCP)         | TCP   |  1MB/s   | Yes | No  |    |\n\n\n\nThe LeechAgent Memory Acquisition and Analysis Agent:\n=====================================================\nThe LeechAgent Memory Acquisition and Analysis Agent exists for Windows only. It allows users of the LeechCore library (PCILeech and MemProcFS) to connect to remotely installed LeechAgents over the network. The connection is secured, by default, with mutually authenticated encrypted kerberos.\n\nOnce connected physical memory may be acquired over the secure compressed connection. Memory analysis scripts, written in Python, may also be submitted for remote processing by the LeechAgent.\n\nThe LeechAgent authenticates all incoming connections against membership in the Local Administrators group. The clients must also authenticate the agent itself against the SPN used by the agent - please check the Application Event Log for information about the SPN and also successful authentication events against the agent.\n\nThere is also a possibility to run the LeechAgent in interactive mode (as a normal program). If run in interactive mode a user may also start the LeechAgent in \"insecure\" mode - which means no authentication or logging at all.\n\nThe LeechAgent listens on the port `tcp/28473` - please ensure network connectivity for this port in the firewall. Also, if doing live capture ensure that LeechAgent (if running in interactive mode) is started as an administrator.\n\nFor more information please check the [LeechCore wiki](https://github.com/ufrisk/LeechCore/wiki) and the [blog entry](http://blog.frizk.net/2019/04/LeechAgent.html) about remote live memory capture with the LeechAgent.\n\nThe videos below shows the process of installing the LeechAgent to a remote computer, connecting to it with MemProcFS to analyze and dump the memory while also connecting to it in parallel with PCILecch to submit a Python memory analysis script that make use of the MemProcFS API to analyze the remote CPU page tables for rwx-sections.\n\u003cp align=\"center\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/wiki/ufrisk/LeechCore/resources/agent-anim.gif\"/\u003e\u003c/p\u003e\n\n**Examples:**\n\nInstalling the LeechAgent on the local system (run as elevated administrator)'. Please ensure that the LeechAgent.exe is on the local C: drive before installing the agent service. Please also ensure that dependencies such as required `.dll` and/or `.sys` files (and optional Python sub-subfolder) are put in the same directory as the LeechAgent before running the install command.\n* `LeechAgent.exe -install`\n\nInstalling the LeechAgent on a remote system (or on the local system) in the `Program Files\\LeechAgent` folder. An Actice Directory environment with remote access to the Service Manager of the target system is required. For additional information see the [wiki entry](https://github.com/ufrisk/LeechCore/wiki/LeechAgent_Install) about installing LeechAgent.\n* `LeechAgent.exe -remoteinstall \u003cremotecomputer.contoso.com\u003e`\n\nUninstall an existing, locally installed, LeechAgent. The agent service will be uninstalled but any files will remain.\n* `LeechAgent.exe -uninstall`\n\nUninstall a LeechAgent from a remote system and delete the `Program Files\\LeechAgent` folder.\n* `LeechAgent.exe -remoteuninstall \u003cremotecomputer.contoso.com\u003e`\n\nStart the LeechAgent in interactive mode only accepting connections from administative users over kerberos-secured connections. Remember to start as elevated administrator if clients accessing LeechAgent should load WinPMEM to access live memory.\n* `LeechAgent.exe -interactive`\n\nStart the LeechAgent in interactive insecure mode - accepting connections from all clients with access to port `tcp/28473`. NB! unauthenticated clients may dump memory and submit Python scripts running as SYSTEM. Use with care for testing only!\n* `LeechAgent.exe -interactive -insecure`\n\nStart the LeechAgent in interactive mode with DumpIt LIVEKD to allow connecting clients to access live memory. Start as elevated administrator. Only accept connections from administative users over kerberos-secured connections. \n* `DumpIt.exe /LIVEKD /A LeechAgent.exe /C -interactive`\n\nStart the LeechAgent in interactive mode with DumpIt LIVEKD to allow connecting clients to access live memory. Start as elevated administrator. Accept connections from all clients with access to port `tcp/28473` without any form of authentication.\n* `DumpIt.exe /LIVEKD /A LeechAgent.exe /C \"-interactive -insecure\"`\n\n\nPCILeech and MemProcFS community:\n=========\nFind all this a bit overwhelming? Or just want to ask a quick question? Join the PCILeech and MemProcFS DMA community server at Discord!\n\n\u003ca href=\"https://discord.gg/pcileech\"\u003e\u003cimg src=\"https://discord.com/api/guilds/1155439643395883128/widget.png?style=banner3\"/\u003e\u003c/a\u003e\n\n\n\nBuilding:\n=========\n\u003cb\u003ePre-built [binaries, modules and configuration files](https://github.com/ufrisk/LeechCore/releases/latest) are found in the latest release.\u003c/b\u003e Build instructions are found in the [Wiki](https://github.com/ufrisk/LeechCore/wiki) in the [Building](https://github.com/ufrisk/LeechCore/wiki/Dev_Building) section.\n\n\n\nContributing:\n=============\nPCILeech, MemProcFS and LeechCore are open source but not open contribution. PCILeech, MemProcFS and LeechCore offers a highly flexible plugin architecture that will allow for contributions in the form of plugins. If you wish to make a contribution, other than a plugin, to the core projects please contact me before starting to develop.\n\n\n\nLinks:\n======\n* Twitter: [![Twitter](https://img.shields.io/twitter/follow/UlfFrisk?label=UlfFrisk\u0026style=social)](https://twitter.com/intent/follow?screen_name=UlfFrisk)\n* Discord: [![Discord | PCILeech/MemProcFS](https://img.shields.io/discord/1155439643395883128.svg?label=\u0026logo=discord\u0026logoColor=ffffff\u0026color=7389D8\u0026labelColor=6A7EC2)](https://discord.gg/pcileech)\n* PCILeech: https://github.com/ufrisk/pcileech\n* PCILeech FPGA: https://github.com/ufrisk/pcileech-fpga\n* LeechCore: https://github.com/ufrisk/LeechCore\n* MemProcFS: https://github.com/ufrisk/MemProcFS\n* Blog: http://blog.frizk.net\n\n\n\nSupport PCILeech/MemProcFS development:\n=======================================\nPCILeech and MemProcFS is free and open source!\n\nI 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! \n \nIf 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`](https://github.com/sponsors/ufrisk)\n\nTo all my sponsors, Thank You 💖 \n\nAll sponsorships are welcome, no matter how large or small. I especially wish to thank my **bronze sponsors**: [grandprixgp](https://github.com/grandprixgp).\n\n\n\nChangelog:\n===================\n\u003cdetails\u003e\u003csummary\u003ePrevious releases (click to expand):\u003c/summary\u003e\nv1.0-1.8\n* Initial Release and various updates. Please see individual relases for more information.\n\n[v2.0](https://github.com/ufrisk/LeechCore/releases/tag/v2.0)\n* API: New handle based API to support multiple concurrent open devices.\u003cbr\u003e\n  NB! API contains breaking changes compared to v1.x API versions.\n* FPGA related performance improvements and bug fixes.\n* New features:\n  - AMD support.\n  - User-settable physical memory map.\n  - External device plugins - see the [LeechCore-plugin](https://github.com/ufrisk/LeechCore-plugins) project for details.\n  - Sysinternals LiveKd Hyper-V VM-introspection (slow).\n\n[v2.1](https://github.com/ufrisk/LeechCore/releases/tag/v2.1)\n* Bug fixes.\n* Support for [LiveCloudKd](https://github.com/ufrisk/LeechCore/wiki/Device_LiveCloudKd).\n\n[v2.2](https://github.com/ufrisk/LeechCore/releases/tag/v2.2)\n* Bug fixes.\n* Minor API additions.\n\n[v2.3](https://github.com/ufrisk/LeechCore/releases/tag/v2.3)\n* FPGA: R/W \"shadow\" config space (requires v4.9+ bitstream).\n* LeechAgent: Full multi-device support.\n\n[v2.4](https://github.com/ufrisk/LeechCore/releases/tag/v2.4)\n* Bug fixes.\n* Remake of Python package `leechcorepyc` now also available on [pip](https://pypi.org/project/leechcorepyc/).\n\n[v2.5](https://github.com/ufrisk/LeechCore/releases/tag/v2.5)\n* Bug fixes.\n* Read/Write PCI Express Transaction Layer Packets, PCIe TLPs, FPGA devices only.\n\n[v2.6](https://github.com/ufrisk/LeechCore/releases/tag/v2.6)\n* Bug fixes.\n* Updates to support MemProcFS v4.\n* Separate releases for Windows and Linux.\n\n[v2.7](https://github.com/ufrisk/LeechCore/releases/tag/v2.7)\n* Bug fixes.\n* Remote LeechAgent support for MemProcFS.\n* VMWare live memory VM introspection (Windows host only).\n\n[v2.8](https://github.com/ufrisk/LeechCore/releases/tag/v2.8)\n* Bug fixes.\n* 32-bit support.\n* Support for Active Memory and Full Bitmap Microsoft Crash Dump files.\n\n[v2.9](https://github.com/ufrisk/LeechCore/releases/tag/v2.9)\n* Support for the FT2232H USB2 chip.\n\n[v2.10](https://github.com/ufrisk/LeechCore/releases/tag/v2.10)\n* Support for [Enigma X1](https://github.com/ufrisk/pcileech-fpga/tree/master/EnigmaX1) hardware.\n* [Plugin support](https://github.com/ufrisk/LeechCore-plugins/blob/master/README.md#leechcore_device_microvmi) for [libmicrovmi](https://github.com/Wenzel/libmicrovmi):\n  - Support for Xen, KVM, VirtualBox, QEMU on Linux.\n  - Pre-bundled on Linux x64 (libmicrovmi)\n  - Thank you [Wenzel](https://github.com/Wenzel/) for this contribution.\n\n[v2.11](https://github.com/ufrisk/LeechCore/releases/tag/v2.11)\n* Bug fixes.\n* Visual Studio 2022 Support.\n* New write fpga algorithm.\n\n[v2.12](https://github.com/ufrisk/LeechCore/releases/tag/v2.12)\n* Support for MemProcFS v5.\n\n[v2.13](https://github.com/ufrisk/LeechCore/releases/tag/v2.13)\n* FPGA performance improvements.\n* ARM64 Windows support.\n\n[v2.14](https://github.com/ufrisk/LeechCore/releases/tag/v2.14)\n* VMM loopback device.\n\n[v2.15](https://github.com/ufrisk/LeechCore/releases/tag/v2.15)\n* Multi-threaded file access.\n* Volatile memory file support.\n* Support for LiME memory dump files.\n* Improved FPGA performance for smaller reads.\n* QEMU support on Linux (VM live memory introspection).\n* Improved [MemProcFS remoting](https://github.com/ufrisk/MemProcFS/wiki/_Remoting) via a remote [LeechAgent](https://github.com/ufrisk/LeechCore/wiki/LeechAgent). Full MemProcFS remote support over SMB - tcp/445. Perfect for memory forensics Incident Response (IR)!\n\n[v2.16](https://github.com/ufrisk/LeechCore/releases/tag/v2.16)\n* PCIe BAR information and user callback (easier implementation of custom devices).\n* ARM64 memory dump (.dmp) and VMWare Fusion (.vmem/.vmsn) support.\n* Improved handling of PCIe TLP user callback.\n\u003c/details\u003e\n\n[v2.17](https://github.com/ufrisk/LeechCore/releases/tag/v2.17)\n* Bug fixes.\n* I/O BAR support.\n* Support for plugin device drivers.\n* Linux PCIe FPGA performance improvements.\n* Linux PCIe FPGA multiple devices (devindex) supported.\n\n[v2.18](https://github.com/ufrisk/LeechCore/releases/tag/v2.18)\n* Bug fixes.\n* Hibernation file support.\n\n[v2.19](https://github.com/ufrisk/LeechCore/releases/tag/v2.19)\n* Bug fixes.\n* Windows 11 24H2 hibernation file support.\n* ZDMA fast-write \"lockless\" support.\n\n[v2.20](https://github.com/ufrisk/LeechCore/releases/tag/v2.20)\n* macOS support\n\n[v2.21](https://github.com/ufrisk/LeechCore/releases/tag/v2.21)\n* LeechAgent gRPC support.\n* LeechAgent Linux support.\n* **Breaking change**: LeechAgent is incompatible with previous versions (unless compressed memory is explicitly disabled).\n\n[v2.22](https://github.com/ufrisk/LeechCore/releases/tag/v2.22)\n* Support for FTDI FT601 driver 1.4 (FTD3XXWU.dll)\n","funding_links":["https://github.com/sponsors/ufrisk"],"categories":["Exploitation Tools","Forensics"],"sub_categories":["Unikernel-like","Steganography"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fufrisk%2FLeechCore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fufrisk%2FLeechCore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fufrisk%2FLeechCore/lists"}