auditlog

package
v0.6.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// CapabilitySep separates HMAC capability fields.
	CapabilitySep = "|"
	// DefaultCapabilityTTL bounds how long a worker may emit egress events
	// with a given capability without refresh.
	DefaultCapabilityTTL = 24 * time.Hour
)
View Source
const (
	// KindRetentionCheckpoint is the immutable record retention inserts
	// where it dropped a prefix: its PrevHash is the last dropped EventHash,
	// and WitnessedThrough (when set) names the last externally witnessed
	// head the prefix carried.
	KindRetentionCheckpoint = "retention_checkpoint"
	// KindRetentionRedacted is what retention leaves of an expired record
	// it cannot cut out of the chain: its two link hashes and nothing that
	// says who opened what. See RedactForRetention.
	KindRetentionRedacted = "retention_redacted"

	// MaxLineBytes bounds one JSONL record during chain scans; audit lines
	// are metadata-only, so anything larger is corruption, not evidence.
	MaxLineBytes = 1024 * 1024
)
View Source
const (
	IndexKindOther byte = iota
	IndexKindSecretOpen
	IndexKindEgress
	IndexKindGap
	IndexKindRetentionCheckpoint
)

Index kind classes. Only decisive exclusions may use them: a filter for "egress" skips IndexKindSecretOpen entries but must still read IndexKindOther and IndexKindGap ones and decide on the record itself.

View Source
const (
	// KindAPI is one API call, an SSH session open, or a destructive action
	// the daemon took on its own (lifecycle, reconcile).
	KindAPI = "api"
	// KindAuthDenied is a refused credential (a 401), at most one per
	// source address per minute; Dropped counts the 401s from that address
	// the limit folded into it.
	KindAuthDenied = "auth_denied"
	// KindAPIFloodMode records a change of the node's effective flood
	// control mode: a coalesce-only node that gained a second owner now
	// budgets too, and the switch is part of the evidence.
	KindAPIFloodMode = "api_flood_mode"
)

Record kinds this file adds. Each one is hash-covered and unknown to a binary older than the release that writes it, so writers emit them only behind the same cluster gate as Caller.

View Source
const (
	APIResultOK     = "ok"
	APIResultDenied = "denied"
	APIResultError  = "error"
)

Result values of an api record. A 403 is "denied" (who tried what they may not do); any other 4xx or 5xx is "error".

View Source
const (
	// SurfaceMCP is a remote MCP tool's inner API call.
	SurfaceMCP = "mcp"
	// SurfaceSSH is an SSH session opened through the gateway.
	SurfaceSSH = "ssh"
)

Surfaces a call can arrive through besides a direct API request.

View Source
const (
	// LockFileName is the stable flock sidecar for the whole audit
	// directory. It carries no data; every writer, reader, drain and
	// retention pass takes it, so the file must never be renamed.
	LockFileName = "secrets.jsonl.lock"
	// SpillFileName is the overflow buffer the daemon's writer drains.
	SpillFileName = "secrets.spill.jsonl"
)
View Source
const GenesisPrevHash = "0"

GenesisPrevHash is the prev_hash of the first event in a chain.

View Source
const KindIdentityConfig = "identity_config"

KindIdentityConfig is the record a node writes when the identity file it enforces changes, at reload or at boot (D20).

View Source
const ReasonRateLimited = "rate_limited"

ReasonRateLimited marks the record that stands for calls the flood budget did not write one by one: Dropped is how many, Request.Routes which routes they hit, Caller who made them.

View Source
const RefSSH = "ssh"

RefSSH is the ref of an SSH session-open record.

Variables

View Source
var ErrIndexEntriesCorrupt = errors.New("audit index entries are corrupt")

ErrIndexEntriesCorrupt reports a posting list that does not decode. The index is derived data; the caller rebuilds it from the JSONL.

View Source
var ErrNoSpillPath = errors.New("audit spill path is unset")

ErrNoSpillPath reports a SpillFile with no destination.

Functions

func APIResultForStatus added in v0.6.8

func APIResultForStatus(status int) string

APIResultForStatus maps an HTTP status onto an api record's result.

func ContextWithCorrelationID added in v0.6.8

func ContextWithCorrelationID(ctx context.Context, id string) context.Context

