bof

package
v0.0.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 29, 2026 License: GPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package bof loads and executes native Beacon Object Files from memory. Consumers opt in to BOF support by importing this package.

Index

Constants

View Source
const (
	OutputDefault = 0x00
	OutputError   = 0x0d
	OutputOEM     = 0x1e
	OutputUTF8    = 0x20
)

Beacon output channel values used by Cobalt-compatible BOFs.

Variables

View Source
var ErrClosed = errors.New("reflektor: BOF is closed")

ErrClosed is returned when Execute is called after Close.

Functions

This section is empty.

Types

type Arguments

type Arguments struct {
	// contains filtered or unexported fields
}

Arguments builds the length-prefixed argument format consumed by the BeaconData* callbacks. Its zero value is ready for use.

func (*Arguments) AddBytes

func (arguments *Arguments) AddBytes(value []byte) error

AddBytes appends a four-byte length followed by an arbitrary byte string.

func (*Arguments) AddInt16

func (arguments *Arguments) AddInt16(value int16) error

AddInt16 appends a little-endian Beacon "short" argument.

func (*Arguments) AddInt32

func (arguments *Arguments) AddInt32(value int32) error

AddInt32 appends a little-endian Beacon "integer" argument.

func (*Arguments) AddString

func (arguments *Arguments) AddString(value string) error

AddString appends a NUL-terminated UTF-8 string argument.

func (*Arguments) AddUTF16String

func (arguments *Arguments) AddUTF16String(value string) error

AddUTF16String appends a NUL-terminated UTF-16LE "wstring" argument.

func (*Arguments) Bytes

func (arguments *Arguments) Bytes() []byte

Bytes returns an owned argument buffer with its four-byte payload-length prefix. Calling Bytes does not consume or alias the builder.

func (*Arguments) Reset

func (arguments *Arguments) Reset()

Reset discards all currently packed arguments while retaining capacity.

type Import

type Import struct {
	Name         string
	Weak         bool
	Builtin      bool
	RequiresHost bool
}

Import describes one external symbol referenced by a BOF image. Name is the exact object-file symbol spelling. Builtin marks callbacks implemented by Reflektor. RequiresHost marks Beacon APIs that Reflektor deliberately does not implement and will not search for in system libraries.

type LoadOptions

type LoadOptions struct {
	// EntryPoint selects an exact defined executable symbol. When empty,
	// Reflektor searches go, _go, coffee, and _coffee in that order.
	EntryPoint string

	// ValidateImports runs after parsing and host validation, but before image
	// allocation, callback registration, or dynamic-library lookup. The slice
	// is an owned, deterministic snapshot and may be retained by the callback.
	ValidateImports func([]Import) error

	// ResolveSymbol may provide a native address for an import that is not a
	// built-in Reflektor callback. Function addresses must follow the object's
	// platform ABI. Returning handled=false falls back to the normal system
	// resolver, except for RequiresHost imports, which fail explicitly. Any
	// returned error aborts loading. A handled address must be nonzero and
	// remain valid until the loaded BOF is closed. The resolver is called at
	// most once for each exact imported name during each load. Data imports
	// must use the object's native indirection convention when required; for
	// example, Windows data declarations should use __declspec(dllimport).
	ResolveSymbol func(Import) (address uintptr, handled bool, err error)
}

LoadOptions controls entry-point selection and external-symbol policy. Its zero value preserves Load's default behavior.

type Object

type Object struct {
	// contains filtered or unexported fields
}

Object is an in-memory native relocatable Beacon Object File. A loaded object may be executed more than once. Close releases its mapped image.

func Load

func Load(data []byte) (*Object, error)

Load loads a native relocatable BOF image from memory using default load options.

func LoadFile

func LoadFile(path string) (*Object, error)

LoadFile reads and loads a native relocatable BOF image from disk.

func LoadFileWithOptions

func LoadFileWithOptions(path string, options LoadOptions) (*Object, error)

LoadFileWithOptions reads and loads a native relocatable BOF image from disk using the supplied load options.

func LoadWithOptions

func LoadWithOptions(data []byte, options LoadOptions) (*Object, error)

LoadWithOptions loads a native relocatable BOF image from memory. Windows accepts COFF, Linux accepts ELF, and Darwin accepts native Mach-O plus legacy ELF relocatable objects.

func (*Object) Close

func (object *Object) Close() error

Close releases the object's mapped image. It is safe to call more than once.

func (*Object) Execute

func (object *Object) Execute(args []byte) ([]Output, error)

Execute invokes the object's go (or coffee) entry point with an encoded Beacon argument buffer. It returns one record for every valid BeaconOutput or BeaconPrintf call, including zero-length records, in callback-capture order. Records captured during an execution that returns a terminal error are returned together with that error; callers must process the records even when err is non-nil.

type Output

type Output struct {
	Type int
	Data []byte
}

Output is one typed record emitted through BeaconOutput or BeaconPrintf. Type is the signed Beacon output channel supplied by the object; unknown values are preserved without remapping. Data is an owned copy of the raw record bytes and may have zero length. The bytes remain valid after later Execute calls and after Close.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL