Ghidrecomp - Command Line Ghidra Decompiler

About

This Python command line tool decompiles all functions of a binary and writes them to a directory in separate C files:

flowchart LR

a(filename ) --> b[ghidrecomp]
a2[(Symbol Server)] --> b

b --> e(Ghidra Project Files)
b --> output

subgraph output

  subgraph decompilations
      direction LR
      i(func1.c)
      h(func2.c)
      f(funcB.c)
  end

  subgraph callgraphs
      direction LR
      j(callgraph1.md)
      k(callgraph2.md)
      l(callgraphN.md)
  end

  subgraph bsim-xml
      direction LR
      n(sig-md5-bin1.xml)
      m(sig-md5-bin2.xml)
      o(sig-md5-binN.xml)
  end

end

Or a single file C and header file with --cppexport:

flowchart LR

a(filename ) --> b[ghidrecomp]
a2[(Symbol Server)] --> b

b --> e(Ghidra Project Files)

b --> singlefile 


subgraph singlefile
  direction LR
  s1(all_funcs.c)
  s2(all_funcs.h)
end

The main purpose for this is to use the decomplilations for research and analysis. The tool relies on Ghidra for decompilation and communicates to Ghidra with jpype via pyghidra.

TOC

• Ghidrecomp - Command Line Ghidra Decompiler
  • About
  • TOC
  • Features
  • Usage
  • Output Files Tree
  • Example Usage with Windows afd.sys:
    • Command line
    • Output
    • Decompilation Output Dir
  • Example usage in Docker container
    • Command (Host)
    • Run in docker on /bin/ls
      • Output
    • Decompilation Output Dir
  • Example Usage with Windows afd.sys Callgraph:
    • Command line
    • Output
    • Sample Calling Callgraph Output AfdRestartDgConnect:
    • Sample MindMap Output for AfdRestartDgConnect
  • Example SAST Scanning
    • Command line with multiple rule files
    • Command line with custom rule directory
    • Command line with comma-separated rules (backward compatible)
    • Output
    • SAST Output Files
  • Example BSim signature generation
    • Command line
    • Output
    • Files generated
  • Installation
    • Optional SAST dependencies
    • Windows
    • Linux / Mac
    • Devcontainer / Docker
      • Option 1 - Devcontainer
      • Option 2 - Docker

Features

all these features are ultimately provided by Ghidra

• Decompile all functions (threaded)
  • to a folder (-o OUTPUT_PATH)
  • to a single c file and header file (--cppexport)
• Auto-downloaded symbols for supported symbol servers (-s SYMBOLS_PATH)
  • https://msdl.microsoft.com/download/symbols/
  • https://chromium-browser-symsrv.commondatastorage.googleapis.com/
  • https://symbols.mozilla.org/
  • https://software.intel.com/sites/downloads/symbols/
  • https://driver-symbols.nvidia.com/
  • https://download.amd.com/dir/bin/
• Specify pdb for binary (--sym-file-path)
• Filter functions to decompile that match regex (--filter)
• Apply custom data types (--gdt)
• SAST scanning (--sast) with Semgrep for static analysis of decompiled code
  • Support for multiple rule files/directories
  • SARIF output for integration with security tools
  • Preprocessing of Ghidra-specific calling conventions

Usage

usage: ghidrecomp [-h] [--cppexport] [--filter FILTERS] [--project-path PROJECT_PATH] [--gdt [GDT]] [-o OUTPUT_PATH] [-v] [--skip-cache]
                  [--sym-file-path SYM_FILE_PATH | -s SYMBOLS_PATH | --skip-symbols] [-t THREAD_COUNT] [--va] [--fa]
                  [--max-ram-percent MAX_RAM_PERCENT] [--print-flags] [--callgraphs] [--callgraph-filter CALLGRAPH_FILTER] [--mdd MAX_DISPLAY_DEPTH]
                  [--max-time-cg-gen MAX_TIME_CG_GEN] [--cg-direction {calling,called,both}] [--bsim] [--bsim-sig-path BSIM_SIG_PATH]
                  [--bsim-template BSIM_TEMPLATE] [--bsim-cat BSIM_CAT] [--sast] [--semgrep-rules SEMGREP_RULES] [--codeql-rules CODEQL_RULES]
                  bin

ghidrecomp - A Command Line Ghidra Decompiler

positional arguments:
  bin                   Path to binary used for analysis

options:
  -h, --help            show this help message and exit
  --cppexport           Use Ghidras CppExporter to decompile to single file (default: False)
  --filter FILTERS      Regex match for function name (default: None)
  --project-path PROJECT_PATH
                        Path to base ghidra projects (default: ghidra_projects)
  --gdt [GDT]           Additional GDT to apply (default: None)
  -o OUTPUT_PATH, --output-path OUTPUT_PATH
                        Location for all decompilations (default: ghidrecomps)
  -v, --version         show program's version number and exit
  --skip-cache          Skip cached and genearate new decomp and callgraphs. (default: False)
  --sym-file-path SYM_FILE_PATH
                        Specify single pdb symbol file for bin (default: None)
  -s SYMBOLS_PATH, --symbols-path SYMBOLS_PATH
                        Path for local symbols directory (default: symbols)
  --skip-symbols        Do not apply symbols (default: False)
  -t THREAD_COUNT, --thread-count THREAD_COUNT
                        Threads to use for processing. Defaults to cpu count (default: 12)
  --va                  Enable verbose analysis (default: False)
  --fa                  Force new analysis (even if already analyzed) (default: False)

JVM Options:
  --max-ram-percent MAX_RAM_PERCENT
                        Set JVM Max Ram % of host RAM (default: 50.0)
  --print-flags         Print JVM flags at start (default: False)

Callgraph Options:
  --callgraphs          Generate callgraph markdown (default: False)
  --callgraph-filter CALLGRAPH_FILTER
                        Only generate callgraphs for functions matching filter (default: .)
  --mdd MAX_DISPLAY_DEPTH, --max-display-depth MAX_DISPLAY_DEPTH
                        Max Depth for graph generation (default: None)
  --max-time-cg-gen MAX_TIME_CG_GEN
                        Max time in seconds to wait for callgraph gen. (default: 5)
  --cg-direction {calling,called,both}
                        Direction for callgraph. (default: calling)

BSim Options:
  --bsim                Generate BSim function feature vector signatures (default: False)
  --bsim-sig-path BSIM_SIG_PATH
                        Path to store BSim xml sigs (default: bsim-xmls)
  --bsim-template BSIM_TEMPLATE
                        BSim database template (default: medium_nosize)