{"id":13799255,"url":"https://github.com/msuiche/LiveCloudKd","last_synced_at":"2025-05-13T06:32:44.674Z","repository":{"id":65319525,"uuid":"137635350","full_name":"msuiche/LiveCloudKd","owner":"msuiche","description":"Hyper-V Research is trendy now","archived":false,"fork":false,"pushed_at":"2024-05-06T05:02:25.000Z","size":12810,"stargazers_count":178,"open_issues_count":1,"forks_count":47,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-10T06:57:10.332Z","etag":null,"topics":["memory-forensics","virtual-machines"],"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/msuiche.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2018-06-17T06:58:52.000Z","updated_at":"2025-03-15T04:49:54.000Z","dependencies_parsed_at":"2024-05-06T06:23:47.191Z","dependency_job_id":"937a52e5-a582-4743-83b0-1a3e210d633f","html_url":"https://github.com/msuiche/LiveCloudKd","commit_stats":null,"previous_names":["comaeio/livecloudkd"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msuiche%2FLiveCloudKd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msuiche%2FLiveCloudKd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msuiche%2FLiveCloudKd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msuiche%2FLiveCloudKd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msuiche","download_url":"https://codeload.github.com/msuiche/LiveCloudKd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253889242,"owners_count":21979591,"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":["memory-forensics","virtual-machines"],"created_at":"2024-08-04T00:01:00.358Z","updated_at":"2025-05-13T06:32:42.371Z","avatar_url":"https://github.com/msuiche.png","language":"C","funding_links":[],"categories":["\u003ca name=\"security_tools\" /\u003eSecurity Research Tools"],"sub_categories":[],"readme":"# LiveCloudKd\n## Introduction\nLiveCloudKd was the first utility to focus on Virtual Machine introspection for memory forensics purposes, it was released in 2010 after some initial research on Hyper-V v1.\n\nThis feature was later added into LiveKd 5.0 by Mark Russinovich and Ken Johnson.\nhttps://blogs.technet.microsoft.com/markrussinovich/2010/10/09/livekd-for-virtual-machine-debugging/\n\n### Original Author\n- Matt Suiche [(www.msuiche.com)](https://www.msuiche.com)\n### Maintainer\n- [@gerhart_x](https://twitter.com/gerhart_x)\n\n## Getting Started\nConfigure symbol path:\n``` \nmkdir C:\\Symbols\ncompact /c /i /q /s:C:\\Symbols\nsetx /m _NT_SYMBOL_PATH SRV*C:\\Symbols*https://msdl.microsoft.com/download/symbols\n```\n\nFor launch:\n\n1. Extract LiveCloudKd.exe, hvlib.dll, hvmm.sys to WinDBG x64 folder (tested on WinDBG from WDK 1809 - 23H2) or separate folder (use /y key for specify directory with WinDBG). \n   Also LiveCloudKd can find path to WinDBG, if it was installed with Windows WDK or SDK\n2. Launch LiveCloudKd.exe with admin rights (It needs Visual Studio 2022 runtime libraries - https://aka.ms/vs/17/release/vc_redist.x64.exe).\n3. Choose Hyper-V virtual machine for inspection.  \n\nWhen starting LiveCloudKd searches WinDBG in next steps:\n\n1. Standard Windows SDK installation folder (using register key)\n2. in Windows Registry HKLM\\Software\\LiveCloudKd\\Parameters in WinDbgPath key. See RegParam.key for instance. \n3. Set /y parameter with WinDBG path, for instance: \n\n```\nLiveCloudKd /y C:\\Microsoft\\WinDBG\n```\n\n4. If previous result is not successfully, LiveCloudKd tries to run kd.exe from same folder.\n\nPerformance comparison with LiveKd from Sysinternals Suite, at the time of release (LiveCloudKd is more performance: about 1000 times using ReadInterfaceHvmmDrvInternal interface):\n\n![](images/image02.png)\n\nLiveCloudKd options:\n\n``` \n      /a        Pre-selected action.\n                   0 - Live kernel debugging\n                   1 - Start EXDi plugin (WinDBG)\n                   2 - Produce a linear physical memory dump\n                   3 - Produce a Microsoft full memory crash dump\n                   4 - Dump guest OS memory chunk\n                   5 - Dump RAW guest OS memory (without KDBG scanning)\n                   6 - Resume VM\n      /b        Close LiveCloudKd automatically, after exiting from kd or WinDBG.\n      /f        Force freeze CPU on every read operations. It is actual for Windows Sandbox, because it constantly resume CPU.\n      /m        Memory access type.\n                   0 - Winhvr.sys interface\n                   1 - Raw memory interface (hvmm.sys)\n      /n        Pre-selected number of VM.\n      /o        Destination path for the output file (Action 1 - 5).\n      /p        Pause partition.\n      /v        Verbose output.\n      /w        Run Windbg instead of Kd (Kd is the default).\n      /y        Set path to WinDBG or WinDBG with modern UI (for start EXDi plugin)\n      /?        Print this help.\n``` \n\nProject uses diStorm3 library (BSD license) by [Gil Dabah](https://twitter.com/_arkon): [Distorm project](https://github.com/gdabah/distorm)\n\n## Changelog\n### LiveCloudKd (2024)\n\nLiveCloudKd is tool, that allows you connect to Hyper-V guest VM with kd.exe (or WinDBG.exe and WinDBG with modern UI). \n\nAlso you can use LiveCloudKd EXDi plugin for attaching to Hyper-V VM.  \n\nTool uses Hyper-V Memory Manager plugin for operations with Hyper-V memory.\nTool has additional options in compare with LiveKd from Microsoft Sysinternals Suite:\n\n1. Write capabilities (you can write to Hyper-V VM in virtual and physical address space using native WinDBG commands)\n2. More performance\n3. Support Hyper-V VM with nested option enabled on Intel based CPU\n4. Support multilanguage OS\n\nLiveCloudKd. [Download](https://github.com/gerhart01/LiveCloudKd/releases/download/v2.6.1.20240228/LiveCloudKd.v2.6.1.20240228-release.zip)  \nContains EXDi plugin:  \n\n![WinDBG](images/image03.png)\n![WinDBG with modern UI](images/image04.png)\n\nLiveCloudKd based on hvlib.dll library (Hyper-V memory manager plugin). Other tools, that were developed using this library:\n\nLiveCloudKd EXDi debugger. [Download](https://github.com/gerhart01/LiveCloudKd/releases/download/v1.0.22021109/LiveCloudKd.EXDi.debugger.v1.0.22021109.zip). [Readme](https://github.com/gerhart01/LiveCloudKd/blob/master/ExdiKdSample/LiveDebugging.md)    \nHyper-V Virtual Machine plugin for MemProcFS. [Download](https://github.com/gerhart01/LiveCloudKd/releases/download/v1.2.20240228/leechcore_hyperv_plugin_28.02.2024.zip)  \nHyper-V Memory Manager plugin for volatility. [Download](https://github.com/gerhart01/Hyper-V-Tools/releases/download/1.0.20221109/Hyper-V.Memory.Manager.plugin.for.volatility.v1.0.20221109.zip)  \n\nMethods for accessing guest Hyper-V VM memory: \n\t`ReadInterfaceWinHv` - uses Hyper-V hypercall for reading guest OS memory. Slow, but robust method; \n\t`ReadInterfaceHvmmDrvInternal` - read data directly from kernel memory. Faster, then ReadInterfaceWinHv, but uses undocument structures). See description of -m option. Default reading method is ReadInterfaceHvmmDrvInternal.\n\t\n\t`WriteInterfaceWinHv` - uses Hyper-V hypercall for writing to guest OS memory.\n\t`WriteInterfaceHvmmDrvInternal` - write data directly to kernel memory. Faster, then WriteInterfaceWinHv, but uses undocument structures). See description of -m option. Default writing method is WriteInterfaceHvmmDrvInternal.\n\nLiveCloudKd was tested on Windows Server 2016, Windows Server 2019, Windows Server 2022, Windows 10 and Windows 11 operations system (some of preview versions of Windows 11 and Windows Server vNext including Windows Server 2025)\n\n### LiveCloudKd (2019+) (Beta)\n\nAdded new methods for accessing guest Hyper-V VM Memory: \n- `ReadInterfaceWinHv` - uses Hyper-V hypercall for reading guest OS memory. Slow, but robust method; \n- `ReadInterfaceHvmmDrvInternal` - read data directly from kernel memory. Much faster, then ReadInterfaceWinHv, but uses undocument structures). See description of -m option. Default reading method is ReadInterfaceHvmmDrvInternal.\n- `ReadInterfaceVidAux` - uses vidaux.dll library, which must be injected in vmwp.exe process, for access to Microsoft vid.dll API.\n- `ReadInterfaceVidNative` - uses native vid.dll without driver. Can be used for Windows Server 2012\\2012 R2\\2016 Hyper-V. \n- `WriteInterfaceWinHv` - uses Hyper-V hypercall for writing to guest OS memory. Use EXDi interface for it (/x or /w options). See ExdiKdSample README for more details.\n- `ReadInterfaceHvmmDrvInternal` was tested on Windows Server 2016, Windows Server 2019 (july 2019 updates), Windows 10 x64 1803, 1809, 18362.\n- `ReadInterfaceVidNative` was tested on Windows Server 2012, Windows Server 2012 R2, Windows Server 2016.\n\n### LiveCloudKd (2018)\nAfter discussing with [@gerhart_x](https://twitter.com/gerhart_x) on why LiveCloudKd was not working anymore on the current version of Hyper-V, [@gerhart_x](https://twitter.com/gerhart_x) offered to work on an expiremental feature to revive LiveCloudKd again. Unfortunately, this requires a kernel driver.\n\nThanks to [@aionescu](https://twitter.com/aionescu) who pointed out to me the existence of the Windows Hypervisor Platform API (WHVP) where I noticed the presence of the [ReadGuestPhysicalAddress()](https://docs.microsoft.com/en-us/virtualization/api/vm-dump-provider/funcs/readguestphysicaladdress) API which is now publicly available as of Windows 1803 (10.0.17134.48). This may be a good lead to create a current lean version of LiveCloudKd and re-enable on the fly memory forensics for Hyper-V Virtual Machines.\n[Simpleator](https://github.com/ionescu007/Simpleator) is a great example of an application leveraging those APIs if you want to learn more about it.\n\n### LiveCloudKd (2010)\nOne of the initial attribute of LiveCloudKd is that the solution was completely user-mode (!!!) due to some design flaws inside vmwp.exe (Virtual Machine Worker's process).\n- The process had no isolation so it was possible to read its memory address space from another process running with administrator privileges.\n- Memory Block's handles were not indexes inside an object tables but kernel mode addresses pointing to those Memory Block kernel-objects. Yes, you read that correctly. vmwp.exe used to pass kernel-mode pointers to vid.sys \n- No official documentation was available regarding vmwp.exe vid.dll and the drivers winhv.sys and vid.sys BUT an Microsoft open-source project ([Singularity](https://en.wikipedia.org/wiki/Singularity_(operating_system))), that was focusing on experimenting .NET as a foundation for a new Operating System, leaked [full headers for Vid.dll (Virtualization Interface Driver)](https://searchcode.com/codesearch/view/10186291/). \n\nEach Virtual Machine has one vmwp.exe, which has one Partition Handle (PT_HANDLE) - and multiple Memory Block handles (MB_HANDLE), this is particularly true if the target Virtual Machine has the Dynamic Memory (VidDm*) feature enabled. \n\n#### Quest to PT_HANDLE\nFirst, we needed to retrive the original Partition Handle (PT_HANDLE) returned by VidCreatePartition() to the vmwp.exe. Unfortunately, no API was present to retrieve existing partition handles. But since the process was not isolated we could just look for handles within each `vmwp.exe` process with an object name starting with `\\\\Device\\\\000000`, and then we could validate each of the retrieved handles with a basic API call such as `VidGetPartitionFriendlyName()`.\nMore details are available in `[partition.c!IsPartitionHandle()](https://github.com/comaeio/LiveCloudKd/blob/master/hvdd/partition.c#L141)`:\n\n#### Quest to MB_HANDLE[]\nSecondly, once we recovered the valid Partition Handles corresponding to each Hyper-V Virtual Machine, we need to retrieve its Memory Block's Handles. This is where I brute-forced the memory address space of each `vmwp.exe` to collect all the kernel pointers before verifying if they were valid Memory Block handles or not. More details can be found in [`memoryblock.c!GetMemoryBlocks()`](https://github.com/comaeio/LiveCloudKd/blob/master/hvdd/memoryblock.c#L106). \nOnce we have a PT_HANDLE and a MB_HANDLE we can pass them as arguments to `VidReadMemoryBlockPageRange()`. Overall, LiveCloudKd was using only few Vid.dll functions:\n- VidDmMemoryBlockQueryTopology()\n- VidQueryMemoryBlockMbpCount()\n- VidGetPartitionFriendlyName()\n- VidTranslateGvaToGpa()\n- VidReadMemoryBlockPageRange()\n- VidGetVirtualProcessorState()\n\n#### From VidReadMemoryBlockPageRange() to WinDbg\nLast but not least, in order to create a `livekd` style image on the fly I would just hook the Export Address Table (EAT) of WinDbg.exe / kd.exe. More details can be found in [`DumpLiveVirtualMachine()`](https://github.com/comaeio/LiveCloudKd/blob/master/hvdd/dump.c#L214)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsuiche%2FLiveCloudKd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsuiche%2FLiveCloudKd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsuiche%2FLiveCloudKd/lists"}