Skip to content

Coalfire-Research/ERC.Xdbg

Repository files navigation

Image

ERC.Xdbg

License GitHub tag (latest by date) GitHub issues

An X64dbg plugin built around the ERC library designed to assist in the exploit development process.

Installation

Installing the plugin is reasonably straight forward. Simply download the appropriate zip package for your architecture from the releases page of this repository and save then unzip it in the plugins directory of X64dbg. If X64dbg does not currently have a plugins directory then run it once to create the initial directory structure.

If you wish to build the plugin from source simply clone the Git repository, open the solution in Visual Studio and build the project targeted for your architecture of choice. Then copy the binaries into the plugins directory of your X64dbg installation.

It should be noted that if you are running Windows 7 you will need to ensure .Net Framework 4.7.2 is installed on your system or X64dbg will crash immediately on startup.

Documentation

This library contains the fundamental specifications, documentation, and architecture that underpin ERC.Xdbg. If you're looking to understand the system better, or want to know how to integrate the various components, there is a lot of valuable information contained here.

📄 Documentation and Specifications

API

ERC.Net is the API used to develop ERC.Xdbg, all of the functionality in this plugin stems from the API. ERC.Net is a collection of tools designed to assist in debugging Windows application crashes.

📁 Source - https://github.com/Andy53/ERC.net
📦 32 bit Package - ERC.Net-x86.SDK
📦 64 bit Package - ERC.Net-x64.SDK

Articles

A list of articles covering common usage scenarios using ERC.Xdbg.

📄 The Basics of Exploit Development 1: Win32 Buffer Overflows
📄 The Basics of Exploit Development 2: SEH Overflows
📄 The Basics of Exploit Development 3: Egg Hunters
📄 The Basics of Exploit Development 4: Unicode Overflows
📄 The Basics of Exploit Development 5: x86-64 Buffer Overflows

Globals

Global variables are variables which are set and stored for one session. They are reset to the defaults each time X64dbg is restarted.

-ASLR
Used to exclude pointers from modules implementing ASLR in search output. Can be reset by supplying false as a parameter.
    Example: ERC --help -ASLR Remove pointers from ASLR enabled modules from all search results.
    Example: ERC --help -ASLR false Include pointers from ASLR enabled modules in all search results.

-SafeSEH
Used to exclude pointers from modules implementing SafeSEH in search output. Can be reset by supplying false as a parameter.
    Example: ERC --help -SafeSEH Remove pointers from SafeSEH enabled modules from all search results.
    Example: ERC --help -SafeSEH false Include pointers from SafeSEH enabled modules in all search results.

-Rebase
Used to exclude pointers from modules implementing Rebase in search output. Can be reset by supplying false as a parameter.
    Example: ERC --help -Rebase Remove pointers from Rebase enabled modules from all search results.
    Example: ERC --help -Rebase false Include pointers from Rebase enabled modules in all search results.

-NXCompat
Used to exclude pointers from modules implementing NXCompat in search output. Can be reset by supplying false as a parameter.
    Example: ERC --help -NXCompat Remove pointers from NXCompat enabled modules from all search results.
    Example: ERC --help -NXCompat false Include pointers from NXCompat enabled modules in all search results.

-OSdll
Used to exclude pointers from modules that are OSdll's in search output. Can be reset by supplying false as a parameter.
    Example: ERC --help -OSdll Remove pointers from OSdll's from all search results.
    Example: ERC --help -OSdll false Include pointers from OSdll's in all search results.

-Bytes
Used to exploit pointers containing specific bytes from all search results and from being added to bytearrays generated by the plugin. Can be disabled by passing switch with no arguments. Bytes must be passed without spaces.
    Example: ERC --help -Bytes 0x0A0x0D Remove pointers containing bytes 0A or 0D from all search results.
    Example: ERC --help -Bytes 740D Remove pointers containing bytes 74 or 0D from all search results.
    Example: ERC --help -Bytes Remove any previous byte restrictions from all further search results.

-Protection Used to specify the protection value of all pointers returned in search results. Generic values of read, write and exec are used to specify which the returned pointers should have and can be used in combination. Options must be separated with commas and no spaces.
    Example: ERC --help -Protection exec Remove pointers that do not have exec permission from all search results.
    Example: ERC --help -Protection read,exec Remove pointers that do not have read and exec permission from all search results.
    Example: ERC --help -Protection all Remove any previous protection restrictions from all further search results.

-Extended
Used to specify that the extended character set should be used when using FindNRP and Pattern create and offset functionality. Can be reset by supplying false as a parameter.
    Example: ERC --help -Extended Replaces the standard character set with the extended character set.
    Example: ERC --help -Extended false Resets to the standard characters set.