ContextWithCorrelationID returns ctx carrying id. An empty id is a no-op, so a caller can pass a header value through without checking it.

func ContextWithSSHGatewayCall added in v0.6.9

func ContextWithSSHGatewayCall(ctx context.Context, c SSHGatewayCall) context.Context

ContextWithSSHGatewayCall marks ctx as a call the SSH gateway bridged. Only the API edge sets it, after checking the call's origin.

func ContextWithSurface added in v0.6.8

func ContextWithSurface(ctx context.Context, surface string) context.Context

ContextWithSurface marks ctx as a call that arrived through surface (SurfaceMCP). Only in-process code sets it; nothing on the wire can.

func CorrelationIDFromContext added in v0.6.8

func CorrelationIDFromContext(ctx context.Context) string

CorrelationIDFromContext returns the id ContextWithCorrelationID attached, or "".

func EnsureEventID

func EnsureEventID(ev *Event)

EnsureEventID assigns an ID exactly once.

func HashEvent

func HashEvent(prevHash string, ev Event) string

HashEvent returns SHA-256 hex of prevHash || canonical JSON of ev with EventHash cleared (so the hash does not depend on itself).

func LinkEvent

func LinkEvent(prevHash string, ev *Event)

LinkEvent sets PrevHash/EventHash on ev given the previous tip hash.

func LocalIncarnationID

func LocalIncarnationID(sandboxID, toolboxToken string) string

LocalIncarnationID derives a stable, non-secret lifecycle identifier from the per-create toolbox token. The token is regenerated whenever a sandbox ID is reused, so stale worker capabilities cannot cross into a replacement lifecycle. Only the digest is retained in audit ACL/event records.

func MarkForwardFailed added in v0.6.8

func MarkForwardFailed(ctx context.Context)

MarkForwardFailed records that the forward itself failed (the edge answered 502 without reaching the peer), so the edge records the call after all: no peer ever saw it.

func MarkForwarded added in v0.6.8

func MarkForwarded(ctx context.Context)

MarkForwarded records that the request was handed to a peer, which runs the handler and writes the record; the edge then writes none (§5.9, "Forwarding"). cluster.StampForward calls it on every forward path.

func MintEgressCapability

func MintEgressCapability(key, sandboxID, incarnationID string, expiry time.Time) (string, error)

MintEgressCapability returns HMAC(sandboxID|incarnationID|expiry, key) hex-encoded as sandboxID|incarnationID|expiryUnix|mac. key is typically SB_AUDIT_INGEST_TOKEN (or a derived key). The mac binds the sandbox so a stolen capability for one sandbox cannot forge another sandbox's events.

func NewCorrelationID added in v0.6.8

func NewCorrelationID() string

NewCorrelationID returns a fresh id: the wall clock, so ids sort roughly by time in a log, plus 64 random bits. If the entropy source fails the clock alone still yields a usable, if not unique, id: losing correlation must never cost a record.

func NewEventID

func NewEventID(nodeID string) string

NewEventID returns a fleet-unique audit event identifier. The normal path is 128 bits from crypto/rand. The fallback includes node, wall clock, process, and a process-local sequence so audit emission remains available even if the host entropy source fails.

func NoteCreatedToken added in v0.6.8

func NoteCreatedToken(ctx context.Context, id, role, team string)

NoteCreatedToken records the token a token create minted: its id as the record's target and the role and team it carries as the record's grant.

func NoteSandbox added in v0.6.8

func NoteSandbox(ctx context.Context, sandboxID string)

NoteSandbox records the sandbox a call acted on when the route's path does not carry it (a Daytona name resolved to its id).

func NoteSandboxIdentity added in v0.6.8

func NoteSandboxIdentity(ctx context.Context, sandboxID, incarnationID, ownerRef string)

NoteSandboxIdentity is NoteSandbox with the sandbox's lifecycle and owner, when the caller already holds them: a create learns its new id here, so the create record names the sandbox (the creator is found through it) and stamping it needs no lookup.

func NoteTarget added in v0.6.8

func NoteTarget(ctx context.Context, target string)

NoteTarget records the object a call created when the route's path does not name it (token create records the new token id, §5.9).

func ParseAndVerifyEgressCapability

func ParseAndVerifyEgressCapability(key, capability string, now time.Time) (sandboxID, incarnationID string, err error)

