collector

Documentation

Overview

Package collector defines the collector contract and the four offline collectors UAC supports: file, find, stat and hash.

The exported interface is deliberately narrow, because collectors are meant to be pluggable and some will come from outside this repository:

InspectFile(path string) error
ScanResults() (any, error)

InspectFile takes a path, not a stat buffer, but no collector ever calls stat itself. The walker resolves each path exactly once and primes a single-entry cache before dispatching; because every collector is called for the same path consecutively, that cache has a perfect hit rate. Without it, 479 compiled rules would mean 479 stat calls per file.

Index

• type Collector
  • func New(r *rules.Rule, ctx *Context) (Collector, error)
• type Context
  • func (c *Context) AddToList(key, path string)
  • func (c *Context) List(key string) []string
  • func (c *Context) RecordError(path, stage string, err error)
  • func (c *Context) RecordedErrors() int64
• type Finisher
• type Flusher
• type Pruner
• type Result

Types

type Collector

type Collector interface {
	// InspectFile examines one path and records whatever it finds. A returned
	// error means the collector itself is broken -- its spool file cannot be
	// written, the output disk is full -- and the scan should stop. Problems
	// with the *file* (unreadable, vanished, bad sector) are recorded as
	// results and must not be returned: unreadable files are routine on real
	// images, and one of them must never abort a multi-hour acquisition.
	InspectFile(path string) error

	// ScanResults returns this collector's results. Implementations return a
	// stream that reads from disk, never a materialised slice.
	ScanResults() (any, error)
}

Collector is the contract every collector satisfies.

func New

func New(r *rules.Rule, ctx *Context) (Collector, error)

New builds the collector for one compiled rule.

type Context

type Context struct {
	// Cache is the single-entry stat memo the walker primes.
	Cache *fsref.Cache
	// Broker opens a matched file once and shares it with all consumers.
	Broker *content.Broker
	// Store owns the output tree.
	Store *spool.Store
	// Env carries the date range and the image's account database.
	Env *rules.Env
	// OutputRoot is where collected file bytes are written.
	OutputRoot string
	// contains filtered or unexported fields
}

Context is the machinery shared by every collector in one scan.

func (*Context) AddToList

func (c *Context) AddToList(key, path string)

AddToList records a path discovered by a list-producing rule.

func (*Context) List

func (c *Context) List(key string) []string

List returns the paths recorded under a key, sorted so the output does not depend on the order files happened to be visited in.

func (*Context) RecordError

func (c *Context) RecordError(path, stage string, err error)

RecordError writes a per-file problem to the errors spool. It deliberately returns nothing: callers must not treat a bad file as a reason to stop.

The count is kept so the run can report how many problems it papered over. An acquisition that quietly skipped ten thousand files is not the same as a clean one, and the difference has to be visible without reading the spool.

func (*Context) RecordedErrors

func (c *Context) RecordedErrors() int64

RecordedErrors returns how many per-file problems were recorded.

type Finisher

type Finisher interface {
	Finish() error
}

Finisher is an optional interface for collectors whose work cannot happen during the walk. The walker calls Finish once, after the traversal, which is what makes the two-phase artifacts possible: a shell history file named inside an rc file is not knowable until that rc file has been read.

type Flusher

type Flusher interface {
	Flush() error
}

Flusher is an optional interface for collectors with buffered or deferred work. The walker calls it before ScanResults is valid.

type Pruner

type Pruner interface {
	ShouldSkipDir(path string) bool
}

Pruner is an optional interface. A push-only collector cannot tell the walker to skip a subtree, and pruning is what keeps exclusions cheap, so collectors that know a directory is irrelevant may say so. The walker skips a directory only when every collector agrees.

type Result

type Result struct {
	Collector string
	Line      string
}

Result is the streamed record type shared by the line-oriented collectors.