Turdshovel
Description
Turdshovel is an interactive CLI tool that allows users to dump objects from .NET memory dumps without having to fully understand the intricacies of WinDbg. It uses Python.NET to wrap around ClrMD and perform basic operations for dumping objects and sections of memory. The primary goal of Turdshovel is to focus on finding secrets in memory dumps quickly.
It is absolutely not intended to be a full-fledged memory dump analysis tool.
Installation
Turdshovel is written in Python 3.8 and at the moment is expected to only work with Python 3.8. No testing has been performed with other Python versions. This is because Turdshovel has a dependency on Python.NET, which requires specific installations of its files per Python version. This may change in the future with the release of Python.NET 3.0 and Turdshovel will support Python >3.8 as long as Python.NET supports it.
Additionally, Turdshovel is meant to be installed on Windows and has only been tested on Windows. No testing has been performed with Linux. However, Turdshovel uses the .NET Standard 2.0 versions of ClrMD which supports:
- .NET Core (2.0 - 6.0)
- .NET Framework (4.6.1 - 4.8)
- Mono (5.4, 6.4)
The inclusion of Mono may mean that Turdshovel works on Linux, especially since ClrMD does support Linux. However, future plans for Turdshovel may include features that will be limited to Windows due to dependencies. These features will not be supported on other OSes, so a Windows environment is your best bet for usage.
Microsoft offers free Windows 10 development environment VMs here.
Installing with Pipx
As a CLI tool, installation is highly recommended using Pipx to avoid any dependency confusions. Honestly, you should use Pipx for most Python CLI tools! Additionally, since Turdshovel only works with Python 3.8, this helps ensure that your virtual environment is set to use Python 3.8 at all times.
If your Pipx install was done with Python 3.8: pipx install turdshovel
If your Pipx install was done with different version: pipx install --python
Usage
Turdshovel uses Nubia as its framework for an interactive CLI.
| Command | Arguments | Description |
|---|---|---|
| load | Loads a dump for a session | |
| dump heap | filter - Filter objects by strings | Lists objects on the heap |
| dump obj | address - Address of object to dump save - Save ouput to disk |
Dumps object on heap by address |
| dump mem | address - Address of memory to read length - Length of bytes to read |
Dumps the memory in bytes at location |
| dump stat | filter - Filter objects by strings sort - Sort object by count or object reverse - Reverse sorting output |
Dumps the count of each object on the heap |
| dump type | types - Objects types | Dumps the objects on the heap by type |
| help | Show help | |
| exit | Exit |
Commands
load
The load command takes the path to the file dump as an argument.
dump heap
Similar to the dump heap command via SOS, this command will list the objects on the heap as well as their type. However, the output differs in that Turdshovel does not show objects which are listed as "Free" on the heap. You can optionally pass a list of strings as the filter.
dump obj
Similar to the dump obj command via SOS, this command will dump all of the non-static fields of the object on the heap in JSON representation. You can also pass save=True to save the resulting JSON to disk.
IMPORTANT: When dumping a complex object, you may noticed fields . This indicates that the field would have caused a recursion error to occur so Turdshovel did not parse the field. This usually occurs with objects that reference themselves.
dump mem
Prints the bytes at the location specified for the amount of bytes specified. This is useful when objects point to locations in memory that are not objects, such as encrypted data, or just seeing what is around any given memory address. The example shows a simple string which you could find with the strings command but there are better use cases, specifically with pointers!
dump stat
Prints the count of each type of object. You can optionally filter the type using filter= and can sort the output by count or object using sort=.
dump type
Dumps all objects of specific types. THIS CAN BE DANGEROUS so if you suspect a type might have a large amount of output, use "save=True" to write everything to disk.
Built With
- Python-Nubia - CLI Framework
- Python.NET - Python/C# Interop
- ClrMD - .NET Diagnostics Library
- Rich - Amazing text, highlighting, and formatting
Special Thanks
- Steve Dower - Helped fixed the recursion issue!
2 Dec 28, 2021
282 Dec 27, 2022
2.4k Jan 02, 2023
144 Jan 05, 2023
20 Dec 21, 2022
1 Jul 22, 2022
439 Jan 02, 2023
1.2k Jan 06, 2023
9 Mar 01, 2022
7.4k Jan 07, 2023
1 Mar 04, 2022
1 Jan 23, 2022
30 Nov 08, 2022
89 Dec 17, 2022
20 Dec 22, 2022
5 May 08, 2022
1 Dec 24, 2021
6 Aug 01, 2022
44 Dec 16, 2022
1 Feb 01, 2022