ParseAndVerifyEgressCapability checks the HMAC and expiry. On success it returns the bound sandboxID and incarnationID (never trust client body for those fields when a capability is present).

func ReadLine added in v0.6.7

func ReadLine(br *bufio.Reader, max int64) (line []byte, consumed int64, terminated, tooLong bool, err error)

ReadLine returns one line (terminator included when present) and the bytes consumed. A line past max is counted but not retained so a NUL-filled or runaway tail cannot balloon the scan. max <= 0 means MaxLineBytes; the daemon's spill drain passes its ingest body cap so a worker cannot plant a line that fails strict boot.

func SurfaceFromContext added in v0.6.8

func SurfaceFromContext(ctx context.Context) string

SurfaceFromContext returns the surface ContextWithSurface attached, or "".

func WithFileLock

func WithFileLock(lockPath string, fn func() error) error

WithFileLock runs fn holding an exclusive flock on lockPath. The sidecar is opened read-only: it only needs a stable descriptor, and a read-only open cannot hide a buffered-write failure on close.

Types

type CallState added in v0.6.8

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

CallState is what one API request's record learns while the request runs: whether a forward path handed the call to a peer (which records it instead), and the sandbox or object the call turned out to act on when the route's path does not name it (a create learns its new sandbox id). The API edge attaches one per recorded request; everything below the edge only marks it, through the helpers below, never reads it.

func CallStateFromContext added in v0.6.8

func CallStateFromContext(ctx context.Context) *CallState

CallStateFromContext returns the CallState ctx carries, or nil.

func ContextWithCallState added in v0.6.8

func ContextWithCallState(ctx context.Context) (context.Context, *CallState)

ContextWithCallState returns ctx carrying a fresh CallState. A nested request (a remote MCP tool's inner call) gets its own, so marking one never touches the other.

func (*CallState) ForwardFailed added in v0.6.8

func (s *CallState) ForwardFailed() bool

ForwardFailed reports whether that forward failed before reaching the peer.

func (*CallState) Forwarded added in v0.6.8

func (s *CallState) Forwarded() bool

Forwarded reports whether a forward path handed the call to a peer.

func (*CallState) Grant added in v0.6.8

func (s *CallState) Grant() *Grant

Grant is the grant NoteCreatedToken recorded, or nil.

func (*CallState) SandboxID added in v0.6.8

func (s *CallState) SandboxID() string

SandboxID is the sandbox NoteSandbox recorded, or "".

func (*CallState) SandboxIdentity added in v0.6.8

func (s *CallState) SandboxIdentity() (sandboxID, incarnationID, ownerRef string)

SandboxIdentity is the sandbox NoteSandboxIdentity recorded and, when it was given, its lifecycle and owner.

func (*CallState) Target added in v0.6.8

func (s *CallState) Target() string

Target is the object NoteTarget recorded, or "".

type Caller added in v0.6.8

type Caller struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name,omitempty"`
	Team string `json:"team,omitempty"`
	Via  string `json:"via,omitempty"`
}

Caller names who made the request behind a record, or which daemon subsystem acted when no request did. Kind and ID are the principal (controlplane.Principal: "operator", "node:n3", "tok_…", "oidc:…", "controlplane:…", "system:reconcile"); Name is the display name when it adds something to ID (an email, a token name); Team is the team a team-bound credential acted for; Via is the edge node that forwarded the request to the node that wrote the record, taken from the verified mTLS peer, never from a header. Field order is part of the hash: append only.

type ChainScan added in v0.6.7

type ChainScan struct {
	Head    string
	EventID string
	// LastLineStart is the offset of the record carrying Head.
	LastLineStart int64
	// Found reports which probed hashes the pass saw.
	Found map[string]bool
	// WitnessedThrough is the newest retention checkpoint's WitnessedThrough.
	WitnessedThrough string
	// ValidEnd is the byte offset just past the last complete, verified line.
	ValidEnd int64
	// TornBytes is the length of an unterminated, unparseable tail after
	// ValidEnd — what a crash leaves when it interrupts one append write. The
	// writer emits line+'\n' in a single write, so a crash leaves a strict
	// byte-prefix, and no proper prefix of a JSON object is itself valid JSON;
	// that is what makes this the only defect safe to classify as a tear.
	// ScanChain reports a tear rather than failing on it so the daemon's
	// boot repair can cut it back; every other reader must treat a non-zero
	// value as a chain it cannot verify, never quietly trim evidence.
	TornBytes int64
	// MissingNewline reports a complete, verified final record without its
	// terminator (the write stopped exactly between '}' and '\n').
	MissingNewline bool
	// Records counts verified records (blank lines excluded).
	Records int64
	// Redacted counts retention stubs among them: records whose payload
	// retention removed in place. The node never produces one inside the
	// retention window.
	Redacted int64
}

