correlate

Documentation

Overview

Package correlate raises agent-reported/observed activity to corroborated (or contradicted) by comparing it against independent endpoint evidence (plan §16). External evidence enters through the Adapter interface, so new sources (EDR exports, DNS logs, process telemetry, MCP-gateway logs) plug in without touching the core.

Correlation NEVER invents evidence: an event is only upgraded when an adapter yields an independent observation that matches it. Absence of endpoint evidence leaves the state UNKNOWN, never CONTRADICTED.

Index

• type Adapter
• type Observation
• type Result
  • func Apply(events []schema.Event, adapters ...Adapter) (*Result, error)
• type ShellHistoryAdapter
  • func (s *ShellHistoryAdapter) Name() string
  • func (s *ShellHistoryAdapter) Observations() ([]Observation, error)

Types

type Adapter

type Adapter interface {
	Name() string
	Observations() ([]Observation, error)
}

Adapter yields independent endpoint observations. Implementations must treat their input as hostile (bounded reads, no execution).

type Observation

type Observation struct {
	Source string // adapter name, e.g. "shell_history"
	Kind   string // "command" | "network" | "process" | "dns"
	Value  string // normalized value (e.g. the command line)
	Ref    string // evidence reference (file:line or export id)
}

Observation is one independent endpoint fact from an external source.

type Result

type Result struct {
	Corroborated int
	Sources      []string
	Notes        []string
}

Result summarizes a correlation pass.

func Apply

func Apply(events []schema.Event, adapters ...Adapter) (*Result, error)

Apply correlates events in place against all adapters. Tool-call events with a command are matched against endpoint "command" observations; a match upgrades OBSERVED -> CORROBORATED and records the corroborating source on the event summary (evidence-linked).

type ShellHistoryAdapter

type ShellHistoryAdapter struct {
	Path string
}

ShellHistoryAdapter reads a shell history file (bash/zsh) as an independent endpoint evidence source. Commands an agent reported running should also appear here if they actually executed in an interactive-ish shell context.

Hostile input: bounded line size, no execution, values sanitized by downstream display. This is a reference adapter demonstrating the external-evidence extension point (plan §16).

func (*ShellHistoryAdapter) Name

func (s *ShellHistoryAdapter) Name() string

func (*ShellHistoryAdapter) Observations

func (s *ShellHistoryAdapter) Observations() ([]Observation, error)