update readme

clearbluejar · Sep 11, 2023 · 90d3f04 · 90d3f04
1 parent f7d337d
commit 90d3f04
Show file tree

Hide file tree

Showing 4 changed files with 122 additions and 28 deletions.
diff --git 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
@@ -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
@@ -1,18 +1,23 @@
 {
     // 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}",
     "GHIDRA_PROJECTS_PATH": "${workspaceFolder}${pathSeparator}.ghidra_projects",
     "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"
 }
diff --git a/README.md b/README.md
@@ -1,13 +1,24 @@
-# Ghidriff - A Binary Diffing Engine Powered by Ghidra
+# Ghidriff - Ghidra Binary Diffing Engine
+
+<!-- <p align="center">    
+<img align="center" alt="GitHub Workflow Status (with event)" src="https://img.shields.io/github/actions/workflow/status/clearbluejar/ghidriff/pytest-devcontainer.yml?label=pytest&style=for-the-badge">
+<img align="center" alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/ghidriff?color=yellow&label=PyPI%20downloads&style=for-the-badge">
+<img align="center" src="https://img.shields.io/github/stars/clearbluejar/ghidriff?style=for-the-badge">
+</p> -->
 
 <p align='center'>
-<img  src="https://user-images.githubusercontent.com/3752074/229976340-96394970-152f-4d88-9fe4-a46589b31c50.png" height="600">
+<img src="https://user-images.githubusercontent.com/3752074/229976340-96394970-152f-4d88-9fe4-a46589b31c50.png" height="300">
 </p>
 
+
+## 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
-Original file line number
+Diff line change
@@ Expand Up / @@ -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
@@ Expand Down @@