{"id":17263406,"url":"https://github.com/0vercl0k/clairvoyance","last_synced_at":"2025-06-13T18:38:40.038Z","repository":{"id":45815535,"uuid":"320636476","full_name":"0vercl0k/clairvoyance","owner":"0vercl0k","description":"Visualize the virtual address space of a Windows process on a Hilbert curve.","archived":false,"fork":false,"pushed_at":"2021-03-16T01:55:54.000Z","size":4497,"stargazers_count":300,"open_issues_count":1,"forks_count":22,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-08T04:18:37.297Z","etag":null,"topics":["address-space","hilbert-curve","kernel-dump","space-filling-curves","windows"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0vercl0k.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}},"created_at":"2020-12-11T17:11:42.000Z","updated_at":"2025-03-25T08:25:50.000Z","dependencies_parsed_at":"2022-07-26T05:16:30.915Z","dependency_job_id":null,"html_url":"https://github.com/0vercl0k/clairvoyance","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/0vercl0k/clairvoyance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0vercl0k%2Fclairvoyance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0vercl0k%2Fclairvoyance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0vercl0k%2Fclairvoyance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0vercl0k%2Fclairvoyance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0vercl0k","download_url":"https://codeload.github.com/0vercl0k/clairvoyance/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0vercl0k%2Fclairvoyance/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259699973,"owners_count":22898362,"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":["address-space","hilbert-curve","kernel-dump","space-filling-curves","windows"],"created_at":"2024-10-15T07:56:25.699Z","updated_at":"2025-06-13T18:38:40.017Z","avatar_url":"https://github.com/0vercl0k.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔮 clairvoyance\n![Builds](https://github.com/0vercl0k/clairvoyance/workflows/Builds/badge.svg)\n\nClairvoyance (/**klɛərˈvɔɪəns**/; from French clair meaning *clear* and voyance meaning *vision*) from [Wikipedia](https://en.wikipedia.org/wiki/Clairvoyance).\n\n\u003cp align='center'\u003e\n\u003cimg src='pics/ida64_dmp-ph.annotated.png' width=60% alt='clairvoyance'\u003e\n\u003c/p\u003e\n\n## Overview\n\n**clairvoyance** creates a colorful visualization of the page protection of an entire 64-bit process address space (user and kernel) running on a Windows 64-bit kernel.\n\nTo transform the 1 dimension space, that is the address space, into a 2 dimensions visualization, the [hilbert space-filling curve](https://en.wikipedia.org/wiki/Hilbert_curve) is used. Each colored pixel on the above picture represents the page protection (*UserRead*, *UserReadWrite*, etc.) of a 4KB page in virtual memory.\n\nThe address space is directly calculated by manually parsing the [four-level](https://en.wikipedia.org/wiki/X86-64#Virtual_address_space_details) page tables hierarchy associated with a process from a kernel crash-dump that has been generated using [WindDbg](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools).\n\nFinally, the program program outputs a file with the metadata required to have it displayed on a two dimensional canvas as well as being able to calculate the virtual address corresponding to a specific highlighted pixel.\n\nCompiled binaries are available in the [releases](https://github.com/0vercl0k/clairvoyance/releases) section. An online viewer is also hosted at [0vercl0k.github.io/clairvoyance](https://0vercl0k.github.io/clairvoyance).\n\nShouts out to:\n- [Alexandru Radocea](https://twitter.com/defendtheworld) and [Georg Wicherski](https://twitter.com/ochsff) for the inspiration (see their BlackHat USA 2013 research: *[Visualizing Page Tables for Exploitation](https://media.blackhat.com/us-13/US-13-Wicherski-Hacking-like-in-the-Movies-Visualizing-Page-Tables-WP.pdf)*),\n- [The Hacker's delight second edition](https://www.amazon.com/Hackers-Delight-2nd-Henry-Warren/dp/0321842685)'s chapter 16 *Hilbert's curve* for providing the algorithms used.\n\n## Usage\n\nTo generate the kernel crash dump it is recommended to use [WinDbg](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/debugger-download-tools), [KDNet](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/setting-up-a-network-debugging-connection-automatically) with the [.dump /f](https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/-dump--create-dump-file-) command.\n\nOnce the dump has been acquired you can pass its path to clairvoyance as well as the physical address of the page directory you are interested in:\n\n```\n./clairvoyance \u003cdump path\u003e [\u003cpage dir pa\u003e]\n```\n\nThis generates a file with the *clairvoyance* extension that you then can visualize in your browser at [0vercl0k.github.io/clairvoyance](https://0vercl0k.github.io/clairvoyance) or by checking out the [gh-pages](https://github.com/0vercl0k/clairvoyance/tree/gh-pages) branch which is where the viewer is hosted at.\n\n\n\u003cp align='center'\u003e\n\u003cimg src='pics/clairvoyance.gif' width=100% alt='clairvoyance'\u003e\n\u003c/p\u003e\n\n## Build\n\nThe [CI](https://github.com/0vercl0k/clairvoyance/blob/main/.github/workflows/clairvoyance.yml) builds clairvoyance on Linux using [clang++-11](https://clang.llvm.org/) and on Windows using Microsoft's [Visual studio 2019](https://visualstudio.microsoft.com/vs/community/).\n\nTo build it yourself you can use the scripts in [build/](https://github.com/0vercl0k/clairvoyance/blob/main/build):\n\n```\n(base) clairvoyance\\build\u003ebuild-msvc.bat\n(base) clairvoyance\\build\u003ecmake ..\n-- Selecting Windows SDK version 10.0.19041.0 to target Windows 10.0.19042.\n-- Configuring done\n-- Generating done\n-- Build files have been written to: clairvoyance/build\n\n(base) clairvoyance\\build\u003ecmake --build . --config RelWithDebInfo\nMicrosoft (R) Build Engine version 16.8.2+25e4d540b for .NET Framework\nCopyright (C) Microsoft Corporation. All rights reserved.\n\n  clairvoyance.vcxproj -\u003e clairvoyance\\build\\RelWithDebInfo\\clairvoyance.exe\n  Building Custom Rule clairvoyance/CMakeLists.txt\n```\n\n## Various findings\n\nThe below are things I've noticed on a kernel crash-dump generated from an Hyper-V VM of Windows:\n\n```\nkd\u003e vertarget\nWindows 10 Kernel Version 18362 UP Free x64\nProduct: WinNt, suite: TerminalServer SingleUserTS\nEdition build lab: 18362.1.amd64fre.19h1_release.190318-1202\nMachine Name:\nKernel base = 0xfffff805`36800000 PsLoadedModuleList = 0xfffff805`36c432f0\nDebug session time: Sat Jul 25 10:00:19.637 2020 (UTC - 8:00)\nSystem Uptime: 0 days 0:18:53.609\n```\n\n### Type of pages\n\nWindows doesn't seem to be using huge pages (1GB) or at least I have not seen one being used in any of the dumps I collected.\n\nLarge pages are used in abundance to map some kernel executables like the Windows kernel *nt* for example:\n\n```\nkd\u003e ? nt\nEvaluate expression: -8773703827456 = fffff805`36800000\n```\n\n```\nVA:0xfffff80536800000, PA:0x2400000 (KernelReadWriteExec, Large, PML4E:0xd5745f80, PDPTE:0x42080a0, PDE:0x4209da0, PTE:0x0)\n```\n\nThere are also a bunch of kernel read, write, executable pages that are not large pages, which was somewhat a surprise. I was aware that the kernel / hal\ncould be mapped using large pages and that those were *krwx*. The reason for that is that 2MB is so large that it spans both executable and data sections; meaning the page has to be writeable and executable.\n\nThe only public mention of this I could find is in this [blogpost](https://nadav.amit.zone/windows/2018/09/15/windows-pti.html) (thx [`Ivan](https://twitter.com/ivanlef0u)):\n\n\n\u003e I contacted Microsoft which claimed that this is intended since “in some cases the kernel is mapped with large pages” and that this can be prevented by enabling virtualization based protection (VBS).\n\n### Virtual address sinks\n\nA bunch of large kernel memory sections are mapped against the same physical page (filled with zero):\n\n```\nVA:0xffffc27ef4401000, PA:0x4200000 (KernelRead, Normal, ...)\nVA:0xffffc27ef4402000, PA:0x4200000 (KernelRead, Normal, ...)\nVA:0xffffc27ef4403000, PA:0x4200000 (KernelRead, Normal, ...)\n...\nVA:0xffffc27ef63fb000, PA:0x4200000 (KernelRead, Normal, ...)\nVA:0xffffc27ef63fc000, PA:0x4200000 (KernelRead, Normal, ...)\nVA:0xffffc27ef63fd000, PA:0x4200000 (KernelRead, Normal, ...)\nVA:0xffffc27ef63fe000, PA:0x4200000 (KernelRead, Normal, ...)\nVA:0xffffc27ef63ff000, PA:0x4200000 (KernelRead, Normal, ...)\n```\n\nHere is smaller one (the region is not completely contiguous, there are a few holes):\n\n```\nVA:0xffffc27ed2201000, PA:0x4300000 (KernelRead, Normal, ...)\nVA:0xffffc27ed2202000, PA:0x4300000 (KernelRead, Normal, ...)\nVA:0xffffc27ed2203000, PA:0x4300000 (KernelRead, Normal, ...)\n...\nVA:0xffffc27ed25fc000, PA:0x4300000 (KernelRead, Normal, ...)\nVA:0xffffc27ed25fd000, PA:0x4300000 (KernelRead, Normal, ...)\nVA:0xffffc27ed25fe000, PA:0x4300000 (KernelRead, Normal, ...)\nVA:0xffffc27ed25ff000, PA:0x4300000 (KernelRead, Normal, ...)\n```\n\n### Gallery of patterns\n\nThis is just a section showing off some of the cool patterns you can see in some regions of an address space.\n\n#### Page heap\n\nPage heap allocations and their guard pages are pretty cool looking and easy to spot:\n\n\u003cp align='center'\u003e\n\u003cimg src='pics/ph.png' width=80% alt='ph'\u003e\n\u003c/p\u003e\n\n#### Kernel stacks\n\nKernel stacks also have a nice recognizable shape because of their size and guard pages:\n\n\u003cp align='center'\u003e\n\u003cimg src='pics/kstack.png' width=85% alt='kstack'\u003e\n\u003c/p\u003e\n\n### System cache\n\nThe system cache region in the kernel seems to be looking like a nebula in the dumps I have seen:\n\n\u003cp align='center'\u003e\n\u003cimg src='pics/systemcache.png' width=90% alt='systemcache'\u003e\n\u003c/p\u003e\n\n## Authors\n\nAxel '[0vercl0k](https://twitter.com/0vercl0k)' Souchet\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0vercl0k%2Fclairvoyance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0vercl0k%2Fclairvoyance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0vercl0k%2Fclairvoyance/lists"}