ChainScan is one verified pass over an audit JSONL stream.

func ScanChain added in v0.6.7

func ScanChain(r io.Reader, opts ScanOptions) (ChainScan, error)

ScanChain walks r once, verifying every record against its predecessor. Blank lines are tolerated but never alter the chain. r should be already bounded (a size snapshot taken under the audit flock) so a verification can run while the writer keeps appending. Memory is O(1) in the number of records.

type ChainVerifier added in v0.6.7

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

ChainVerifier checks one chain in stream order with O(1) state: the head so far, whether the next link may break (right after a retention checkpoint), and whether any record has been seen. The zero value is not ready; start from NewChainVerifier, or ResumeChainVerifier to continue a chain someone already verified up to a known head.

func NewChainVerifier added in v0.6.7

func NewChainVerifier() ChainVerifier

NewChainVerifier starts a verifier at genesis. It is a value so a caller can hand a copy to ScanChain and keep its own state unchanged.

func ResumeChainVerifier added in v0.6.7

func ResumeChainVerifier(head string, allowBreak bool) ChainVerifier

ResumeChainVerifier primes a verifier mid-chain: head is the EventHash of the last record already verified, and allowBreak is whether that record was a retention checkpoint (whose successor may name a dropped predecessor). Checkpoint boot, the export tailer and the read index all carry exactly this state across passes instead of re-reading the prefix, and a resumed verifier refuses a later retention checkpoint just as one that read the prefix itself would.

func (*ChainVerifier) Add added in v0.6.7

func (v *ChainVerifier) Add(ev Event) error

Add validates one immutable event in stream order. The only permitted link discontinuity is the first retained event after a retention checkpoint, whose predecessor was deliberately removed. Missing hash fields are never interpreted as a legacy format: this audit format is intentionally one-way.

func (*ChainVerifier) AllowBreak added in v0.6.7

func (v *ChainVerifier) AllowBreak() bool

AllowBreak reports whether the next record may name a predecessor other than Head — true only right after a retention checkpoint. Callers persist it alongside Head so a resumed pass keeps the same rule.

func (*ChainVerifier) Head added in v0.6.7

func (v *ChainVerifier) Head() string

Head is the EventHash of the last accepted record, or GenesisPrevHash when none has been accepted yet: what the next record's prev_hash must name.

type Event