-ASCII Sets the character encoding as ASCII. All search functions will seach for text in ASCII.
    Example: ERC --help -ASCII Changes the default characters encoding to ASCII.

-Unicode Sets the character encoding as Unicode. All search functions will seach for text in Unicode.
    Example: ERC --help -Unicode Changes the default characters encoding to Unicode.

-UTF7 Sets the character encoding as UTF-7. All search functions will seach for text in UTF-7.
    Example: ERC --help -UTF7 Changes the default characters encoding to UTF-7.

-UTF8 Sets the character encoding as UTF-8. All search functions will seach for text in UTF-8.
    Example: ERC --help -UTF8 Changes the default characters encoding to UTF-8.

-UTF32 Sets the character encoding as UTF-32. All search functions will seach for text in UTF-32.
    Example: ERC --help -UTF32 Changes the default characters encoding to UTF-32.

Usage

Instructions on usage of the plugin can be seen below. This can also be accessed directly through the debugger using ERC --help.

Details on each command can be seen below. Commands are not case sensitive.

--Help
Displays the help message below.
    Example: ERC --help

--Update Downloads the latest release of the plugin from Github and extracts it into the X64Dbg plugin directory for the architecture currently in use. Can be passed a ip:port pair in order to specify a proxy.
    Example 1: ERC --update 127.0.0.1:8080

--config
The config option can be used to set values in the config.xml file. These options persist between sessions. Can be used to set things such as the project author, current working directory and error log file. These options are predominantly used when writing the output of operations to file.
    Example 1: ERC --config SetWorkingDirectory C:\Users\You\Desktop
    Example 2: ERC --config GetErrorFilePath

--Pattern
The pattern option can be used to either create a pattern or to identify the location of a string within a pattern. Appending a c and then a number will create a pattern, appending a o and then a string of 3 or more characters will locate the string within the pattern. The plugin will attempt to automatically identify if the extended character set should be used however you can force it's use by adding "extended" to the command.
    Example 1: ERC --pattern c 1000
    Example 2: ERC --pattern o Aa9
    Example 2: ERC --pattern o Aa9 extended

--ByteArray
The ByteArray option allows the generation of a byte array which is displayed in the log and written to the working directory as both a text file and a binary file containing only the binary values the user wants. By default the array will contain all values from 0x00 to 0xFF and values can be omitted by passing them to the -bytes global variable.
    Example 1: ERC --bytearray
    Example 2: ERC --bytearray -bytes 0xFF0x0A \x0b 0C

--Compare
Generates a table with a byte by byte comparison of an area of memory and the bytes from a file. Takes a memory address from which to start the search and a file path for the binary file.     
    Example 1: ERC --Compare 0x12345678 C:\Users\You\Desktop\YourBinaryFile.bin

--Convert
Takes a string and converts it to a hex representation. The string can be converted as if it was ASCII, Unicode, UTF-7, UTF-8 or UTF-32.     Valid conversion types:
        Ascii to Hex = AtoH
        Unicode to Hex = UtoH
        UTF-7 to Hex = 7toH
        UTF-8 to Hex = 8toH
        UTF-32 to Hex = 32toH
    Example 1: ERC --Convert AtoH HelloWorld returns the ASCII bytes for HelloWorld.
    Example 2: ERC --convert UtoH HelloWorld returns the Unicode bytes for HelloWorld.

--Assemble
The assemble option can be used to convert assembly instructions into the associated opcodes. The plugin will attempt to identify the architecture required based on the attached process however a 0 can be passed to force 32 bit and a 1 can be passed to force 64 bit. Instructions must be separated with a comma (,).
    Example 1: ERC --Assemble jmp esp
    Example 2: ERC --assemble 1 jmp rsp, nop, nop

--Disassemble
The disassemble option can be used to convert opcodes into assembly instructions. The plugin will attempt to identify the architecture required based on the attached process however a 0 can be passed to force 32 bit and a 1 can be passed to force 64 bit.
    Example 1: ERC --disAssemble FF E4
    Example 2: ERC --disassemble 0 FF E4

--SearchMemory
Search memory can take a string or set of bytes to search for within the attached process memory and loaded modules. Optionally an integer can be passed to specify the search type (0 = bytes, 1 = Unicode, 2 = ASCII, 4 = UTF7, 5 = UTF8). Modules can be excluded based on certain characteristics (Is ASLR/SafeSEH/Is the binary rebasable/NXCompat(DEP)/Is the binary an OS dll) The values are optional however if you wish to exclude a later value all previous ones must be included.     Example 1: ERC --SearchMemory FF E4 Search for bytes FF E4 include all dlls.
    Example 2: ERC --SearchMemory FF E4 false false false false true Search for bytes FF E4 excluding only OS dlls.
    Example 3: ERC --SearchMemory 1 HelloWorld Search for the ASCII string HelloWorld.

