goartifacts

Documentation

Overview

Package goartifacts provides functions for parsing and validating forensic artifact definition files.

Index

• Variables
• func IsOSArtifactDefinition(os string, supportedOs []string) bool
• type ArtifactCollector
• type ArtifactDefinition
  • func DecodeFile(filename string) ([]ArtifactDefinition, []string, error)
  • func DecodeFiles(filenames []string) ([]ArtifactDefinition, error)
  • func FilterName(names []string, artifactDefinitions []ArtifactDefinition) []ArtifactDefinition
  • func FilterOS(artifactDefinitions []ArtifactDefinition) []ArtifactDefinition
• type Attributes
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (dec *Decoder) Decode() ([]ArtifactDefinition, error)
  • func (dec *Decoder) SetStrict(s bool)
• type KeyValuePair
• type Provide
• type Source
  • func ExpandSource(source Source, collector ArtifactCollector) Source

Variables

var SourceType = struct {
	ArtifactGroup string
	Command       string
	Directory     string
	File          string
	Path          string
	RegistryKey   string
	RegistryValue string
	Wmi           string
}{
	ArtifactGroup: "ARTIFACT_GROUP",
	Command:       "COMMAND",
	Directory:     "DIRECTORY",
	File:          "FILE",
	Path:          "PATH",
	RegistryKey:   "REGISTRY_KEY",
	RegistryValue: "REGISTRY_VALUE",
	Wmi:           "WMI",
}

SourceType is an enumeration of artifact definition source types.

Functions

func IsOSArtifactDefinition

func IsOSArtifactDefinition(os string, supportedOs []string) bool

Types

type ArtifactCollector

type ArtifactCollector interface {
	Resolve(parameter string) ([]string, error)
	Collect(name string, source Source)

	FS() fs.FS
	Registry() fs.FS
	Prefixes() []string
}

ArtifactCollector is an interface that can resolve parameters in artifact defintions and collect artifacts.

type ArtifactDefinition

type ArtifactDefinition struct {
	Name        string   `yaml:"name,omitempty"`
	Doc         string   `yaml:"doc,omitempty"`
	Sources     []Source `yaml:"sources,omitempty"`
	Conditions  []string `yaml:"conditions,omitempty"`
	Provides    []string `yaml:"provides,omitempty"`
	Labels      []string `yaml:"labels,omitempty"`
	SupportedOs []string `yaml:"supported_os,omitempty"`
	Urls        []string `yaml:"urls,omitempty"`
}

The ArtifactDefinition describes an object of digital archaeological interest.

func DecodeFile

func DecodeFile(filename string) ([]ArtifactDefinition, []string, error)

DecodeFile takes a single artifact definition file to decode.

func DecodeFiles

func DecodeFiles(filenames []string) ([]ArtifactDefinition, error)

DecodeFiles takes a list of artifact definition files. Those files are decoded, validated, filtered and expanded.

func FilterName

func FilterName(names []string, artifactDefinitions []ArtifactDefinition) []ArtifactDefinition

FilterName return a list of ArtifactDefinitions which match the provided names.

func FilterOS

func FilterOS(artifactDefinitions []ArtifactDefinition) []ArtifactDefinition

FilterOS returns a list of ArtifactDefinitions for the current operating system.

type Attributes

type Attributes struct {
	Names         []string       `yaml:"names,omitempty"`
	Paths         []string       `yaml:"paths,omitempty"`
	Separator     string         `yaml:"separator,omitempty"`
	Cmd           string         `yaml:"cmd,omitempty"`
	Args          []string       `yaml:"args,omitempty"`
	Keys          []string       `yaml:"keys,omitempty"`
	Query         string         `yaml:"query,omitempty"`
	BaseObject    string         `yaml:"base_object,omitempty"`
	KeyValuePairs []KeyValuePair `yaml:"key_value_pairs,omitempty"`
}

Attributes are specific to the type of source definition. They contain information.

type Decoder

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

A Decoder reads and decodes YAML values from an input stream.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder returns a new decoder that reads from r.

The decoder introduces its own buffering and may read data from r beyond the YAML values requested.

func (*Decoder) Decode

func (dec *Decoder) Decode() ([]ArtifactDefinition, error)

Decode reads the next YAML-encoded value from its input and stores it in the value pointed to by v.

func (*Decoder) SetStrict

func (dec *Decoder) SetStrict(s bool)

type KeyValuePair

type KeyValuePair struct {
	Key   string `yaml:"key,omitempty"`
	Value string `yaml:"value,omitempty"`
}

A KeyValuePair represents Windows Registry key path and value name that can potentially be collected.

type Provide

type Provide struct {
	Key    string `yaml:"key,omitempty"`
	Regex  string `yaml:"regex,omitempty"`
	WMIKey string `yaml:"wmi_key,omitempty"`
}

Provide defines a knowledge base entry that can be created using this source.

type Source

type Source struct {
	Type        string     `yaml:"type,omitempty"`
	Attributes  Attributes `yaml:"attributes,omitempty"`
	Conditions  []string   `yaml:"conditions,omitempty"`
	SupportedOs []string   `yaml:"supported_os,omitempty"`
	Provides    []Provide  `yaml:"provides,omitempty"`
}

The Source type objects define the source of the artifact data. Currently the following source types are defined:

• artifact; the source is one or more artifact definitions;
• file; the source is one or more files;
• path; the source is one or more paths;
• directory; the source is one or more directories;
• Windows Registry key; the source is one or more Windows Registry keys;
• Windows Registry value; the source is one or more Windows Registry values;
• WMI query; the source is a Windows Management Instrumentation query.

The difference between the file and path source types are that file should be used to define file entries that contain data and path, file entries that define a location. E.g. on Windows %SystemRoot% could be considered a path artifact definition, pointing to a location e.g. C:\\Windows. And where C:\\Windows\\System32\\winevt\\Logs\\AppEvent.evt a file artifact definition, pointing to the Application Event Log file.

func ExpandSource

func ExpandSource(source Source, collector ArtifactCollector) Source

ExpandSource expands a single artifact definition source by expanding its paths or keys.