From 90d3f040d2a997e2569989383fa92f5de7e1118a Mon Sep 17 00:00:00 2001 From: clearbluejar <3752074+clearbluejar@users.noreply.github.com> Date: Mon, 11 Sep 2023 00:18:00 +0000 Subject: [PATCH] update readme --- .devcontainer/post-create.sh | 2 - .vscode/launch.json | 78 ++++++++++++++++++++++++++++++++++-- .vscode/settings.json | 13 ++++-- README.md | 57 +++++++++++++++++--------- 4 files changed, 122 insertions(+), 28 deletions(-) diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh index ccf7487..95c3d13 100755 --- a/.devcontainer/post-create.sh +++ b/.devcontainer/post-create.sh @@ -29,8 +29,6 @@ if [ -z "$(ls -A $TEST_DATA_PATH)" ]; then popd fi - - # Setup Ghidra Dev for Reference # git clone https://github.com/NationalSecurityAgency/ghidra.git ~/ghidra-master # pushd ~/ghidra-master diff --git a/.vscode/launch.json b/.vscode/launch.json index c704278..ca3d254 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -29,7 +29,7 @@ "name": "Python: tcpip", "type": "python", "request": "launch", - "program": "${file}", + "module": "ghidriff", "console": "integratedTerminal", "justMyCode": true, // Don't edit env directly, they read from settings.json @@ -136,7 +136,7 @@ ] }, { - "name": "localspl ", + "name": "localspl", "type": "python", "request": "launch", "module": "ghidriff", @@ -200,6 +200,28 @@ "--no-symbols" ] }, + { + "name": "same path, name ls ", + "type": "python", + "request": "launch", + "module": "ghidriff", + "console": "integratedTerminal", + "justMyCode": true, + // Don't edit env directly, they read from settings.json + // Add/delete new vars as needed + "env": { + "GHIDRA_INSTALL_DIR": "${config:GHIDRA_INSTALL_DIR}", + "GHIDRA_PROJECTS_PATH": "${config:GHIDRA_PROJECTS_PATH}", + "GHIDRA_HEADLESS": "${config:GHIDRA_HEADLESS}", + "PROJECT_NAME": "${config:PROJECT_NAME}", + "GHIDRA_BRIDGE_INSTALL_DIR": "${config:GHIDRA_BRIDGE_INSTALL_DIR}", + }, + "args": [ + "/bin/ls", + "/bin/ls", + "/tmp/ls", + ] + }, { "name": "fxsroute with deletefile extern ", "type": "python", @@ -219,13 +241,61 @@ "args": [ "--log-level", "DEBUG", - "--md-title", - "asdfds", + // "--md-title", + // "asdfds", "bins/fxsroute.dll.x64.10.0.22000.795", "bins/fxsroute.dll.x64.10.0.22000.856", "--sxs" ] }, + { + "name": "libwhatsapp 2.22.16.11-12", + "type": "python", + "request": "launch", + "module": "ghidriff", + "console": "integratedTerminal", + "justMyCode": true, + // Don't edit env directly, they read from settings.json + // Add/delete new vars as needed + "env": { + "GHIDRA_INSTALL_DIR": "${config:GHIDRA_INSTALL_DIR}", + "GHIDRA_PROJECTS_PATH": "${config:GHIDRA_PROJECTS_PATH}", + "GHIDRA_HEADLESS": "${config:GHIDRA_HEADLESS}", + "PROJECT_NAME": "${config:PROJECT_NAME}", + "GHIDRA_BRIDGE_INSTALL_DIR": "${config:GHIDRA_BRIDGE_INSTALL_DIR}", + }, + "args": [ + "--log-level", + "DEBUG", + "android/com.whatsapp.2.22.16.11.libwhatsapp.so", + "android/com.whatsapp.2.22.16.12.libwhatsapp.so", + // "--sxs" + ] + }, + { + "name": "libwhatsapp 2.22.16.2-15.75", + "type": "python", + "request": "launch", + "module": "ghidriff", + "console": "integratedTerminal", + "justMyCode": true, + // Don't edit env directly, they read from settings.json + // Add/delete new vars as needed + "env": { + "GHIDRA_INSTALL_DIR": "${config:GHIDRA_INSTALL_DIR}", + "GHIDRA_PROJECTS_PATH": "${config:GHIDRA_PROJECTS_PATH}", + "GHIDRA_HEADLESS": "${config:GHIDRA_HEADLESS}", + "PROJECT_NAME": "${config:PROJECT_NAME}", + "GHIDRA_BRIDGE_INSTALL_DIR": "${config:GHIDRA_BRIDGE_INSTALL_DIR}", + }, + "args": [ + "--log-level", + "DEBUG", + "android/com.whatsapp.2.22.15.75-arm64-v8a.libwhatsapp.so", + "android/com.whatsapp.2.22.16.2-arm64-v8a.libwhatsapp.so", + // "--sxs" + ] + }, { "name": "windows.storage massive symbols", "type": "python", diff --git a/.vscode/settings.json b/.vscode/settings.json index d0e8c19..c74becc 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,12 +1,12 @@ { // needed to make ghidra stubs work in this project (auto complete for vscode) "python.defaultInterpreterPath": "${workspaceFolder}.env/bin/python", - "python.analysis.stubPath": "${workspaceFolder}/.env/lib/python3.10/site-packages/ghidra-stubs/", + "python.analysis.stubPath": "${workspaceFolder}/.env/lib/python3.11/site-packages/ghidra-stubs/", "python.autoComplete.extraPaths": [ - "${workspaceFolder}/.env/lib/python3.10/site-packages/ghidra-stubs/" + "${workspaceFolder}/.env/lib/python3.11/site-packages/ghidra-stubs/" ], "python.analysis.extraPaths": [ - "${workspaceFolder}/.env/lib/python3.10/site-packages/ghidra-stubs/" + "${workspaceFolder}/.env/lib/python3.11/site-packages/ghidra-stubs/" ], // env vars "GHIDRA_INSTALL_DIR": "${env:GHIDRA_INSTALL_DIR}", @@ -14,5 +14,10 @@ "GHIDRA_HEADLESS": "${env:GHIDRA_INSTALL_DIR}${pathSeparator}support${pathSeparator}analyzeHeadless", "PROJECT_NAME": "sample_project", "GHIDRA_BRIDGE_INSTALL_DIR": "${workspaceFolder}${pathSeparator}.ghidra_bridge", - "sarif-viewer.connectToGithubCodeScanning": "off" + "sarif-viewer.connectToGithubCodeScanning": "off", + "liveServer.settings.port": 5501, + "[python]": { + "editor.defaultFormatter": "ms-python.autopep8" + }, + "python.formatting.provider": "none" } \ No newline at end of file diff --git a/README.md b/README.md index f0d70c4..3184af2 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,24 @@ -# Ghidriff - A Binary Diffing Engine Powered by Ghidra +# Ghidriff - Ghidra Binary Diffing Engine + +

