search

mandiant / GoReSym

Go symbol recovery tool
MIT License
498 stars 62 forks source link
gsoc-2024

readme

GoReSym

GoReSym is a Go symbol parser that extracts program metadata (such as CPU architecture, OS, endianness, compiler version, etc), function metadata (start & end addresses, names, sources), filename and line number metadata, and embedded structures and types. This cross platform program is based directly on the open source Go compiler and runtime code.

The upstream Go runtime code is extended to handle:

Usage

Refer to https://www.mandiant.com/resources/blog/golang-internals-symbol-recovery for reverse engineering details and example usage.

You can download pre-built linux, macos, and windows GoReSym binaries from the Releases tab.

To build from source with a recent Go compiler, invoke the Go compiler:

go build

Once built invoke GoReSym like this:

GoReSym.exe -t -d -p /path/to/input.exe

In this example, we ask GoReSym to recover type names (-t), user package names, standard Go package names (-d), and input file paths (-p) embedded within the file /path/to/input.exe. The output looks like this:

{
    "Version": "1.14.15",
    "BuildId": "Zb9QmokKTiOUgHKmaIwz/wd2rtE3W9PN-um1Ocdzh/qTdqcTY_jVajHy_-TtYv/Z_kJu9M77OjfijEiHMcF",
    "Arch": "amd64",
    "TabMeta": {
        "VA": 5174784,
        "Version": "1.2",
        "Endianess": "LittleEndian",
        "CpuQuantum": 1,
        "CpuQuantumStr": "x86/x64",
        "PointerSize": 8
    },
    "ModuleMeta": {
        "VA": 5678816,
        "Types": 4845568,
        "ETypes": 5171904,
        "Typelinks": {
            "Data": 5171904,
            "Len": 695,
            "Capacity": 695
        },
        "ITablinks": {
            "Data": 5174688,
            "Len": 11,
            "Capacity": 11
        },
        "LegacyTypes": {
            "Data": 0,
            "Len": 0,
            "Capacity": 0
        }
    },
    "Types": [ ... ],
    "Files": [ ... ],
    "UserFunctions": [ ... ],
    "StdFunctions": [ ... ]
}

Here are all the available flags:

To import this information into IDA Pro you can run the script found in https://github.com/mandiant/GoReSym/blob/master/IDAPython/goresym_rename.py. It will read a json file produced by GoReSym and set symbols/labels in IDA.

Version Support

As the Go compiler and runtime have changed, so have the embedded metadata structures. GoReSym supports the following combinations of Go releases & metadata:

The moduledata table used to extract types doesn't exist prior to Go 1.5, so this library will never support extracting types from very old Go versions.

This library current handles the pclntab layouts pre 1.2, 1.2, 1.16, 1.18, and 1.20. Note that the pclntab version is always <= the Go runtime version (ex: Go runtime 1.19 uses the 1.18 pclntab layout), we aim to always support the latest runtime versions.

Contributions

Much of the source code from GoReSym is copied from the upstream Go compiler source directory /internal. To make this work, we've had to massage the source a bit. If you want to contribute to GoReSym, read on so we can explain this import process.

Due to the way Go packages work, we needed to remove the /internal path from the source file tree. This resulted in a lot of copying of internal Go files, where the directory tree is mostly intact but with small changes to many files' imports: references to /internal paths were replaced with github.com/mandiant/GoReSym/.

We also modified many internal structures to export fields and methods. These are not exported by Go upstream because users should not rely upon them. However, the purpose of this tool is to extract internal information, so we're taking on the task of maintaining these structures. It's not a great situation, but it's not easily avoidable. If you update this repository, you must take care to keep these modifications intact. It's probably better to manually merge in commits from upstream rather than copying upstream files wholesale.

I am open to suggestions on how to better structure this project to avoid these issues while still compiling with the typical go build. There is a previous discussion involving Go maintainers here.

Ignoring some trivial changes, most new logic exists in /objfile. For example, the file objfile/internals defines the reversed internal Go structures that GoReSym parses.

References

Changes

License

MIT