runtimeembed

README

runtime-embed

runtime-embed is a Go library and CLI for embedding named data into existing executables and extracting that data at runtime.

It is inspired by sui and targets the same executable families:

• ELF
• PE
• Mach-O

Status

This repository currently provides:

• A Go package for inject/extract workflows
• A CLI with sui-style usage
• Native-structure embedding for ELF/PE/Mach-O
• Mach-O ad-hoc signing compatible with Apple Silicon execution

Install

go mod tidy

To build CLI:

go build -o runtime-embed ./cmd/runtime-embed

CLI Usage

insert/update section: runtime-embed <sectionname> <exe> <data_file> <output>
extract section from self: runtime-embed <sectionname>

Examples:

# Inject payload into an executable
runtime-embed hello ./app ./payload.bin ./app.out

# Inside the injected executable process, extract by section name
./app.out hello

Go API Usage

package main

import (
    "fmt"
    "os"

    runtimeembed "github.com/ray-d-song/runtime-embed"
)

func main() {
    exe, _ := os.ReadFile("./app")
    payload := []byte("Hello, runtime-embed")

    out, err := runtimeembed.InjectBinary(
        exe,
        "hello",
        payload,
        runtimeembed.DefaultInjectOptions(),
    )
    if err != nil {
        panic(err)
    }

    _ = os.WriteFile("./app.out", out, 0o755)

    data, err := runtimeembed.ExtractSectionFromBinary(out, "hello")
    if err != nil {
        panic(err)
    }
    fmt.Println(string(data))
}

From a running process (self-extract):

data, err := runtimeembed.FindSection("hello")

Design

The implementation now follows sui's native-format strategy:

1. ELF: inject data as SHT_NOTE (.note.sui) and keep it mapped via PT_LOAD + PT_NOTE
2. PE: inject data as RT_RCDATA resources in .rsrc
3. Mach-O:
   • arm64: add __SUI segment/section and shift __LINKEDIT-backed offsets
   • x86_64: use sentinel-based appended payload plus Mach-O metadata patching
4. Runtime extraction parses native structures by format and section/resource name

For Mach-O arm64 signing, the project includes an in-process ad-hoc signer (CodeDirectory/SuperBlob generation), aligned with sui behavior.

Error model

Primary exported errors:

• ErrUnsupportedBinary
• ErrSectionNotFound

Development

Run tests:

GOCACHE=$(pwd)/.cache/go-build go test ./...

Format:

gofmt -w .

License

MIT. See LICENSE.

Documentation

Index

• Variables
• func ExtractSectionFromBinary(exe []byte, section string) ([]byte, error)
• func FindSection(section string) ([]byte, error)
• func InjectBinary(exe []byte, section string, payload []byte, opts InjectOptions) ([]byte, error)
• type Format
  • func DetectFormat(data []byte) Format
• type InjectOptions
  • func DefaultInjectOptions() InjectOptions

Variables

var (
	ErrUnsupportedBinary = errors.New("unsupported binary format")
	ErrSectionNotFound   = errors.New("section not found")
)

Functions

func ExtractSectionFromBinary

func ExtractSectionFromBinary(exe []byte, section string) ([]byte, error)

ExtractSectionFromBinary reads a named section from an executable image.

func FindSection

func FindSection(section string) ([]byte, error)

FindSection reads section data from the currently running executable.

func InjectBinary

func InjectBinary(exe []byte, section string, payload []byte, opts InjectOptions) ([]byte, error)

InjectBinary injects named data in native structures for ELF/PE/Mach-O.

Types

type Format

type Format string

Format is a supported executable container format.

const (
	FormatUnknown Format = "unknown"
	FormatELF     Format = "elf"
	FormatPE      Format = "pe"
	FormatMachO   Format = "macho"
)

func DetectFormat

func DetectFormat(data []byte) Format

DetectFormat identifies executable file format by magic bytes.

type InjectOptions

type InjectOptions struct {
	// ResignMachO requests ad-hoc re-signing for Mach-O outputs (macOS only).
	ResignMachO bool
}

InjectOptions controls injection behavior.

func DefaultInjectOptions

func DefaultInjectOptions() InjectOptions

DefaultInjectOptions returns recommended defaults for current host OS.