type Event struct {
	Time          time.Time `json:"time"`
	Actor         string    `json:"actor,omitempty"`
	SandboxID     string    `json:"sandbox_id,omitempty"`
	Ref           string    `json:"ref,omitempty"`
	Result        string    `json:"result"`
	Reason        string    `json:"reason,omitempty"`
	CorrelationID string    `json:"correlation_id,omitempty"`
	EventID       string    `json:"event_id,omitempty"`
	NodeID        string    `json:"node_id,omitempty"`
	Kind          string    `json:"kind,omitempty"`
	Destination   string    `json:"destination,omitempty"`
	Network       string    `json:"network,omitempty"`
	BytesIn       int64     `json:"bytes_in,omitempty"`
	BytesOut      int64     `json:"bytes_out,omitempty"`
	// IncarnationID scopes the event to a placement incarnation so post-delete
	// ACL and recreate history do not cross tenant ownership boundaries.
	IncarnationID string `json:"incarnation_id,omitempty"`
	// OwnerRef is the tenant account the sandbox belonged to when the event
	// was recorded. It makes an exported record self-describing downstream
	// and lets a node authorize a post-delete read from the evidence itself,
	// without consulting Raft. Empty for operator-owned sandboxes. Being
	// omitempty, records written before the field existed hash identically.
	OwnerRef string `json:"owner_ref,omitempty"`
	// Dropped is set on gap markers to record how many events were coalesced
	// into this single overflow marker (lossy buffer evidence).
	Dropped int64 `json:"dropped,omitempty"`
	// PrevHash / EventHash form the local append-only hash chain used for
	// tamper detection once heads are witnessed off-node (E2b).
	PrevHash  string `json:"prev_hash,omitempty"`
	EventHash string `json:"event_hash,omitempty"`
	// WitnessedThrough is set on retention_checkpoint records to record the
	// last externally witnessed head that prune dropped (optional MVP field).
	WitnessedThrough string `json:"witnessed_through,omitempty"`
	// Caller is who caused the record (plans/identity-and-access.md §5.8).
	// It stays LAST and omitempty: the hash covers json.Marshal of this
	// struct in field order, so moving it, or writing it without omitempty,
	// would change the hash of every record written before it existed. A nil
	// pointer is omitted, so those records re-marshal byte for byte and
	// still verify. A binary that predates the field drops it on decode and
	// computes a different hash, which is why writers gate it on every
	// cluster member advertising support (internal/cluster's audit caller
	// gate) and why rolling back below the release that writes it fails
	// strict boot verification.
	Caller *Caller `json:"caller,omitempty"`
	// Request describes the API call behind a kind "api" record (§5.9).
	// Same rules as Caller, for the same reason: appended after it, a nil
	// pointer omitted so every record written before it existed re-marshals
	// byte for byte, never reordered, and written only behind the same
	// cluster gate.
	Request *Request `json:"request,omitempty"`
	// IdentityConfig is set only on an identity_config record: what an
	// identity-file change did to who can sign in and with which role
	// (plans/identity-and-access.md §5.5, CEO review D20). Appended after
	// Request and omitempty for the same reason Caller is: every older record
	// re-marshals byte for byte. Its record kind is behind the same cluster
	// write gate as Caller.
	IdentityConfig *IdentityConfig `json:"identity_config,omitempty"`
}

Event is the shared JSONL/wire representation for secret-open and egress audit records. Keeping the daemon, peer transport, and WASM worker on this single shape prevents fields that affect pagination from drifting.

func GapMarker

func GapMarker(node string, dropped int64, now time.Time) Event

GapMarker is the record that stands in for dropped events: one marker per flush, carrying the count, so overflow costs the writer one line rather than one per drop and the stream stays honest about the loss.

func RedactForRetention added in v0.6.7

func RedactForRetention(ev Event) Event

RedactForRetention is what retention leaves of an expired record that sits behind a newer one and so cannot be cut out of the chain: the two link hashes, the time and id (so a later prune reclaims it with the prefix and an operator can place it), and nothing that says who opened what. EventHash is the original — it is what the successor's prev_hash names — so the chain still verifies through the stub; the verifier links a stub by its stored hashes because the payload that produced them is gone, and refuses one that still carries any other field.

type ExportSource added in v0.6.7

type ExportSource interface {
	// Days lists the UTC dates ("2006-01-02") holding batches for nodeID,
	// ascending, starting at from.
	Days(ctx context.Context, nodeID, from string) ([]string, error)
	// Batches lists one day's batch names.
	Batches(ctx context.Context, nodeID, day string) ([]string, error)
	// Open reads one batch: one JSON event per line.
	Open(ctx context.Context, nodeID, day, batch string) (io.ReadCloser, error)
}

ExportSource reads a node's exported batches in the export layout: node=<id>/YYYY/MM/DD/<batch>.jsonl. Batch names are never used for order; the walk follows the chain itself.

type Grant added in v0.6.8

type Grant struct {
	Role string `json:"role"`
	Team string `json:"team"`
}

Grant is what a credential-minting call handed out. Field order is part of the hash: append only.

type IdentityConfig added in v0.6.8

