Initial release

Author: sam-f0

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+on:
+    push:
+      tags:
+       - '*'
+jobs:
+  create_release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    outputs:
+        upload_url: ${{ steps.create_release.outputs.upload_url }}  
+    permissions:
+        contents: write # To checkout repo and to create release  
+    steps:
+      - name: Create GitHub Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+            tag_name: ${{ github.ref }}
+            release_name: GAIT release ${{ github.ref }}
+            draft: false
+            prerelease: false
+  build-matrix:
+    needs: create_release # we need to know the upload URL
+    runs-on: ubuntu-latest
+    permissions:
+        contents: write # To checkout repo and to create release  
+    strategy:
+      matrix:
+        ghidra_version: ['11.1.2', '11.1.1', '11.1', '11.0.3', '11.0.2', '11.0.1', '11.0']
+    steps:
+      - name: checkout repo
+        uses: actions/checkout@v3
+      - name: Extract tag name
+        id: tag
+        run: echo ::set-output name=TAG_NAME::$(echo $GITHUB_REF | cut -d / -f 3)
+      - name: build
+        env: 
+          GHIDRA_VERSION: ${{ matrix.ghidra_version }}
+        run: docker compose up --exit-code-from build.service
+      - name: Extract filename
+        id: filename
+        run: echo ::set-output name=ASSET_NAME::$(ls -AU plugin/AngrIntegration/dist | head -1)
+      - name: Upload Release Asset
+        id: upload-release-asset 
+        uses: actions/upload-release-asset@v1
+        env:
+            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+            upload_url: ${{ needs.create_release.outputs.upload_url }} # This pulls from the CREATE RELEASE step above, referencing it's ID to get its outputs object, which include a `upload_url`. See this blog post for more info: https://jasonet.co/posts/new-features-of-github-actions/#passing-data-to-future-steps 
+            asset_path: plugin/AngrIntegration/dist/${{ steps.filename.outputs.ASSET_NAME }}
+            asset_name: ghidra-angr-integration-tool-${{ steps.tag.outputs.TAG_NAME }}-ghidra_${{ matrix.ghidra_version }}.zip
+            asset_content_type: application/zip

.gitignore

@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+angr/

.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": false 
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,26 @@
+{
+    "python.analysis.autoImportCompletions": false,
+    "python.analysis.typeCheckingMode": "off", // disable pylance type hinting, when mypy does a better job
+    "python.analysis.extraPaths": [
+        "./plugin/AngrIntegration/data/architectures"
+    ],
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "always"
+        },
+    },
+    "isort.args": [
+        "--profile",
+        "black"
+    ],
+    "mypy-type-checker.args": [
+        "--disallow-untyped-calls",
+        "--disallow-untyped-defs",
+        "--strict",
+        "--untyped-calls-exclude=angr",
+    ],
+    "black-formatter.args": ["--line-length=120"],
+    "autoDocstring.docstringFormat": "sphinx-notypes"
+}

DESIGN.md

@@ -0,0 +1,76 @@
+# Project architecture
+
+The main component of this tool is the Ghidra plugin, `AngrIntegrationPlugin` (in `plugin/AngrIntegration`). This creates a
+Ghidra UI Component (in `AngrIntegrationProvider`), and creates an `AngrInterface` which is responsible for communicating
+with angr. It also aquires the `ConsoleService` for printing to the console and wraps it in it's own methods for
+outputting data.
+
+## `AngrInterface`
+
+Responsible for running scripts for the plugin. Stores the paths to python and keeps track of currently running worker
+threads.
+
+When the `AngrIntegrationProvider` tells the interface to run angr, a `Process` is created, which corresponds to an
+actually running instance of Python (in the venv). This is passed to a Swing `SwingWorker`, which polls the
+stdin/out/err every 20ms for new output. If there is new output, it will send it to either the REPL or the console,
+depending on if the REPL is active or not.
+
+The `AngrInterface` is also responsible for interpreteting several special commands the python process can send, which are
+all prefixed by a string that's unlikely to be hit normally (currently "`!<*`"). These can do things like send status
+updates to the UI, or cause the `AngrInterface` to create the REPL window and start sending data to that instead.
+
+If the REPL is active, it will call `checkSendInput` on the `AngrREPL` object every 20ms, which forwards updates from
+the user down the pipes to the angr process.
+
+## `AngrIntegrationProvider`
+
+High level component for the UI. Constructs each tab of the UI, registers event handlers, and does any other UI setup
+that needs doing. The tables, components that are shown or hidden by buttons, and Hook panels are delegated to other
+classes due to their complexity.
+
+Shows status reports from the `AngrInterface` next to the run button. Receives events from the `AngrIntegrationPlugin`
+when the program is changed, to allow the various components to adjust.
+
+When the run button is clicked, the `Provider` gathers all the fields from the UI into a `AngrConfiguration` object,
+which is serialized and written to a file in `/tmp`. Then the `AngrInterface` invokes the `angr_main` script, which
+reads that file and uses it to run angr!
+
+## `GoalView` and `StateView`
+
+These subclass Ghidra's `OptionalComponent` which is an abstract class that defines a component that can be shown, and also respond to events when the program is changed or readied. These are used to define the components in the UI when the corresponding button is selected for exploration goal or entry point respectively. When it's time to construct the `AngrConfiguration`, the `getConfig` function is called on them which should return the `ExplorationGoal` or `EntryPoint` that should be written to the `AngrConfiguration`.
+
+Each `_GoalView` corresponds to a `_Goal` that represents that goal in an `AngrConfiguration`, and respectively for `_StateView`.
+
+## `Table` and `TableModel`
+
+These are just specialisations of `JTable`s and `TableModel`s that configure the table to fit our needs.
+
+## `HookView`
+
+This component draws the edit panel for an individual hook. Unlike most of the UI, changes made in the UI are
+immediately written to an underlying array of `Hook`s, which means that only one `HookView` needs to exist.
+
+## `AngrREPL`
+
+Wraps a `InterpreterComponentProvider` in a small interface for reading and writing to it.
+
+## Python
+
+### `get_angr_version`
+
+Invoked by the plugin when loading or the venv changes, to check that the correct version of angr is loaded.
+
+### `angr_main`
+
+The main entry point to angr in the plugin. This reads a passed in data file, which should be a JSON object created from
+the `AngrInterface`, which defines everything that's been written into the UI.
+
+This does some setup, which includes using the `symbolic_field` module to construct symbolic variables and constraints
+from provided python strings, and inserting the progress reporter `ExplorationTechinique` from `progress_reporter`,
+which periodically writes progress reports which are picked up by the `AngrInterface` connected to stdout. It will also
+load the architecture definition from the provided config, which contains many hooks that can trigger across the whole
+process.
+
+Then it runs the main angr process, which should probably take a while! When done, it will print some cursory
+information about the recovered states and, if configured to do so, signal the interface to move to a REPL before
+starting a repl interpreter itself.

Dockerfile

@@ -0,0 +1,8 @@
+FROM gradle:jdk19
+
+RUN apt-get update && apt-get install python3-pip -y && rm -rf /var/lib/apt/lists/*
+RUN bash -c "AIOHTTP_NO_EXTENSIONS=1 pip3 install pygithub"
+
+COPY docker_build.py /docker_build.py
+
+CMD [ "python3", "-u", "/docker_build.py" ]