Quickstart Guide

ForensicDbg has been built to help you view, understand, and interpret why your software is crashing at a foundational level. This usually involves loading a dmp file produced by an exception or crash and using ForensicDbg to investigate what happened and how to fix it.

Opening Dmp Files

If you already are running ForensicDbg you can either open the dmp using the “File > Open Crash Dump…” menu or just click the bug icon on the top bar.

You can also just launch any dmp file found in the file system directly.

Either way, your chosen file will be loaded (which may take up to a minute or two for large dmp files). ForensicDbg takes that time to interpret relevant information and link everything together for simple navigation.

Attaching to Processes

Another way to view what is going on under the hood of your software is to attach to its running process directly. ForensicDbg will take a snapshot of the current state of any process you attach to so you can move through it just as clearly.

Make sure the software you wish to see is running, then select the “File > Attach to Process…” menu option. A new window will pop up showing all of the current running processes. Select the one you want and attach to it. From there ForensicDbg will act very similarly to when you load a dmp file.

Understanding Loaded Info

After loading a dmp file (or attaching to a process), ForensicDbg should look a bit like this.

There is a lot going on here, so let’s move through it in a standard initial navigation order often useful for understanding the loaded data.

The top two panels on the right show you all the threads in the process space and the callstack in the currently selected thread. You can click to move around the process space in either panel and if there is an exception call in the loaded data, it will have the thread and function it occurred in highlighted.

The top two panels on the top left show you the source code (if you have access to it) and the disassembly for the selected function. Clicking around in either panel will jump the other to match and lets you see exactly what is happening in your code. Just as before, the disassembly panel will highlight the exact line that caused an exception if there is one.

Finally we get down to the bottom two panels which provide you a direct look at the selected stack or memory on the left, and a whole host of useful information on the right including the selected registers, objects, types, and references.

Note - If your loaded data is missing symbols or source code you have on your machine, there are two environment variables you can set to make sure they are found and loaded.

Panel Descriptions

Let’s quickly cover every tab in every panel and what they do.

Source - Shows the source code related to the currently selected disassembly and allows you to navigate the process space when moving through the source code. Useful for understanding how the disassembly and source code relate to each other.
Threads - Shows all of the threads present in the process space and lets you navigate between them. Will highlight exceptions for you automatically.
Modules - Lists all of the modules referenced in the process space and if they have had their symbols successfully loaded. Double click on any of them to see the associated regions and symbols for the selected module.
Regions - Shows all of the regions of memory in the process space, what read/write/execute permission each has, as well as a description of what the region contains. The color of each region corresponds to what type of region it is.
Disassembly - Displays executable regions of the process and as you move around in the Disassembly panel, the Source panel will track your location. This is your primary window for moving through the process space and figuring out what happened and why. Will highlight exceptions for you automatically.
Callstack - Shows the functions that were called on the selected thread and as you navigate between them, the Disassembly and Source panels will show the selected function. Moving through frames of the callstack gives you an idea of what is happening. Will highlight exceptions for you automatically.
Symbols - Shows all of the symbols contained in the selected module.
Stack - Shows the stack for the selected thread, broken up by frame.
Memory - Shows a memory dump for the selected memory region, broken up by symbols. This will be your primary area for identifying issues caused by memory stomps or other badly managed memory issues.
Console - Shows all logs created while loading and working in the process space. Also attempts to evaluate any C++ expressions you type in.
Registers - Shows what is loaded into the registers.
Locals - Shows local variables for the frame selected in the Callstack window.
Object - Shows the structure of objects selected in the Object window.
Type - Shows the type of objects selected in the Object window.
Information - Currently a placeholder and will be added in at a later date.
References - Shows all references contained in the selected address range.
History - Shows a history of selected addresses when working in the editor.