DOCSEARCHbyAlgolia
Submit Docs

GoReSym Documentation

repository·master·Indexed 21 days ago

https://github.com/mandiant/goresym

A specialized Go symbol parser for reverse engineering that extracts deep metadata from Go binaries, including types, functions, and file paths. It supports stripped or malformed binaries (such as UPX packed) across ARM64, Intel x86/x64, MACH-O, ELF, and PE formats. GoReSym provides a CLI for JSON or flat text output and an IDAPython script for importing symbols into IDA Pro. It supports pclntab parsing for Go versions ≥ 1.2 and type parsing for Go versions ≥ 1.5.

Tokens
1.8K
Snippets
3
Records
12
Agent score
27%

What's inside GoReSym

  1. GoReSym version and architecture support

    master

    GoReSym supports a wide range of Go environments:

    • Architectures/OS/Endianness: All combinations of ARM64, Intel x86/x64, MACH-O, ELF, and PE (Windows) across both big and little endian.
    • pclntab parsing: Supported for Go versions $\ge$ 1.2. It handles layouts for versions 1.2, 1.16, 1.18, and 1.20.
    • moduledata location: Supported for Go versions $\ge$ 1.2.
    • moduledata type parsing: Supported for Go versions $\ge$ 1.5.

    Note: Because the moduledata table required for type extraction did not exist prior to Go 1.5, GoReSym cannot extract types from Go versions older than 1.5.

  3. Use GoReSym to extract metadata

    master

    GoReSym is used to extract program metadata (CPU architecture, OS, endianness, compiler version), function metadata, filename/line number metadata, and embedded structures/types from Go binaries. It is specifically designed to handle stripped binaries, malformed unpacked binaries (like UPX), and binaries with split data ranges.

    Basic usage involves passing the input file path with the -p flag and optional extraction flags. By default, it outputs results in JSON format.

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

  4. Install and build GoReSym

    master

    You can use GoReSym by downloading pre-built binaries for linux, macos, and windows from the GitHub Releases page, or by building it from source using a recent Go compiler.

    To build from source, run:

    go build

  5. Extract Go program metadata with GoReSym

    master

    GoReSym is a tool used to recover symbols and metadata from Go binaries. It can extract information such as the Go version, build ID, architecture, operating system, type structures, interfaces, file paths, embedded strings, and function metadata (both user-defined and standard library functions).

    By default, GoReSym outputs the extracted metadata as a formatted JSON object. You can also use the -human flag to view a simplified, flat text representation of the information.

    goresym <filepath>

  6. Understand the ExtractMetadata structure

    master

    The ExtractMetadata struct is the primary data contract returned by the extraction logic. It contains the following fields:

    • Version: The detected Go version.
    • BuildId: The build ID of the binary.
    • Arch: The target architecture (e.g., amd64).
    • OS: The target operating system (e.g., linux).
    • TabMeta: PcLnTabMetadata containing runtime table info (VA, Endianness, PointerSize, etc.).
    • ModuleMeta: objfile.ModuleData containing module-level information.
    • Types: A slice of objfile.Type (populated if printTypes is true).
    • Interfaces: A slice of objfile.Type representing interfaces (populated if printTypes is true).
    • BuildInfo: debug.BuildInfo containing Go build settings and dependencies.
    • Files: A slice of strings representing source file paths.
    • UserFunctions: A slice of FuncMetadata for non-standard library functions.
    • StdFunctions: A slice of FuncMetadata for standard library functions (populated if printStdPkgs is true).
    • Strings: A slice of objfile.StringEntry containing extracted strings.

  7. GoReSym CLI flag reference

    master

    The following flags are available for the GoReSym CLI:

    FlagDescription
    -d(default) Print standard Go packages in addition to user packages.
    -pPrint any file paths embedded in the pclntab.
    -tPrint Go type names.
    -stringsExtract embedded Go strings by analyzing the string internment table.
    -m <virtual address>(manual) Dump the RTYPE structure recursively at the given virtual address.
    -v <version string>(version) Override automated version detection with the provided version. Required for some stripped binaries; incorrect versions will cause type parsing to fail.
    -humanPrint a flat text listing instead of JSON (useful for viewing structures and interfaces).
    -aboutPrint license information.

  8. Extract metadata from byte slices using main_impl_tmpfile

    master

    To extract metadata from a byte slice (e.g., a file loaded into memory) rather than a file on disk, use main_impl_tmpfile. This function creates a temporary file, writes the bytes to it, and then calls main_impl.

    Signature: func main_impl_tmpfile(fileBytes []byte, printStdPkgs bool, printFilePaths bool, printTypes bool, noPrintFunctions bool, manualTypeAddress int, versionOverride string, printStrings bool) (metadata ExtractMetadata, err error)

  9. Extract metadata using main_impl

    master

    If integrating GoReSym logic into another Go program, use main_impl to extract metadata from a file.

    Signature: func main_impl(fileName string, printStdPkgs bool, printFilePaths bool, printTypes bool, noPrintFunctions bool, manualTypeAddress int, versionOverride string, printStrings bool) (metadata ExtractMetadata, err error)

    Parameters:

    • fileName: Path to the target binary.
    • printStdPkgs: If true, includes standard library functions in StdFunctions.
    • printFilePaths: If true, populates the Files slice.
    • printTypes: If true, automatically enumerates type and interface links.
    • noPrintFunctions: If true, excludes function metadata from the result.
    • manualTypeAddress: If non-zero, parses the RTYPE at this specific virtual address instead of automated enumeration.
    • versionOverride: A string to force a specific Go version (e.g., "1.18").
    • printStrings: If true, extracts embedded strings into the Strings field.

  10. GoReSym CLI flags reference

    master

    The following flags are available when using the GoReSym CLI:

    FlagDescription
    -aboutPrint license and author information
    -dPrint Default Packages (standard library functions)
    -pPrint File Paths
    -tPrint types automatically, enumerate typelinks and itablinks
    -nofuncsDo not print user and standard function sections
    -m <address>Manually parse the RTYPE at the provided virtual address (disables automated enumeration of moduledata typelinks/itablinks)
    -v <version>Override the automated version detection (e.g., 1.17). Use this if automated detection fails.
    -humanHuman view: print information flat rather than JSON (some information is omitted for clarity)
    -stringsExtract embedded Go strings from binary

  11. FuncMetadata structure

    master

    The FuncMetadata struct represents a single function's location and identity within the binary.

    Fields:

    • Start: The virtual address (VA) where the function begins.
    • End: The virtual address (VA) where the function ends.
    • PackageName: The name of the package the function belongs to.
    • FullName: The fully qualified name of the function.

  12. PcLnTabMetadata structure

    master

    The PcLnTabMetadata struct contains metadata extracted from the Program Counter Line Table (pclntab).

    Fields:

    • VA: The virtual address of the table.
    • Version: The version string of the table.
    • Endianess: The endianness (e.g., LittleEndian).
    • CpuQuantum: The minimal unit for a program counter (e.g., 1 for x86, 4 for ARM).
    • CpuQuantumStr: A human-readable string describing the architecture based on the quantum (e.g., x86/x64/wasm, arm/mips/ppc/riscv, or s390x).
    • PointerSize: The size of a pointer in bytes.