type IdentityConfig struct {
	// OldHash is empty for the first file this node ever recorded.
	OldHash string `json:"old_hash,omitempty"`
	NewHash string `json:"new_hash"`
	// BindingsAdded and BindingsRemoved diff the binding lists as sets.
	// Bindings are first-match, so a pure reorder changes who gets which
	// role without adding or removing a line: Reordered says so.
	BindingsAdded   []string `json:"bindings_added,omitempty"`
	BindingsRemoved []string `json:"bindings_removed,omitempty"`
	Reordered       bool     `json:"reordered,omitempty"`
	DenyAdded       []string `json:"deny_added,omitempty"`
	DenyRemoved     []string `json:"deny_removed,omitempty"`
	IssuersAdded    []string `json:"issuers_added,omitempty"`
	IssuersRemoved  []string `json:"issuers_removed,omitempty"`
	// Omitted counts diff lines left out to keep the record far below the
	// audit line cap (MaxLineBytes); the hashes still identify both files.
	Omitted int `json:"omitted,omitempty"`
}

IdentityConfig is an identity-file change as evidence. The file cannot say who edited it; the hashes point at the exact file versions, and the operator's own config history (git, Ansible) names the author. The lists hold canonical one-line forms, never secrets: issuers ("name url audiences=…"), bindings ("okta group=platform-admins -> admin/*") and deny-list subjects ("okta:00u1ab"). Field order is part of the hash: append only.

type IndexEntry

type IndexEntry struct {
	Offset   int64 // first byte of the record
	Length   int64 // bytes through the trailing newline
	TimeNano int64 // Event.Time as UnixNano
	Kind     byte  // IndexKind*; anything unclassified is IndexKindOther
}

IndexEntry locates one record inside the local audit JSONL and carries just enough of it to page and filter without touching the file: the read path decides which lines a page needs from entries alone, then reads only those lines. Offsets are byte positions in the current file generation.

func AppendIndexEntries

func AppendIndexEntries(buf []byte, prev IndexEntry, hasPrev bool, entries []IndexEntry) ([]byte, IndexEntry, error)

AppendIndexEntries delta-encodes entries after prev. Within one posting list offsets are strictly increasing (file order) and times nearly so, so each entry costs a few bytes rather than the 25+ of a fixed layout — the index stays a small fraction of the log it describes. prev is the last entry already in buf; pass hasPrev=false for an empty list.

func DecodeIndexEntries

func DecodeIndexEntries(buf []byte) ([]IndexEntry, error)

DecodeIndexEntries is the inverse of AppendIndexEntries for a whole list.

type NodeInput added in v0.6.7

type NodeInput struct {
	NodeID string
	// Heads are the witnessed heads in witness order, oldest first. Heads
	// before Since may be included; they are listed, not checked.
	Heads []WitnessedHead
	// Prior is the newest head witnessed before the earliest of Heads, when
	// known: a head equal to it needs no records to link.
	Prior *WitnessedHead
	// Since is the window start the auditor chose. It must come from the
	// auditor, never from the evidence: a node that deletes its oldest
	// records must not shrink what gets checked (D22).
	Since time.Time
	// Now is the verification time; zero means time.Now.
	Now time.Time
	// MaxLag is how long a head may wait for its records to be exported.
	MaxLag time.Duration
	// Export supplies exported batches; nil means none.
	Export ExportSource
	// Local is a copy of the node's secrets.jsonl; nil means none.
	Local io.Reader
	// HiddenKeys are witness keys that carry a delete marker.
	HiddenKeys []string
	// NewestWitnessDay is the newest day with any witnessed version.
	NewestWitnessDay string
	// NoWitness says the caller has no witness to compare against (an
	// `aerolvm audit search` without --witness): the walk still proves every
	// record links to the one before it, but no head is checked and the
	// node is not reported silent for having none.
	NoWitness bool
}

NodeInput is everything the verifier knows about one node.

type NodeReport added in v0.6.7

type NodeReport struct {
	NodeID            string        `json:"node_id"`
	Result            Result        `json:"result"`
	WindowStart       time.Time     `json:"window_start"`
	HeadsBeforeWindow int           `json:"heads_before_window"`
	HeadsInWindow     int           `json:"heads_in_window"`
	HeadsLinked       int           `json:"heads_linked"`
	Pending           []PendingHead `json:"pending,omitempty"`
	Problems          []string      `json:"problems,omitempty"`
	Warnings          []string      `json:"warnings,omitempty"`
	Silent            bool          `json:"silent"`
	RecordsChecked    int64         `json:"records_checked"`
	EvidenceFrom      *time.Time    `json:"evidence_from,omitempty"`
	EvidenceTo        *time.Time    `json:"evidence_to,omitempty"`
	ExportBatches     int           `json:"export_batches"`
	// UnreachedBatches were never on the walk: re-sends and overlapping
	// re-exports of records already checked, or forks.
	UnreachedBatches int `json:"export_batches_unreached"`
	// contains filtered or unexported fields
}

