Added high level README

Author: evm-sec

README.md

@@ -0,0 +1,56 @@
+# CodeCut Plugin for Ghidra
+
+Ghidra Plugin for DeepCut / CodeCut GUI
+
+## Theory of Operation
+CodeCut allows a user to assign functions to object files in Ghidra, and then interact with the binary at the object file level.  Functions are assigned to object files by setting the `Namespace` field in the Ghidra database.  DeepCut attempts to establish initial object file boundaries which the user can then adjust using the CodeCut Table window. 
+
+## Plugin Installation
+Follow normal Ghidra extension installation procedures.  Copy the CodeCut and DeepCut extension zip into `$GHIDRA_INSTALL_DIR/Extensions` then in the main Ghidra window selection **File -> Install Extensions** and select the CodeCut and DeepCut boxes.  Ghidra will tell you it needs to restart.  
+
+**NOTE:** After restarting and loading a CodeBrowser window, Ghidra will tell you it has found new plugins and ask if you want to configure them.  Only CodeCut shows up in this window.  This is because DeepCut is a "one-shot" analyzer (it is still installed).
+
+## Configuring Native Python Paths & Python Dependencies
+Both CodeCut and DeepCut rely on native Python (outside of Ghidra) on your system.  CodeCut uses native Python for guessing module names.  DeepCut's model evaluation runs in native Python.  
+
+### Native Python Dependencies
+CodeCut: 
+- nltk
+
+DeepCut: 
+- torch 1.7.1
+- torch-geometric 1.6.3
+- torch-cluster 1.5.8
+- torch-sparse 0.6.8
+- torch-scatter 2.0.5
+- torch-spline-conv 1.2.0
+
+To install dependencies run:
+
+```
+pip3 install nltk
+pip3 install torch==1.7.1+cpu torch-geometric==1.6.3 torch-cluster==1.5.8 torch-spare==0.6.8 torch-scatter==2.0.5 torch-spline-conv==1.2.0
+```
+
+(assuming that pip3 points to the version of Python you plan to use below)
+
+### Configuring CodeCut Python Path
+![](img/codecut-config.png)
+
+Configure the native Python path for CodeCut by choosing **Edit -> Tool Options** and selecting "Python Executable."
+
+### Configuring DeepCut Python Path
+![](img/deepcut-config.png)
+
+Configure the native Python path for DeepCut by choosing **Analysis -> Analyze All Open...** and selecting **Deepcut (Prototype)**.  After changing the path, click the **Apply** button.
+
+## Running DeepCut Analysis
+DeepCut is best run as a one-shot analyzer *after* initial auto-analysis.  Select **Analysis -> One Shot -> Deepcut**.  After DeepCut runs, you can view the results by looking at the **Namespace** field in the **Symbol Table** view.
+
+## Using CodeCut
+![](img/codecut-run.png)
+
+After DeepCut runs, you can interact at an object file level with the **CodeCut Table** view.  Select **Window -> CodeCut Table**  You can have CodeCut guess the module names (based on string references) by choosing **Analysis -> Guess Module Names** in the CodeCut Table window.  You can split/combine object files by right clicking on an object and choosing "Split Namespace Here" / "Combine Namespaces."  You can move functions between object files (changing the boundaries of the object files) by dragging and dropping them.
+
+## Building
+Specific build instructions are provided in the DeepCut and CodeCut subfolders.

codecut-gui/README.md

@@ -1,10 +1,9 @@
-# CodeCut / DeepCut GUI Plugin
 
-Ghidra Plugin for DeepCut / CodeCut GUI
+# Ghidra Plugin for CodeCut GUI
 
 ## Building and Installation
 
-JDK 11 (or newer) and Ghidra 9.1.0 (or newer) are required.
+Requirements are the same as the Ghidra build requirements, currently JDK 17 (or newer) is required for Ghidra 10.2.
 
 Ghidra's standard Gradle build system is used. Set the `GHIDRA_INSTALL_DIR` environment variable before building, or set it as a Gradle property (useful for building in an IDE).
 

deepcut-ghidra/README.md

@@ -1,10 +1,10 @@
 Ghidra Deepcut Analyzer
 =======================
 
-Implementation of the deepcut as a Ghidra one-shot analyzer. 
+Implementation of Deepcut as a Ghidra one-shot analyzer. 
 
 ## Building and Installation
-JDK 11 (or newer) and Ghidra 9.1.0 (or newer) are required.
+Requirements are the same as Ghidra.  Currently JDK 17 (or newer) is required (for Ghidra 10.2).
 
 Ghidra's standard Gradle build system is used. Set the
 `GHIDRA_INSTALL_DIR` environment variable before building, or set it as
@@ -13,7 +13,7 @@ a Gradle property (useful for building in an IDE):
 ### Environment variable
 ```bash
 $ export GHIDRA_INSTALL_DIR="/path/to/ghidra"
-$ ./gradlew
+$ ./gradle
 ```
 
 ### Gradle property
@@ -30,11 +30,12 @@ used by your Ghidra installation. If you have multiple Java runtime
 environments installed, select the correct JRE by setting the
 `JAVA_HOME` environment variable before building.
 
-### Python 3 
-The deepcut graph based machine learning model needs Python 3 to
-execute. The analyzer calls and external python process to execute the
-model on a graph representation of the binary. There are no GPU
-requirements since the model converge quickly even running in CPU mode.
+### Native Python 3 
+The Deepcut graph based machine learning model needs Python 3 to
+execute (outside of Ghidra). The analyzer calls an external Python 
+process to execute the model on a graph representation of the binary. 
+There are no GPU requirements since the model converge quickly even 
+running in CPU mode.
 
 #### Python 3 Path
 By default the analyzer use the command `/usr/local/bin/python3` to
@@ -73,3 +74,10 @@ Namespace field.
 
 If there are any errors please make sure you are using the proper path
 to Python 3 and the requirement dependencies installed.
+
+## Troubleshooting
+You can verify that dependencies are correct by navigating to:
+`~/.ghidra/.ghidra_${VERSION}/Extensions/deepcut-ghidra/data`
+and running `./python3 deepcut.py`.  Python will throw errors if it
+can't find dependencies.  If the process runs and sits there waiting
+for input, then the dependencies should be correct.