--SearchModules
Search modules can take a string or set of bytes to search for within the processes loaded modules. Optionally an integer can be passed to specify the search type (0 = bytes, 1 = Unicode, 2 = ASCII, 4 = UTF7, 5 = UTF8). Modules can be excluded based on certain characteristics (Is ASLR/SafeSEH/Is the binary rebasable/NXCompat(DEP)/Is the binary an OS dll) The values are optional however if you wish to exclude a later value all previous ones must be included. Furthermore the search can be limited to certain modules by passing their name or path as arguments.
    Example: ERC --SearchModules FF E4. Search for bytes FF E4 including all dll's
    Example: ERC --SearchModules FF E4 module1.dll module2.dll. Search for bytes FF E4 only in module1.dll and module2.dll

--Dump
Dumps the contents of process memory to the log and a file in the working directory. Takes a hex start address and a hex number for number of bytes to be read.
    Example 1: ERC --Dump 0x63428401 0x30

--ListProcesses
The list processes option takes no parameters and simply lists all visible processes on the machine.
    Example 1: ERC --ListProcesses

--ProcessInfo
Displays information about the attached process, loaded modules and threads. Can be passed a boolean to indicate if the output should be written to disk.
    Example 1: ERC --processInfo
    Example 2: ERC --processinfo false Does not write processinfo output to disk.

--ModuleInfo
Displays info about the modules loaded by the attached process. Can be passed a boolean to indicate if the output should be written to disk.
    Example 1: ERC --moduleInfo
    Example 2: ERC --moduleinfo false Does not write moduleinfo output to disk.

--ThreadInfo
Displays info about threads associated with the attached process. Can be passed a boolean to indicate if the output should be written to disk.
    Example 1: ERC --threadInfo
    Example 2: ERC --threadinfo false Does not write threadinfo output to disk.

--HeapInfo
Displays information about the heap. Takes commands search, stats, ids, and dump. Takes an integer to represent the ID of the heap to utilize. Takes a hex value to specify the address of the heap entry to utilize. If both heap ID and start address are specified heap ID takes precedence, if start address and a byte pattern to search for are specified start address must be provided first. Takes a boolean value of true/false/1/0 to specify if output should be written to disk.
    Example 1: ERC --HeapInfo stats Display statistics about all heaps associated with the process.
    Example 2: ERC --HeapInfo 0x00453563 search FFE4 Search for FFE4 in the Heap entry starting at 0x00453563
    Example 3: ERC --HeapInfo 0x00453563 dump Dump all memory from heap entry starting at 0x00453563
    Example 4: ERC --HeapInfo 0x00453563 dump stats Dump all memory from heap entry starting at 0x00453563 and display stats for the heap entry starting at 0x00453563

--SEH
Displays a list of addresses for pop pop ret instructions. Can be passed a list of module paths to be ignored in the search.
    Example 1: ERC --seh
    Example 2: ERC --SEH C:\Path\To\Module\To\Exclude C:\Path\To\Other\Module\To\Exclude

--EggHunters
Prints a list of egghunters which can be used for various machine types. Can be passed 4 character string to be used as the egghunter search tag. Default tag is ERCD.
    Example 1: ERC --egghunters
    Example 2: ERC --egghunters ABCD Egghunters will be generated with the tag "ABCD"

--FindNRP
Searches process memory for a non repeating pattern specified in the pattern_extended and pattern_standard files. Takes an integer optional to specify the text formatting (1 = Unicode, 2 = ASCII, 3 = UTF8, 4 = UTF7, 5 = UTF32, default = ASCII) and can have the parameter "true" passed to indicate the extended pattern should be used.
    Example 1: ERC --FindNRP
    Example 2: ERC --FindNRP 2 true Generates FindNRP table after searching for the extended NRP in Unicode format.

--Rop
Attempts to build a ROP chain for the current process. Current implementation utilizes VirtualAlloc, VirtualProtect and HeapCreate.
    Example 1: ERC --Rop

--RopGadgets
Generates lists of ROP gadgets from within the current process. Lists are saved to the working directory.
    Example 1: ERC --RopGadgets

--Reset
Returns the plugin to a default status. Resets all client variables and configurations.
    Example 1: ERC --reset

Author

Andy Bowden | Twitter URL