NodeReport is the verdict for one node and what it rests on.

func SearchNode added in v0.6.8

func SearchNode(ctx context.Context, in NodeInput, f SearchFilter, fn func(Event)) (NodeReport, error)

SearchNode walks one node's evidence like VerifyNode and calls fn with every record that links into the chain and passes f, in chain order. The report is VerifyNode's: a FAIL means the history the matches came from does not hold up, and a caller must not present them as evidence.

func VerifyNode added in v0.6.7

func VerifyNode(ctx context.Context, in NodeInput) (NodeReport, error)

VerifyNode checks one node. An error means the inputs could not be read; a contradiction in what was read is a FAIL in the report instead.

type PendingHead added in v0.6.7

type PendingHead struct {
	HeadHex string    `json:"head"`
	At      time.Time `json:"witnessed_at"`
	Ref     string    `json:"ref,omitempty"`
	// Stale is true once the head has waited longer than MaxLag.
	Stale bool `json:"stale"`
}

PendingHead is a head newer than the evidence.

type Request added in v0.6.8

type Request struct {
	// Method and Route are the HTTP method and the route pattern the call
	// matched ("POST /v1/sandboxes/{id}/exec"), never the raw path, which
	// can carry ids and query values.
	Method string `json:"method,omitempty"`
	Route  string `json:"route,omitempty"`
	// Status is the response status; 101 for a WebSocket upgrade, recorded
	// at the upgrade.
	Status int `json:"status,omitempty"`
	// Digest is a keyed digest of an exec request body, "hmac:<key id>:<hex>":
	// an HMAC under a key derived from the server key, of the body's SHA-256
	// as it streamed. It proves which command ran without recording it, and
	// without letting a reader of the log test a guessed secret. Records from
	// older releases hold the body's plain hex SHA-256; empty when the body
	// was not read or no server key was usable.
	Digest string `json:"digest,omitempty"`
	// Count is how many identical calls one coalesced record stands for.
	// Absent means one.
	Count int64 `json:"count,omitempty"`
	// Surface is how the call arrived when not as a direct API request:
	// SurfaceMCP or SurfaceSSH.
	Surface string `json:"surface,omitempty"`
	// Argv is the command an exec ran, only with SB_AUDIT_EXEC_COMMAND=full.
	// Never the environment.
	Argv []string `json:"argv,omitempty"`
	// Target is the object a call acted on when it is not a sandbox: the
	// token, snapshot, egress profile, WASM module, JS bundle or template id
	// from the route's path; on a toolbox route, the sub-path inside the
	// sandbox ("process/execute").
	Target string `json:"target,omitempty"`
	// Routes lists the routes a rate_limited record's calls hit.
	Routes []string `json:"routes,omitempty"`
	// Source is the client address of an auth_denied record.
	Source string `json:"source,omitempty"`
	// Grant is the role and team a token create gave the token it minted
	// (Target is its id), so "who minted this admin token" survives the
	// token row's deletion (§5.9; T5b's access review reads it).
	Grant *Grant `json:"grant,omitempty"`
}

Request is the call behind an api record. Every field is omitempty, so a record carries only what applies to it. Field order is part of the hash: append only.

type Result added in v0.6.7

type Result string

Result is a node's verdict.

const (
	// ResultPass means every head in the window links to the next one.
	ResultPass Result = "PASS"
	// ResultFail means the evidence contradicts the witness, or is missing
	// for part of the window.
	ResultFail Result = "FAIL"
	// ResultIncomplete means some heads are newer than the evidence and have
	// been waiting for it longer than the allowed lag. Never a pass: a node
	// that stopped exporting could otherwise hide a forged newest head.
	ResultIncomplete Result = "INCOMPLETE"
)

type SSHGatewayCall added in v0.6.9

type SSHGatewayCall struct {
	// SandboxID is the sandbox whose key opened the SSH session. It must be
	// the sandbox the call's path names.
	SandboxID string
	// Open marks the first call of an SSH session channel: the node that
	// runs it writes the session's one ssh record, naming Session.
	Open bool
	// Session is the toolbox session the SSH session attached to ("" for a
	// one-shot exec), as the ssh record's target. Only with Open.
	Session string
}