- +

+ +## About + `ghidriff` is a [Ghidra](https://ghidra-sre.org/) enabled binary diffing engine. It leverages the power of Ghidra's SRE [FlatProgramAPI](https://ghidra.re/ghidra_docs/api/ghidra/program/flatapi/FlatProgramAPI.html) to find the *added*, *deleted*, and *modified* functions of two arbitrary binaries. It's primary use case is for patch diffing. It is written in Python 3 using `pyhidra` to orchestrate Ghidra and `jpype` as the interface to Ghidra. + + ## High Level ```mermaid @@ -23,26 +34,33 @@ subgraph diffs_output_dir direction LR i(rpcrt4.dll-v1-v2.diff.md) h(rpcrt4.dll-v1-v2.diff.json) + j(rpcrt4.dll-v1-v2.diff.side-by-side.html) end ``` ## Features +- Command Line - Highlights important changes in the TOC - Fast - Can diff the full Windows kernel in less than a minute. - Beautiful Markdown Output - - [Visual Diff] Results - - Easily hosted in a gist + - Visual Diff Graph Results + - Easily hosted in a GitHub or GitLab gist, blog, or anywhere markdown is supported - Callgraphs support (coming soon) - Supports both unified and side by side diff results (unified is default) +- Provides unique Meta Diffs + - Strings + - Called + - Calling + - Binary Metadata The heavy lifting of the binary analysis is done by Ghidra. This library is just the glue that puts it all together. -## About +## Engine > An "engine" is a self-contained, but externally-controllable, piece of code that encapsulates powerful logic designed to perform a specific type of work. -`ghidriff` is provides a core base class, [GhidraDiffEngine](ghidriff/ghidra_diff_engine.py), that can be extended to create your own binary diffing [implementations](#implementations). +`ghidriff` is provides a core base class [GhidraDiffEngine](ghidriff/ghidra_diff_engine.py) that can be extended to create your own binary diffing [implementations](#implementations). The base class implements first 3 steps of the Ghidra [headless workflow](https://github.com/clearbluejar/ghidra-python-vscode-devcontainer-skeleton#steps): >1. **Create Ghidra Project** - Directory and collection of Ghidra project files and data @@ -88,10 +106,9 @@ Each implementation leverags the base class, and implements `find_changes`. #### Usage ```bash -usage: ghidriff [-h] [--engine {SimpleDiff,StructualGraphDiff,VersionTrackingDiff}] [-o OUTPUT_PATH] [--summary SUMMARY] [-p PROJECT_LOCATION] [-n PROJECT_NAME] [-s SYMBOLS_PATH] - [--threaded | --no-threaded] [--force-analysis] [--force-diff] [--log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}] - [--file-log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}] [--log-path LOG_PATH] [--verbose-analysis] [--max-ram-percent MAX_RAM_PERCENT] [--print-flags] - [--jvm-args [JVM_ARGS]] [--sxs] [--max-section-funcs MAX_SECTION_FUNCS] [--md-title MD_TITLE] +usage: ghidriff [-h] [--engine {SimpleDiff,StructualGraphDiff,VersionTrackingDiff}] [-o OUTPUT_PATH] [--summary SUMMARY] [-p PROJECT_LOCATION] [-n PROJECT_NAME] [-s SYMBOLS_PATH] [--threaded | --no-threaded] + [--force-analysis] [--force-diff] [--no-symbols] [--log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}] [--file-log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}] + [--log-path LOG_PATH] [--va] [--max-ram-percent MAX_RAM_PERCENT] [--print-flags] [--jvm-args [JVM_ARGS]] [--sxs] [--max-section-funcs MAX_SECTION_FUNCS] [--md-title MD_TITLE] old new [new ...] ghidriff - A Command Line Ghidra Binary Diffing Engine @@ -105,7 +122,7 @@ options: --engine {SimpleDiff,StructualGraphDiff,VersionTrackingDiff} The diff implementation to use. (default: VersionTrackingDiff) -o OUTPUT_PATH, --output-path OUTPUT_PATH - Output path for resulting diffs (default: .ghidriffs) + Output path for resulting diffs (default: ghidriffs) --summary SUMMARY Add a summary diff if more than two bins are provided (default: False) Ghidra Project Options: @@ -121,12 +138,14 @@ Engine Options: Use threading during import, analysis, and diffing. Recommended (default: True) --force-analysis Force a new binary analysis each run (slow) (default: False) --force-diff Force binary diff (ignore arch/symbols mismatch) (default: False) + --no-symbols Turn off symbols for analysis (default: False) --log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET} Set console log level (default: INFO) --file-log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET} Set log file level (default: INFO) --log-path LOG_PATH Set ghidriff log path. (default: ghidriff.log) - --verbose-analysis Verbose logging for Ghidra analysis of each binary. (noisy) (default: False) + --va, --verbose-analysis + Verbose logging for analysis step. (default: False) JVM Options: --max-ram-percent MAX_RAM_PERCENT @@ -584,11 +603,13 @@ ghidriff afd.sys.x64.10.0.22621.1028 afd.sys.x64.10.0.22621.1415 ### Design Goals -- Fast +- Fast - Simple -- Find added functions -- Find deleted functions -- Find modified functions -- Generate JSON capturing Diff Results -- Generate Markdown Diff +- Accurate +- Find all added, deleted, and modified functions +- Easy sharing of results + - capture diff results in JSON + - diff reports generated in markdown or html +- Enable Social Diffing +- Provide building block for automation