artifact

Documentation

Overview

Package artifact reads UAC artifact definition files.

These files look like YAML but are not: UAC parses them with hand-rolled shell in lib/parse_artifact.sh, so they contain things no YAML library will accept -- bare scalars starting with '%' (path: %user_home%/.ssh), unquoted command values containing ": ", literal tabs inside descriptions. Rather than pre-mangling them into valid YAML and hoping the mangling is faithful, this parser accepts the dialect UAC actually uses.

Index

• type Doc
  • func LoadDir(root string) ([]*Doc, map[string]error)
  • func LoadFS(fsys fs.FS) ([]*Doc, map[string]error)
  • func Parse(r io.Reader, source string) (*Doc, error)
  • func ParseFile(path, source string) (*Doc, error)
• type Entry
  • func (e Entry) ID() string

Types

type Doc

type Doc struct {
	Source          string // path the document was read from
	Version         string
	OutputDirectory string
	Condition       string
	Artifacts       []Entry
}

Doc is one artifact file: some document-level keys plus a list of entries.

func LoadDir

func LoadDir(root string) ([]*Doc, map[string]error)

LoadDir reads every *.yaml under a directory on disk.

func LoadFS

func LoadFS(fsys fs.FS) ([]*Doc, map[string]error)

LoadFS reads every *.yaml in fsys, returning documents keyed by their path within it. Parse failures are returned per file rather than aborting the load, so one malformed artifact cannot take down a whole collection.

Taking an fs.FS rather than a path is what lets the embedded corpus and a real UAC checkout run through exactly the same code: os.DirFS for one, the unpacked archive for the other.

func Parse

func Parse(r io.Reader, source string) (*Doc, error)

Parse reads the artifact dialect from r. source names the document for error messages and rule ids.

func ParseFile

func ParseFile(path, source string) (*Doc, error)

ParseFile reads one artifact file from disk.

type Entry

type Entry struct {
	Source string // "files/system/etc.yaml"
	Index  int    // position within the file, for stable rule ids

	Description string
	SupportedOS []string
	Collector   string
	Condition   string

	Path               []string // may name several paths, shell-split
	PathPattern        []string
	NamePattern        []string
	ExcludePathPattern []string
	ExcludeNamePattern []string
	ExcludeFileSystem  []string
	FileType           []string
	Permissions        []string

	MaxDepth    int
	HasMaxDepth bool

	MinFileSize    int64
	HasMinFileSize bool
	MaxFileSize    int64
	HasMaxFileSize bool

	NoUser          bool
	NoGroup         bool
	IgnoreDateRange bool
	IsFileList      bool

	Command         string
	OutputFile      string
	OutputDirectory string

	ExcludeNologinUsers bool
	Foreach             string

	Extra map[string]string
}

Entry is a single artifact definition. Unknown keys are kept in Extra rather than dropped, so a newer artifact file does not silently lose meaning.

func (Entry) ID

func (e Entry) ID() string

ID is a stable identifier used for rule names and spool file names.