SSHGatewayCall is one call the SSH gateway bridged for a sandbox key holder.

func ParseSSHGatewayCall added in v0.6.9

func ParseSSHGatewayCall(raw string) (SSHGatewayCall, bool)

ParseSSHGatewayCall reads a value Encode wrote. ok is false for anything else, including a value that names no sandbox or names it twice.

func SSHGatewayCallFromContext added in v0.6.9

func SSHGatewayCallFromContext(ctx context.Context) (SSHGatewayCall, bool)

SSHGatewayCallFromContext returns the call ContextWithSSHGatewayCall attached.

func (SSHGatewayCall) Encode added in v0.6.9

func (c SSHGatewayCall) Encode() string

Encode is c's header value: "sandbox=<id>", plus "&open=<session>" on the call that opens the session.

type ScanOptions added in v0.6.7

type ScanOptions struct {
	// Base is the byte offset in the underlying file where the reader
	// starts; every offset in ChainScan is reported in file coordinates.
	Base int64
	// Verifier, when set, is copied (never mutated) and continued from.
	Verifier *ChainVerifier
	// StartEventID and StartLineOffset describe the record carrying the
	// primed verifier's head, reported back when nothing follows it.
	StartEventID    string
	StartLineOffset int64
	// Probe lists hashes whose presence the scan should report (witness
	// ancestry) — O(len(Probe)) memory instead of O(records).
	Probe []string
}

ScanOptions parameterize one pass. A nil Verifier starts at genesis; a primed one continues a chain from Base (checkpoint boot).

type SearchFilter added in v0.6.8

type SearchFilter struct {
	// Caller matches the record's caller id exactly ("tok_7Hq2…",
	// "operator", "system:lifecycle") or its display name ignoring case
	// ("ana@acme.com").
	Caller string
	// Kind matches the record kind ("api", "secret_open", "auth_denied").
	Kind string
	// SandboxID matches the sandbox the record is about.
	SandboxID string
	// Result matches the result ("ok", "denied", "error", "success", ...).
	Result string
	// Since and Until bound the record time: Since inclusive, Until
	// exclusive.
	Since, Until time.Time
}

SearchFilter selects records. A zero field matches everything.

func (SearchFilter) Match added in v0.6.8

func (f SearchFilter) Match(ev Event) bool

Match reports whether ev passes the filter. Records retention left behind (checkpoints and stubs) are chain structure, not evidence of anything, and match only a filter that asks for their kind.

type SpillFile

type SpillFile struct {
	Path     string
	LockPath string
}

SpillFile is one audit directory's overflow buffer.

func SpillFileIn

func SpillFileIn(dir string) SpillFile

SpillFileIn names the spill buffer and lock of an audit directory.

func (SpillFile) Append

func (s SpillFile) Append(events []Event) error

Append durable-appends events with no capability (gap markers, daemon-side tests). Egress records need AppendRecords: an unauthenticated egress line is drained as a gap.

func (SpillFile) AppendRecords

func (s SpillFile) AppendRecords(records []SpillRecord) error

AppendRecords durable-appends records as one write and one fsync under the audit lock. Events get an id and a time if they lack one. Either every line lands or the error covers the whole batch: a torn spill line is repaired by the daemon's drain (which counts it as a gap), so a crash mid-write loses at most this batch and never corrupts what came before.

type SpillRecord

type SpillRecord struct {
	Event
	Capability string `json:"capability,omitempty"`
}

SpillRecord is one spill line: the event plus the sandbox-scoped capability the worker would have sent on the ingest header. The spill file is written by worker subprocesses and drained by the daemon, so every identity field on the line is unauthenticated until the drain verifies the capability and rebinds them from it — exactly what the HTTP ingest does. The capability is a bearer credential and never reaches secrets.jsonl.

type WitnessedHead added in v0.6.7

type WitnessedHead struct {
	HeadHex string
	// At is the witness's own time for the head (S3 LastModified).
	At time.Time
	// Ref says where the head is stored, for messages.
	Ref string
}

WitnessedHead is one head as the witness recorded it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL