![\"Monav3](\"https:\/\/www.corelan.be\/wp-content\/uploads\/2026\/04\/monav3-ascii-glow.png\" "\\"monav3")
<\/p>\n
This release has been a long time in the making.
\nWhile it still builds on some of the solid foundations of earlier versions, substantial parts of the codebase have been completely reworked, refactored, and modernized.<\/p>\n
The result is a cleaner and broader version of mona, with improved compatibility and a more consistent runtime across supported environments.<\/p>\n
What\u2019s new<\/h2>\nThe good news<\/h3>\n
This new version is not only faster and leaner, it also brings a broader and more flexible runtime:<\/p>\n
- \n
- Full support for Python 2 and<\/em> Python 3. We do recommend running mona on Python3<\/strong><\/li>\n
- Runs on WinDBG, WinDBGX, and Immunity Debugger<\/li>\n
- Works with both 32-bit and 64-bit processes<\/li>\n
- Uses a more recent pykd library and the pykd-ext bootstrapper<\/li>\n<\/ul>\n
Additionally, mona v3:<\/p>\n
- \n
- Relies less on pykd's access to symbols to run. Mona now natively does most of the heavy lifting, in a lot of areas of the process (modules, heap, etc).<\/li>\n
- Allows us to specify addresses, registers, symbol names, dereferenced registers with offsets, module names etc any time you can specific an address as an argument<\/li>\n
- Has improved table-based output<\/li>\n
- Features significant performance improvements in certain time-consuming routines (such as
mona rop<\/mono>)<\/li>\n - Helps you manage symbols, clean up unwanted disk space consumption caused by failed symbol file downloads<\/li>\n
- Has an improved wildcard search routine (
findwild<\/mono>)<\/li>\n - Shows an eta for long-running actions and searches<\/li>\n
- Allows you to interrupt long-running searches without killing your debugging session.<\/li>\n
- Uses clickable links in some output, making use and navigation even easier<\/li>\n<\/ul>\n
The vast majority of existing
mona<\/mono> commands remain available, and - as suggested in the list above - many have been improved in terms of behavior, stability, compatibility and\/or performance. <\/p>\n The overall goal remains unchanged: to deliver high-quality, actionable output out of the box<\/strong>, while still allowing detailed control over search scope and behavior. <\/p>\n
In addition, mona v3 includes a number of new features and commands.
\nSome of those will be covered in more detail in follow-up posts.<\/p>\nSo, that's the good news.<\/p>\n
Less-than-ideal news<\/h3>\n
There is also some less encouraging news to share.<\/p>\n
When I started developing the first version of
mona.py<\/mono> back in 2011, the primary goal was simple: make the tool easy to use and capable of producing actionable results out of the box. It was designed to run on a default installation of Python 2 together with Immunity Debugger \u2014 no additional libraries required.<\/p>\n Later, when adding support for WinDBG, that principle had to be relaxed with the introduction of the
pykd<\/mono> library.<\/p>\n Today, as part of the ongoing effort to bring more functionality into 64-bit debugging sessions, I ran into another limitation: WinDBG(X) does not natively support assembling 64-bit mnemonics.<\/p>\n
Crazy, right? \ud83e\udd37\ud83c\udffc\u200d\u2642\ufe0f<\/p>\n
Since
pykd<\/mono> depends on WinDBG and doesn't have its own built-in assembler, this created a new challenge: how to provide reliable 64-bit assembly capabilities without building and maintaining a custom assembler myself?<\/em><\/p>\n An initial attempt involved building a cache of commonly used instructions. However, while working on improvements to the
findwild<\/mono> wildcard search command, it quickly became clear that this approach would not scale in a practical or maintainable way.<\/p>\n For now, the solution is to rely on the
keystone-engine<\/mono> library.
\nTo get the most out ofmona.py<\/mono> on 64-bit targets, you will need to install keystone-engine<\/mono> via pip.
\nWhen installed,windbglib<\/mono> will automatically import and use it.
\nIf not, it will fall back to the limited instruction cache and whatever WinDBG provides.
\nEven on 32-bit targets,windbglib<\/mono> will prefer Keystone if it is present before falling back to WinDBG\u2019s native assembler.<\/p>\n That said, it appears the Keystone project is no longer actively maintained. Still, that didn\u2019t stop us from using
pykd<\/mono> either.<\/p>\n If you are aware of viable alternatives \u2014 ideally a lightweight, actively maintained assembler library with solid 32-bit and 64-bit support and easy installation via pip on Python 3.9+ \u2014 feel free to reach out.<\/mono><\/p>\n
Acknowledgements<\/h2>\n
Before we dive into the practical side, I want to take a moment to give credit where it\u2019s due.<\/p>\n
A huge thank you to @apl3b<\/a> for his dedication, persistence, and high-quality work.<\/p>\n
He rewrote significant parts of the core routines, improved performance across multiple areas, and introduced several new features and commands.<\/p>\n
This release would not be what it is without his contribution.<\/p>\n
I would also like to thank angelo5d0<\/a> for his help testing the various features and commands in the updated mona\/windbglib codebase.<\/p>\n
Prerequisites<\/h2>\n
Before installing mona v3, it\u2019s worth making sure your environment is clean and ready.<\/p>\n
Cleaning up<\/h3>\n
If you have older versions of
mona<\/mono> lying around, now is a good time to remove them.<\/p>\n - \n
- Delete existing
mona.py<\/mono> and windbglib.py<\/mono> copies from your debugger directories<\/li>\n - Remove the
pykd.pyd<\/mono> file from your WinDBG Program folder as well<\/li>\n - Remove any Python installations that you're not using or plan on using<\/li>\n<\/ul>\n
Starting clean helps avoid subtle issues later on.<\/p>\n
Installing dependencies<\/h3>\n
Python 3.9 + PyKD + bootstrapper + libraries<\/h4>\n
The mona3 github repo<\/a> contains the full setup instructions. <\/p>\n
The main prerequisites are:<\/p>\n
- \n
- Python3.9.13 (32bit and 64bit) - that's the most recent Python3 version that ships the PyKD Python library version via pip<\/li>\n
- The corresponding PyKD Python library for both Python architectures<\/li>\n
- PyKD-ext WinDBG Extension, used as bootstrapper.<\/li>\n
- The keystone-engine Python library for both Python architectures<\/li>\n<\/ul>\n
You can have other Python 3 versions installed on the system, but please note that mona won't run in a Python version that doesn't have the pykd library. <\/p>\n
The CorelanTraining github repository<\/a> contains a
CorelanPyKDInstall.ps1<\/mono> powershell script that will install all of the aforementioned components. I recommend using the script and carefully checking the output for errors.
\nThe script has been tested on a handful of virtual machines, Windows 10 and Windows 11. Make sure your machines are up-to-date and everything should run smoothly.<\/p>\nOf course, you can also install all required components by hand.
\nIn that case, I'd like to refer you to the corresponding procedure as documented in this blogpost on WinDBG Automation and Scripting<\/a>. (Check out the section on PyKD.)<\/p>\nNote: That procedure does not cover how to install keystone-engine. That means you'll have to add the following 2 steps to the procedure:<\/p>\n
py -3.9-32 -m pip install keystone-engine<\/cmd><\/pre>\n and<\/p>\n
py -3.9-64 -m pip install keystone-engine<\/cmd><\/pre>\n Feeling adventurous?<\/h4>\n
A few days after publishing my blog post on WinDBG automation<\/a>, I received a message on X from @gerhart_x<\/a>.
\nHe explaineded that he managed to compile pykd against Python 3.14. You can find the release here<\/a>.
\nSo in theory, it means you may be able to install Python 3.14 and load the corresponding pykd.dll<\/p>\nInstalling mona.py<\/h2>\n
Putting mona.py and windbglib.py in the right place<\/h3>\n
With mona3, you still have the option to put both
mona.py<\/mono> and windbglib.py<\/mono> inside your WinDBG program folder.<\/p>\n However, we're proposing a different approach now.<\/p>\n
The mona3 GitHub repository has instructions on performing a centralized installation<\/a>, which involves creating a local folder.<\/p>\n
We're using
C:\\Tools\\mona3<\/mono> in the documentation, but you can obviously put it anywhere you'd like. <\/p>\n Both
mona.py<\/mono> and windbglib.py<\/mono> should reside in the same folder. <\/p>\n Of course, you can also simply perform a
git clone https:\/\/github.com\/corelan\/mona3.git<\/mono> into C:\\Tools<\/mono> if you'd like. That will also create the mona3 folder and put all the files from the repository inside that folder. (which is a bit overkill really, we only need the 2 python files)
\nWhatever you do, just take note of the full path ofmona.py<\/mono> and make sure windbglib.py<\/mono> sits in the same folder. We'll need the full path to run mona<\/mono> in WinDBG.<\/p>\n A centralized setup simplifies maintance. Whenever you decide to run
!mona up<\/mono>, it will update the scripts for all debuggers using it.<\/p>\n In WinDBG and WinDBGX, the
mona.py<\/mono> script is referenced via its full path. We'll have the ability to use WinDBG aliases to provide us with the ability to just run !mona<\/mono> (instead of having to type the full path every time). We'll talk about this in a moment.<\/p>\n In Immunity Debuger, a symbolic link can be used to make
mona.py<\/mono> appear in the PyCommands<\/mono> folder. That way, we can invoke mona<\/mono> just like before, by running !mona<\/mono>.<\/p>\n From an admin command prompt:<\/p>\n
C:\\>
mklink \"c:\\Program Files (x86)\\Immunity Inc\\Immunity Debugger\\PyCommands\\mona.py\" C:\\Tools\\mona3\\mona.py<\/cmd>\nsymbolic link created for c:\\Program Files (x86)\\Immunity Inc\\Immunity Debugger\\PyCommands\\mona.py <<===>> C:\\Tools\\mona3\\mona.py<\/pre>\n mona.ini<\/h3>\n
Mona uses a
mona.ini<\/mono> file to store certain configurations.
\nIf you already had a mona.ini file present on your system and discovered by mona3, it will be moved over into the folder that containsmona.py<\/mono>.
\nIn other words, everything will be centralized in one place.<\/p>\nRunning mona.py<\/h2>\n
Once installed, running mona should feel familiar.<\/p>\n
In WinDBG \/ WinDBGX, load the
pykd<\/mono> bootstrapper:<\/p>\n !load pykd<\/cmd><\/pre>\n (unlike what we did with previous versions of mona, we're not<\/strong> loading
pykd.pyd<\/mono>! We're loading pykd.dll<\/mono> instead.<\/p>\n Next, execute mona using Python 3.9:<\/p>\n
!py -3.9 C:\\Tools\\mona3\\mona.py<\/cmd><\/pre>\n If multiple Python versions are installed, specifying 3.9 avoids ambiguity. The debugger will automatically use the correct architecture.<\/p>\n
As indicated above, we can make our lives easier by creating the following alias:<\/p>\n
as !mona !py -3.9 C:\\Tools\\mona3\\mona.py<\/cmd><\/pre>\n This now allows us to run<\/p>\n
!mona<\/cmd><\/pre>\n
- Remove the