analysis

Documentation

Overview

Package analysis is the one place a package gets analyzed. It runs the stages in the right order — normalize (only when needed), endpoint correlation, detections, rule packs, MCP audit, provenance — and writes one consistent set of results under <pkg>/detections/. Every command that shows or exports results (analyze/triage, serve, investigate, report) goes through here, so nothing is ever "not run yet" and later stages never clobber earlier ones.

Index

• func LoadEntities(pkg string) []schema.Entity
• func LoadEvents(pkg string) []schema.Event
• func LoadFindings(pkg string) []schema.Finding
• func Stale(pkg string) bool
• type Options
• type Result
  • func Ensure(pkg string, log io.Writer) (*Result, error)
  • func Run(pkg string, o Options) (*Result, error)

Functions

func LoadEntities

func LoadEntities(pkg string) []schema.Entity

LoadEntities reads the overlay entities.

func LoadEvents

func LoadEvents(pkg string) []schema.Event

LoadEvents reads the overlay into memory (for stages that need it).

func LoadFindings

func LoadFindings(pkg string) []schema.Finding

LoadFindings reads the persisted findings.

func Stale

func Stale(pkg string) bool

Stale reports whether results need (re)computing: no overlay, no findings, or the package was sealed after the overlay was written.

Types

type Options

type Options struct {
	EndpointLogs   []string // auditd / Sysmon XML / JSONL-CSV exports (second witness)
	EndpointFormat endpoint.Format
	Window         time.Duration
	ShellHistory   string
	GatewayLog     string
	GatewayMap     string
	GatewayServers []string
	RulesDir       string
	Honeytokens    []string
	SpawnThreshold int
	KnownDests     []string
	Renormalize    bool      // force re-parse even if the overlay is current
	Log            io.Writer // progress lines; nil = silent
}

Options are the optional inputs an analyst may add.

type Result

type Result struct {
	Events       int
	Entities     int
	Renormalized bool
	Findings     []schema.Finding
	Correlation  *correlate.EndpointResult
	MCPServers   int
	Provenance   int // instruction files attributed
	StageNotes   []string
}

Result summarizes one run.

func Ensure

func Ensure(pkg string, log io.Writer) (*Result, error)

Ensure runs a default analysis only when results are missing or stale.

func Run

func Run(pkg string, o Options) (*Result, error)

Run executes every stage and persists results.