visitors

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: May 11, 2023 License: BSD-3-Clause Imports: 26 Imported by: 6

Documentation

Overview

Package visitors uses the Visitor interface to recursively apply an operation over the firmware image. Also, functions are exported for using the visitors through the command line.

Index

Constants

View Source
const (
	InsertWhatTypeUndefined = InsertWhatType(iota)
	InsertWhatTypeFile
	InsertWhatTypePadFile

	EndOfInsertWhatType
)
View Source
const (
	InsertWherePrepositionUndefined = InsertWherePreposition(iota)
	InsertWherePrepositionFront
	InsertWherePrepositionEnd
	InsertWherePrepositionAfter
	InsertWherePrepositionBefore

	EndOfInsertWherePreposition
)

Variables

This section is empty.

Functions

func ExecuteCLI

func ExecuteCLI(f uefi.Firmware, v []uefi.Visitor) error

ExecuteCLI applies each Visitor over the firmware in sequence.

func FindDXEFV

func FindDXEFV(f uefi.Firmware) (*uefi.FirmwareVolume, error)

FindDXEFV is a helper function to quickly retrieve the firmware volume that contains the DxeCore.

func FindEnclosingFV

func FindEnclosingFV(f uefi.Firmware, file *uefi.File) (*uefi.FirmwareVolume, error)

FindEnclosingFV finds the FV that contains a file.

func FindExactlyOne

func FindExactlyOne(f uefi.Firmware, pred func(f uefi.Firmware) bool) (uefi.Firmware, error)

FindExactlyOne does a find using a supplied predicate and errors if there's more than one.

func FindFileFVPredicate

func FindFileFVPredicate(r string) (func(f uefi.Firmware) bool, error)

FindFileFVPredicate is a generic predicate for searching FVs, files and UI sections.

func FindFilePredicate

func FindFilePredicate(r string) (func(f uefi.Firmware) bool, error)

FindFilePredicate is a generic predicate for searching files and UI sections only.

func FindNVarPredicate

func FindNVarPredicate(r string) (func(f uefi.Firmware) bool, error)

FindNVarPredicate is a generic predicate for searching NVar only.

func ListCLI

func ListCLI() string

ListCLI prints out the help entries in the visitor struct as a newline-separated string in the form:

name: help

func ParseCLI

func ParseCLI(args []string) ([]uefi.Visitor, error)

ParseCLI constructs a list of visitors from the given CLI argument list.

func RegisterCLI

func RegisterCLI(name string, help string, numArgs int, createVisitor func([]string) (uefi.Visitor, error))

RegisterCLI registers a function `createVisitor` to be called when parsing the arguments with `ParseCLI`. For a Visitor to be accessible from the command line, it should have an init function which registers a `createVisitor` function here.

Types

type Assemble

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

Assemble reconstitutes the firmware tree assuming that the leaf node buffers are accurate

func (*Assemble) Run

func (v *Assemble) Run(f uefi.Firmware) error

Run just applies the visitor.

func (*Assemble) Visit

func (v *Assemble) Visit(f uefi.Firmware) error

Visit applies the Assemble visitor to any Firmware type.

type Cat

type Cat struct {
	// Input
	Predicate func(f uefi.Firmware) bool

	// Output
	io.Writer
	Matches []uefi.Firmware
}

Cat concatenates all RAW data sections from a file into a single byte slice.

func (*Cat) Run

func (v *Cat) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Cat) Visit

func (v *Cat) Visit(f uefi.Firmware) error

Visit applies the Extract visitor to any Firmware type.

type Comment

type Comment struct {
	W io.Writer
	// contains filtered or unexported fields
}

Comment holds the io.Writer and args for a comment

func (*Comment) Run

func (v *Comment) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Comment) Visit

func (v *Comment) Visit(f uefi.Firmware) error

Visit applies the Comment visitor to any Firmware type.

type Count

type Count struct {
	// Optionally write result as JSON.
	W io.Writer `json:"-"`

	// Output
	FirmwareTypeCount map[string]int
	FileTypeCount     map[string]int
	SectionTypeCount  map[string]int
}

Count counts the number of each firmware type.

func (*Count) Run

func (v *Count) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Count) Visit

func (v *Count) Visit(f uefi.Firmware) error

Visit applies the Count visitor to any Firmware type.

