goresolver 1.4.1
A tool generating and comparing control flow graphs of GO samples.
Requires Python: >=3.12

# GoResolver

GoResolver is a Go analysis tool using both Go symbol extraction and Control Flow Graph (CFG) similarity to identify and resolve the function symbols of an obfuscated Go binary.

This tool supports all three major operating systems, Windows, MacOS and Linux as well as their respective executables formats, PE, ELF and Mach-O for the X86, AMD64, ARM and ARM64 architectures.

## How to install

To install GoResolver, we recommend pulling directly from PyPi :

```bash
pip install goresolver
```

This will install GoResolver as well as its necessary dependencies.

As GoResolver may need differents Go version for its similairty analysis, you will also need to install base Go version (1.20.6 or superior) as a dependency.

See https://go.dev/dl/ to install the right Go version for your device.

### Building from source

If you wish to build & install GoResolver from source instead, please follow the steps below : 

#### Dependencies :

You will need to install base Go version (1.20.6 or superior). See https://go.dev/dl/ to install the right Go version for your device.

#### Build process :

To build GoResolver from source use Hatch's usual build command :
```bash
hatch build
```

The built archive will be placed in the "dist" directory as a .whl file.
To install GoResolver, simply install the .whl file using pip.

```bash
pip install dist/goresolver-*.whl
```

## Command Line Usage

Once installed, a new utility `goresolver` will be available. The two following commands are available:


### Resolve - Analyze Go binary and retrieve symbols
```
usage: goresolver resolve [-h] [-l [LIBS ...]] [-v VERSION] [-f] [-r COMPARE_REPORT] [-b BACKUP_PATH] [-o OUTPUT] [-t THRESHOLD] [-x] [-g] [-y]
                          sample_path [reference_path]

positional arguments:
  sample_path           Path to the GO sample to analyze.
  reference_path        Path to the GO reference sample to compare to (if any).

options:
  -h, --help                            show this help message and exit
  -l, --libs [LIBS ...]                 List of GO libs to include in the generated samples.
  -v, --go-version VERSION              The GO version to build the reference samples with.
  -f, --force                           Force build existing samples.
  -r, --compare-report COMPARE_REPORT   Path to an already generated GoGrapher report.
  -b, --backup-path BACKUP_PATH         Path where to save the intermediary GoGrapher report.
  -o, --output OUTPUT                   Path of the output JSON report.
  -t, --threshold THRESHOLD             Value at which matches are considered significant.
  -x, --extract                         Extract symbols from the Go sample.
  -g, --graph                           Compare the Go sample against generated references.
  -y, --types                           Parse runtime types from the Go sample.
```

### Manage - Manage the installed Go versions
```
usage: goresolver manage [-h] (--list_available | --list_installed | -i VERSIONS | -u VERSIONS)

options:
  -h, --help                            show this help message and exit
  --list_available                      List the GO versions available to install.
  --list_installed                      List the currently installed GO versions.
  -i, --install VERSIONS                The list of GO versions to install.
  -u, --uninstall VERSIONS              The list of GO versions to uninstall.
```

Here is a typical workflow using GoResolver :

```bash
goresolver resolve -v go1.18 -o "path/to/report.json" "path/to/sample.exe"
```

### Options

```
-l, --libs [LIBS ...]                List of GO libs to include in the generated samples.
-v, --go-version VERSION             The GO version to build the reference samples with.
```

The `--libs` and `--go-version` options allows you to tweak which Go version and libraries are used to generate the reference sample.

By default, GoResolver will attempt to identify to GoVersion used to generate the sample and failing that test a range of Go version and select the closest one.

```
-t, --threshold THRESHOLD            Value at which matches are considered significant.
```

The `--threshold` allow you to tweak the confidence threshold necessary to consider symbols obtained through the graph algorithm in a range of `0.0` to `1.O`. The default value is `0.9`.

```
-x, --extract                        Extract symbols from the Go sample.
-g, --graph                          Compare the Go sample against generated references.
```

The `--extract` and `--graph` options allow you to toggle either algorithm in isolation. Best result are achieved when both options are turned on, which is the default behavior.

## Plugins

GoResolver comes with plugins for both IDA and Ghidra in the `Plugin` directory. Discrete releases of the GoResolver plugin are also available in the release section of this repository. Theses plugins make using GoResolver in conjunction with theses tools easier, by giving an easy way to import reports generated by the CLI tool into their respective databases.

Both plugins share the same `common` directory. When installing one or the other be sure to copy the accompanying `ida` or `ghidra` files as well. See the Plugin's README.md for more information.