Skip to content

Commit

Permalink
Docusaurus Docs (#66)
Browse files Browse the repository at this point in the history
* initial docusaurus init
* adding docusaurus docs
* sites updates with diff samples
* add deploy to workflow
  • Loading branch information
clearbluejar authored Dec 18, 2023
1 parent b0c20e0 commit 6e34506
Show file tree
Hide file tree
Showing 55 changed files with 29,385 additions and 17 deletions.
50 changes: 50 additions & 0 deletions .github/workflows/docs-build-test-and-deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
name: Test Deploy Docs

on:
push:
paths:
- 'www/**'
- '.github/workflows/docs-build-test-and-deploy.yml'
workflow_dispatch:

# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:

test-and-deploy:
name: Test and deploy
runs-on: ubuntu-latest
defaults:
run:
working-directory: www
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 18
cache: yarn
cache-dependency-path: './www/package-lock.json'

- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Test build website
run: yarn build


- name: Deploy to GitHub Pages
if: github.ref == 'refs/heads/main'
# Popular action to deploy to GitHub Pages:
# Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
# Build output to publish to the `gh-pages` branch:
publish_dir: ./www/build
# The following lines assign commit authorship to the official
# GH-Actions bot for deploys to `gh-pages` branch:
# https://github.com/actions/checkout/issues/13#issuecomment-724415212
# The GH actions bot is used by default if you didn't specify the two fields.
# You can swap them out with your own user credentials.
# user_name: github-actions[bot]
# user_email: 41898282+github-actions[bot]@users.noreply.github.com
25 changes: 24 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -137,4 +137,27 @@ ghidriffs/
# pytest data (pulled from https://github.com/clearbluejar/ghidriff-test-data)
tests/data

.DS_Store
.DS_Store


# docusaurus .gitignore
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
39 changes: 23 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
<img align="center" src="https://img.shields.io/github/stars/clearbluejar/ghidriff?style=for-the-badge">

## Ghidriff - Ghidra Binary Diffing Engine

`ghidriff` provides a command-line binary diffing capability with a fresh take on diffing workflow and results.

It leverages the power of Ghidra's ProgramAPI and [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 is written in Python3 using `pyhidra` to orchestrate Ghidra and `jpype` as the Python to Java interface to Ghidra.
Expand All @@ -34,15 +35,15 @@ subgraph diffs_output_dir
end
```

## Sample Diffs
### Sample Diffs

<div>
<a href="https://gist.github.com/clearbluejar/b95ae854a92ee917cd0b5c7055b60282"><img width="30%" align=top alt="image" src="https://github.com/clearbluejar/ghidriff/assets/3752074/d53b681f-8cc9-479c-af4c-5ec697cf4989"></a>
<a href="https://gist.github.com/clearbluejar/b95ae854a92ee917cd0b5c7055b60282#visual-chart-diff"><img width="30%" align=top alt="image" src="https://github.com/clearbluejar/ghidriff/assets/3752074/16d7ae4c-4df9-4bcd-b4af-0ce576d49ad1"></a>
<a href="https://diffpreview.github.io/?f6fecbc507a9f1a92c9231e3db7ef40d"><img width="30%" align=top src="https://github.com/clearbluejar/ghidriff/assets/3752074/662ed834-738d-4be1-96c3-8500ccab9591"/></a>
<div>

## Features
### Features

- Command Line (patch diffing workflow reduced to a single step)
- Highlights important changes in the TOC
Expand All @@ -64,7 +65,7 @@ end

See below for [CVE diffs and sample usage](#sample-usage)

## Design Goals
### Design Goals

- Find all added, deleted, and modified functions
- Provide foundation for automation
Expand All @@ -74,7 +75,7 @@ See below for [CVE diffs and sample usage](#sample-usage)
- Easy sharing of results
- Social Diffing

## Powered by Ghidra
### Powered by Ghidra

The heavy lifting of the binary analysis is done by Ghidra and the diffing is possible via Ghidra's Program API. `ghidriff` provides a diffing [workflow](#engine), function matching, and resulting markdown and HTML diff output.

Expand Down Expand Up @@ -119,7 +120,7 @@ class NewDiffTool(GhidraDiffEngine):
return [unmatched, matched]
```

## Implementations
### Implementations

There are currently 3 diffing implementations, which also display the evolution of diffing for the project.

Expand All @@ -129,12 +130,12 @@ There are currently 3 diffing implementations, which also display the evolution

Each implementation leverages the base class, and implements `find_changes`.

#### Usage
## 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] [--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]
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] [--min-func-len MIN_FUNC_LEN] [--use-calling-counts USE_CALLING_COUNTS] [--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
Expand All @@ -153,7 +154,7 @@ options:
```
#### Extendend Usage
### Extendend Usage
There are quite a few options here, and some complexity. Generally you can succeed with the defaults, but you can override the defaults as needed. One example might be to increase the JVM RAM used to run Ghidra to enable faster analysis of large binaries (`--max-ram-percent 80`). See help for details of other options.
Expand All @@ -162,16 +163,16 @@ There are quite a few options here, and some complexity. Generally you can succe
```bash
Ghidra Project Options:
-p PROJECT_LOCATION, --project-location PROJECT_LOCATION
Ghidra Project Path (default: .ghidra_projects)
Ghidra Project Path (default: ghidra_projects)
-n PROJECT_NAME, --project-name PROJECT_NAME
Ghidra Project Name (default: ghidriff)
-s SYMBOLS_PATH, --symbols-path SYMBOLS_PATH
Ghidra local symbol store directory (default: .symbols)
Ghidra local symbol store directory (default: symbols)

Engine Options:
--threaded, --no-threaded
Use threading during import, analysis, and diffing. Recommended (default: True)
--force-analysis Force a fresh binary analysis each run (default: False)
--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}
Expand All @@ -181,6 +182,10 @@ Engine Options:
--log-path LOG_PATH Set ghidriff log path. (default: ghidriff.log)
--va, --verbose-analysis
Verbose logging for analysis step. (default: False)
--min-func-len MIN_FUNC_LEN
Minimum function length to consider for diff (default: 10)
--use-calling-counts USE_CALLING_COUNTS
Add calling/called reference counts (default: True)