type CreateFV

type CreateFV struct {
	AbsOffset uint64
	Size      uint64
	Name      guid.GUID
	// contains filtered or unexported fields
}

CreateFV creates a firmware volume at given offset

func (*CreateFV) Run

func (v *CreateFV) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*CreateFV) Visit

func (v *CreateFV) Visit(f uefi.Firmware) error

Visit applies the CreateFV visitor to any Firmware type.

type DXECleaner

type DXECleaner struct {
	// This function tests whether the firmware boots. The return values can be:
	//
	//     - (false, nil): The firmware was tested and failed to boot.
	//     - (false, err): The firmware was tested and failed to boot due to err.
	//     - (true, nil):  The firmware was tested and booted.
	//     - (true, err):  Failed to test the firmware due to err.
	Test func(f uefi.Firmware) (bool, error)

	// Predicate to determine whether a DXE can be removed.
	Predicate FindPredicate

	// List of GUIDs which were removed.
	Removals []guid.GUID

	// Logs are written to this writer.
	W io.Writer
}

DXECleaner removes DXEs sequentially in multiple rounds. Each round, an attempt is made to remove each DXE. The Test function determines if the removal was successful. Additional rounds are performed until all DXEs are removed.

func (*DXECleaner) Run

func (v *DXECleaner) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*DXECleaner) Visit

func (v *DXECleaner) Visit(f uefi.Firmware) error

Visit applies the DXEClearn visitor to any Firmware type.

type Dump

type Dump struct {
	// Input
	Predicate func(f uefi.Firmware) bool

	// Output
	// The file is written to this writer.
	W io.Writer
}

Dump a firmware file using a GUID or a name

func (*Dump) Run

func (v *Dump) Run(f uefi.Firmware) error

Run just calls the visitor

func (*Dump) Visit

func (v *Dump) Visit(f uefi.Firmware) error

Visit uses find to dump a file to W.

type Extract

type Extract struct {
	BasePath string
	DirPath  string
	Index    *uint64
}

Extract extracts any Firmware node to DirPath

func (*Extract) Run

func (v *Extract) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Extract) Visit

func (v *Extract) Visit(f uefi.Firmware) error

Visit applies the Extract visitor to any Firmware type.

type Find

type Find struct {
	// Input
	// Only when this functions returns true will the file appear in the
	// `Matches` slice.
	Predicate FindPredicate

	// Output
	Matches []uefi.Firmware

	// JSON is written to this writer.
	W io.Writer
	// contains filtered or unexported fields
}

Find a firmware file given its name or GUID.

func (*Find) Run

func (v *Find) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Find) Visit

func (v *Find) Visit(f uefi.Firmware) error

Visit applies the Find visitor to any Firmware type.

type FindPredicate

type FindPredicate = func(f uefi.Firmware) bool

FindPredicate is used to filter matches in the Find visitor.

func FindAndPredicate

func FindAndPredicate(predicate1 FindPredicate, predicate2 FindPredicate) FindPredicate

FindAndPredicate is a generic predicate which takes the logical OR of two existing predicates.

func FindFileGUIDPredicate

func FindFileGUIDPredicate(r guid.GUID) FindPredicate

FindFileGUIDPredicate is a generic predicate for searching file GUIDs only.

func FindFileTypePredicate

func FindFileTypePredicate(t uefi.FVFileType) FindPredicate

FindFileTypePredicate is a generic predicate for searching file types only.

func FindNotPredicate

func FindNotPredicate(predicate FindPredicate) FindPredicate

FindNotPredicate is a generic predicate which takes the logical NOT of an existing predicate.

type Flatten

type Flatten struct {
	// Optionally write result as JSON.
	W io.Writer

	// Outputted flattened tree.
	List []FlattenedFirmware
	// contains filtered or unexported fields
}

Flatten places all nodes into a single slice and removes their children. Each node contains the index of its parent (the root node's parent is itself). This format is suitable for insertion into a database.

func (*Flatten) Run

func (v *Flatten) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Flatten) Visit

func (v *Flatten) Visit(f uefi.Firmware) error

Visit applies the Flatten visitor to any Firmware type.

type FlattenedFirmware

type FlattenedFirmware struct {
	Parent int
	Type   string
	Value  uefi.Firmware
}

FlattenedFirmware appears in the Flatten.List, contains the index of the parrent and has no children.

