DebugNET

About The Project

This project was implemented to lessen the dependency on programs like Cheat Engine and such by integrating their core functionalities into a .NET library.
The library includes many features, like:

• Kernel32 Decorator
• Events (Attached, Detached, Breakpoint.OnHit, ...)
• Breakpoints (With optional conditions)
• Allocating and freeing Memory
• Resolving address strings (e.g. "Prog.exe+0x14-C")
• Writing and reading to addresses (reading/writing of structs are supported!)
• Creating and running threads
• Injecting .DLL files into a remote thread
• Non-blocking I/O thanks to C#'s async/await-Pattern

You may even use it as an interface for the kernel32.dll!

Check out the examples here.

(back to top)

Built with

DebugNET relies heavily on P/Invokes to the kernel32.dll of Windows.
There are no further dependencies.

(back to top)

Getting Started (Windows)

Follow these simple steps to get a local copy running.

Prerequisites

• .NET Framework 4.6.1 or higher (not .NET Core!)
• Development environment of your choice (Visual Studio, Sublime-Text, etc.)

(back to top)

Installation

To use this repository in your own projects download the compiled .dll file and add to your project it as a library.
Check the releases page for a download.

(back to top)

Building

Alternatively, you can build the project yourself

1. Clone the repository

   git clone https://github.com/Jay184/DebugNET.git
   # Or using SSH (depending on your setup)
   git clone git@github.com:Jay184/DebugNET.git
   

2. Add as an existing Project to your own project to use its source or build it using your development environment (Visual Studio for example)

(back to top)

Usage

For more examples, please refer to the Example project

Basics

Import the namespace

using DebugNET;
using Debugger = DebugNET.Debugger; // (optional, avoids conflict with .NET's Debugger class in System.Diagnostics)

Grab a desired instance of the System.Diagnostics.Process class

Process[] processes = Process.GetProcessesByName(processName);
Process process = processes.Length > 0 ? processes[0] : null;

Instantiate a Debugger object and read some memory addresses
Note: It's generally best-practice to use the using-Statement to take care of the dispoing process!

using (Debugger debugger = new Debugger(process)) {
   // Use process.Modules to find your desired module in your process!
   
   // Retrieve address by code.
   IntPtr codeAddress = debugger.Seek("process.exe", 0x89, 0x45, 0xD0);
   
   // Retrieve address by module-offset pair. (Note the escaped quotation marks!)
   IntPtr address = debugger.GetAddress("\"process.exe\"+13648");
   
   // Read a single byte at a specific address
   byte read = debugger.ReadByte(address);
   
   // Let's write back what we wrote but add one to it
   debugger.WriteByte(address, (byte)(read + 1));
}

(back to top)

Roadmap

• kernel32.dll P/Invoke decorator
• Read/Write memory of remote processes
• Breakpoints, reading CPU registers
• Async using async/await
• Seeking a byte-sequence
• Allocating memory and injecting code
• Injecting .DLL files to remote processes
• Document using DocFX
• Exception handling
• More examples

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a merge request. You can also simply open an issue with the label "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Run unit tests if possible
5. Push to the branch (git push origin feature/AmazingFeature)
6. Open a pull request

Codestyle

• Four space indentation
• One class per file
• Class names are written in PascalCase
• Function names are written in PascalCase
• Class variables (Properties) are written in PascalCase regardless of visibility
• Local variable names are writtein in camelCase (including function parameter names)
• Use XML to document your functions and classes before you start coding them!
• Do not include more namespaces than necessary
• Design your functions to be functional (lessen class coupling and prefer parameters over global properties)

(back to top)

License

Distributed under the Unlicense license. See LICENSE for more information.

(back to top)

Contact

Jay - Jay#4711

Project Link: https://github.com/Jay184/DebugNET

(back to top)

Acknowledgments

• PInvoke.net
• Choose an Open Source License
• GitHub Emoji Cheat Sheet
• Img Shields

(back to top)