JVM Options:
--max-ram-percent MAX_RAM_PERCENT
Expand Down Expand Up @@ -217,14 +222,16 @@ export GHIDRA_INSTALL_DIR="/path/to/ghidra/"
pip install ghidriff
```
### Ghidriff in a Box - Devcontainer / Docker
## Ghidriff in a Box
Don't want to install Ghidra and Java on your host? Try "Ghidriff in a box". It supports multiple-platforms (x64 and arm64).
<p align='center'>
<img src="https://github.com/clearbluejar/ghidriff/assets/3752074/688756fc-038c-471a-8e49-e56a1c06e77c" height="300">
</p>
### Docker
`docker pull ghcr.io/clearbluejar/ghidriff:latest`
Expand Down Expand Up @@ -268,12 +275,12 @@ ghidriffs
```
#### For Ghidriff development
### Devcontainer - For Ghidriff development
Use the [.devcontainer](.devcontainer) in this repo. If you don't know how, follow the detailed instructions here: [ghidra-python-vscode-devcontainer-skeleton quick setup](https://github.com/clearbluejar/ghidra-python-vscode-devcontainer-skeleton#quick-start-setup---dev-container--best-option).
## Sample Usage
## Use Cases
### Diffing a full Windows Kernel
Expand Down
20 changes: 20 additions & 0 deletions www/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
41 changes: 41 additions & 0 deletions www/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Website

This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.

### Installation

```
$ yarn
```

### Local Development

```
$ yarn start
```

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

### Build

```
$ yarn build
```

This command generates static content into the `build` directory and can be served using any static contents hosting service.

### Deployment

Using SSH:

```
$ USE_SSH=true yarn deploy
```

Not using SSH:

```
$ GIT_USER=<Your GitHub username> yarn deploy
```

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
3 changes: 3 additions & 0 deletions www/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
28 changes: 28 additions & 0 deletions www/diff-sidebars.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
*/

// @ts-check

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
// By default, Docusaurus generates a sidebar from the docs folder structure

diffSidebar: [{ type: 'autogenerated', dirName: '.' }],
// But you can create a sidebar manually

// tutorialSidebar: [

// { type: 'autogenerated', dirName: '.' }
// ],

};

export default sidebars;
6 changes: 6 additions & 0 deletions www/diffs/CVEs/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"link": {
"type": "generated-index",
"description": "Sample CVE Diffs"
}
}
Loading

0 comments on commit 6e34506

Please sign in to comment.