type Insert

type Insert struct {

	// Input
	Predicate func(f uefi.Firmware) bool
	NewFile   *uefi.File
	InsertType

	// Matched File
	FileMatch uefi.Firmware
}

Insert inserts a firmware file into an FV

func (*Insert) Run

func (v *Insert) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Insert) Visit

func (v *Insert) Visit(f uefi.Firmware) error

Visit applies the Insert visitor to any Firmware type.

type InsertType

type InsertType int

InsertType defines the insert type operation that is requested

const (

	// InsertTypeFront inserts a file at the beginning of the firmware volume,
	// which is specified by 1) FVname GUID, or (File GUID/File name) of a file
	// inside that FV.
	InsertTypeFront InsertType = iota
	// InsertTypeEnd inserts a file at the end of the specified firmware volume.
	InsertTypeEnd

	// These two specify a File to insert before or after
	// InsertTypeAfter inserts after the specified file,
	// which is specified by a File GUID or File name.
	InsertTypeAfter
	// InsertTypeBefore inserts before the specified file.
	InsertTypeBefore
	// InsertTypeDXE inserts into the Dxe Firmware Volume. This works by searching
	// for the DxeCore first to identify the Dxe Firmware Volume.
	InsertTypeDXE

	// InsertTypeReplaceFFS replaces the found file with the new FFS. This is used
	// as a shortcut for remove and insert combined, but also when we want to make
	// sure that the starting offset of the new file is the same as the old.
	InsertTypeReplaceFFS

	// InsertTypeInsert is generalization of all InsertTypeInsert* above. Arguments:
	// * The first argument specifies the type of what to insert (possible values: "file" or "pad_file")
	// * The second argument specifies the content of what to insert:
	//     - If the first argument is "file" then a path to the file content is expected.
	//     - If the first argument is "pad_file" then the size is expected.
	// * The third argument specifies the preposition of where to insert to (possible values: "front", "end", "after", "before").
	// * The forth argument specifies the preposition object of where to insert to. It could be FV_or_File GUID_or_name.
	//   For example combination "end 5C60F367-A505-419A-859E-2A4FF6CA6FE5" means to insert to the end of volume
	//   "5C60F367-A505-419A-859E-2A4FF6CA6FE5".
	//
	// A complete example: "pad_file 256 after FC510EE7-FFDC-11D4-BD41-0080C73C8881" means to insert a pad file
	// of size 256 bytes after file with GUID "FC510EE7-FFDC-11D4-BD41-0080C73C8881".
	InsertTypeInsert
)

Insert Types

func (InsertType) String

func (i InsertType) String() string

String creates a string representation for the insert type.

type InsertWhatType added in v1.1.0

type InsertWhatType int

InsertWhatType defines the type of inserting object

func ParseInsertWhatType added in v1.1.0

func ParseInsertWhatType(s string) InsertWhatType

ParseInsertWhatType converts a string to InsertWhatType

func (InsertWhatType) String added in v1.1.0

func (t InsertWhatType) String() string

String implements fmt.Stringer.

type InsertWherePreposition added in v1.1.0

type InsertWherePreposition int

InsertWherePreposition defines the type of inserting object

func ParseInsertWherePreposition added in v1.1.0

func ParseInsertWherePreposition(s string) InsertWherePreposition

ParseInsertWherePreposition converts a string to InsertWherePreposition

func (InsertWherePreposition) String added in v1.1.0

func (p InsertWherePreposition) String() string

String implements fmt.Stringer.

type JSON

type JSON struct {
	// JSON is written to this writer.
	W io.Writer
}

JSON prints any Firmware node as JSON.

func (*JSON) Run

func (v *JSON) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*JSON) Visit

func (v *JSON) Visit(f uefi.Firmware) error

Visit applies the JSON visitor to any Firmware type.

type NVRamCompact

type NVRamCompact struct {
}

NVRamCompact compact nvram content by removing old version of variables

func (*NVRamCompact) Run

func (v *NVRamCompact) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*NVRamCompact) Visit

func (v *NVRamCompact) Visit(f uefi.Firmware) error

Visit applies the NVRamCompact visitor to any Firmware type.

type NVarInvalidate

