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
- Variables
- type Arguments
- func (arguments *Arguments) AddBytes(value []byte) error
- func (arguments *Arguments) AddInt16(value int16) error
- func (arguments *Arguments) AddInt32(value int32) error
- func (arguments *Arguments) AddString(value string) error
- func (arguments *Arguments) AddUTF16String(value string) error
- func (arguments *Arguments) Bytes() []byte
- func (arguments *Arguments) Reset()
- type Import
- type LoadOptions
- type Object
- type Output
Constants ¶
const ( OutputDefault = 0x00 OutputError = 0x0d OutputOEM = 0x1e OutputUTF8 = 0x20 )
Beacon output channel values used by Cobalt-compatible BOFs.
Variables ¶
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 ¶
AddBytes appends a four-byte length followed by an arbitrary byte string.
func (*Arguments) AddUTF16String ¶
AddUTF16String appends a NUL-terminated UTF-16LE "wstring" argument.
type Import ¶
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 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) Execute ¶
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 ¶
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.