type NVarInvalidate struct {
	// Input
	Predicate func(f uefi.Firmware) bool

	// Output
	Matches []uefi.Firmware
	// logs are written to this writer.
	W io.Writer
}

NVarInvalidate set NVar as Invalid

func (*NVarInvalidate) Run

func (v *NVarInvalidate) Run(f uefi.Firmware) error

Run uses find and wraps Visit.

func (*NVarInvalidate) Visit

func (v *NVarInvalidate) Visit(f uefi.Firmware) error

Visit set NVar as Invalid

type ParseDir

type ParseDir struct {
	BasePath string
}

ParseDir creates the firmware tree and reads the binaries from the provided directory

func (*ParseDir) Parse

func (v *ParseDir) Parse() (uefi.Firmware, error)

Parse parses a directory and creates the tree.

func (*ParseDir) Run

func (v *ParseDir) Run(f uefi.Firmware) error

Run is not actually implemented cause we can't fit the interface

func (*ParseDir) Visit

func (v *ParseDir) Visit(f uefi.Firmware) error

Visit applies the ParseDir visitor to any Firmware type.

type Remove

type Remove struct {
	// Input
	Predicate  func(f uefi.Firmware) bool
	Pad        bool
	RemoveDxes bool // I hate this, but there's no good way to work around our current structure

	// Output
	Matches []uefi.Firmware
	// Calling this function undoes the removals performed by this visitor.
	Undo func()
	// logs are written to this writer.
	W io.Writer
}

Remove all firmware files with the given GUID.

func (*Remove) Run

func (v *Remove) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Remove) Visit

func (v *Remove) Visit(f uefi.Firmware) error

Visit applies the Remove visitor to any Firmware type.

type Repack

type Repack struct {
	// Input
	Predicate func(f uefi.Firmware) bool

	// Matched File
	FileMatch *uefi.File
}

Repack repacks a per file compressed FV into a singularly compressed nested FV

func (*Repack) Run

func (v *Repack) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Repack) Visit

func (v *Repack) Visit(f uefi.Firmware) error

Visit applies the Repack visitor to any Firmware type.

type ReplacePE32

type ReplacePE32 struct {
	// Input
	Predicate func(f uefi.Firmware) bool
	NewPE32   []byte

	// Output
	Matches []uefi.Firmware
}

ReplacePE32 replaces PE32 sections with NewPE32 for all files matching Predicate.

func (*ReplacePE32) Run

func (v *ReplacePE32) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*ReplacePE32) Visit

func (v *ReplacePE32) Visit(f uefi.Firmware) error

Visit applies the Extract visitor to any Firmware type.

type Save

type Save struct {
	DirPath string
}

Save calls Assemble, then outputs the top image to a file.

func (*Save) Run

func (v *Save) Run(f uefi.Firmware) error

Run just applies the visitor.

func (*Save) Visit

func (v *Save) Visit(f uefi.Firmware) error

Visit calls the assemble visitor to make sure everything is reconstructed. It then outputs the top level buffer to a file.

type Table

type Table struct {
	W      *tabwriter.Writer
	Scan   bool
	Layout bool
	Depth  int
	// contains filtered or unexported fields
}

Table prints the GUIDS, types and sizes as a compact table.

func (*Table) Run

func (v *Table) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Table) Visit

func (v *Table) Visit(f uefi.Firmware) error

Visit applies the Table visitor to any Firmware type.

type TightenME

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

TightenME tighten ME's belt to give more room for LinuxBoot This changes the ME Region Limit to fit the actual content as described in the ME partitions. Also update the BIOS Region Base to start just after the ME Region

func (*TightenME) Run

func (v *TightenME) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*TightenME) Visit

func (v *TightenME) Visit(f uefi.Firmware) error

Visit applies the TightenME visitor to any Firmware type.

type Validate

type Validate struct {
	// An optional Writer for writing errors when validation is complete.
	// When the writer it set, Run will also call os.Exit(1) upon finding
	// an error.
	W io.Writer

	// List of validation errors.
	Errors []error
}

Validate performs extra checks on the firmware image.

func (*Validate) Run

func (v *Validate) Run(f uefi.Firmware) error

Run wraps Visit and performs some setup and teardown tasks.

func (*Validate) Visit

func (v *Validate) Visit(f uefi.Firmware) error

Visit applies the Validate visitor to any Firmware type.

Jump to

Keyboard shortcuts

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