Documentation
¶
Overview ¶
Package recordmode is the deterministic core of Wardyn's "Recording Mode": it OBSERVES what a fully-open (allow-all-egress, broad-grant) run actually used — purely from already-captured audit events — and SYNTHESIZES a tightened, least-privilege RunPolicySpec the operator can review and promote.
PURITY: the two entry points are pure functions of their inputs (audit events, grants, the run in; values out) — no database, network, clock, or global state, so synthesis is a function of captured evidence, not of anything an in-sandbox agent can influence after the fact.
DETERMINISM: every set is de-duplicated and SORTED, egress decision counts are sums, and Synthesize iterates already-sorted fields, so equal evidence always yields byte-identical output.
HONESTY: Recording Mode tightens from evidence but deliberately does NOT auto-author everything — it never auto-wildcards a domain, it forces allow_all_egress=false and first_use_approval=true so the tightened policy fails toward human escalation rather than silent denial, and it does not synthesize WorkspaceMounts or an exec/connect/file allowlist, surfacing kernel ground-truth as warnings/Observations instead.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CleanReplay ¶ added in v0.6.0
func CleanReplay(obs []DomainObservation, truncated bool) bool
CleanReplay is the server-side verdict for a CONFINED replay (Workstream B): true iff the capture is clean FOR WHAT WAS REPLAYED. Pure; meaningful only for a settled `recorded` capture, which the caller gates on before calling this.
clean iff, across every observed domain: zero DenyCount, zero PendingCount, and zero ApprovalCount (no allow was released by a live first-use approval — approving mid-replay must not earn a green the standing policy didn't; the honest loop is approve, then replay again) — AND the capture itself was not truncated (maxCaptureAuditEvents, workspace_run.go). Hard-walled denies count as caught like any other DenyCount.
Empty obs with truncated=false is clean. "Clean" does NOT mean "nothing could go wrong" — a replay the operator ends early earns the same verdict as a full one if nothing else caught it.
func Synthesize ¶
func Synthesize(obs Observations, runGrants []types.CredentialGrant, run types.AgentRun) (types.RunPolicySpec, []string)
Synthesize derives a tightened, least-privilege RunPolicySpec from the Observations of an open run plus the run's grant catalog and the run itself. Pure and deterministic; returns the spec alongside human-readable warnings explaining every tightening decision and everything it deliberately did NOT auto-author. See the package doc for the honesty guarantees.
Types ¶
type DomainObservation ¶
type DomainObservation struct {
Host string `json:"host"` // lowercased, trimmed egress hostname (no port)
// Methods is the de-duplicated, sorted set of HTTP methods observed (an upper-cased "CONNECT"
// appears for tunneled TLS); may be empty when the proxy only saw opaque CONNECTs.
Methods []string `json:"methods,omitempty"`
AllowCount int `json:"allow_count"` // number of egress.allow/deny/pending decisions recorded for this host
DenyCount int `json:"deny_count"`
PendingCount int `json:"pending_count"`
// ApprovalCount is the subset of AllowCount RELEASED by a live first-use approval rather than the
// standing policy. CleanReplay treats any of these as caught: approving mid-replay must not earn
// a green the standing policy didn't.
ApprovalCount int `json:"approval_count"`
}
DomainObservation is one egress host the run actually reached, with the HTTP method set observed at the proxy and the per-decision counts. Methods is de-duplicated and sorted; counts are sums over every decision for the host.
type KernelWindow ¶ added in v0.7.4
type KernelWindow struct {
Beat bool // true when a sensor heartbeat landed inside the capture window
DroppedUnmapped uint64 // that beat's cumulative count of kernel events refused as correlating to no run
ObservedTotal uint64 // that beat's cumulative count of kernel events the sensor DID bind to a run
}
KernelWindow is what the host's eBPF sensor said about ITSELF while this capture was running — the one fact a capture's own audit events cannot carry. Must be scoped to the capture's window: the sensor is host-wide and its heartbeat global, so a beat from days later is not evidence about this capture. The zero value (no heartbeat inside the window) is the honest answer for a host with no sensor.
type Observations ¶
type Observations struct {
Domains []DomainObservation `json:"domains,omitempty"` // per-host egress aggregate (deduped, sorted by host)
// MintedGrantIDs is the deduped, sorted set of grant ids the run SUCCESSFULLY minted a credential
// for (credential.mint with outcome=success); a denied or failed mint is NOT included.
MintedGrantIDs []uuid.UUID `json:"minted_grant_ids,omitempty"`
ExecArgv0s []string `json:"exec_argv0s,omitempty"` // deduped, sorted argv[0] the kernel sensor observed the run exec
FileWrites []string `json:"file_writes,omitempty"` // deduped, sorted sensitive file paths the kernel sensor observed the run write
Connects []string `json:"connects,omitempty"` // deduped, sorted "ip:port" destinations the kernel sensor observed the run connect to
// Anomalies is the deduped, sorted set of human-readable signals a least-privilege synthesis must
// NOT silently bless: an egress.deny during open recording, a dynamic-linker exec, a
// failed/escape kernel connect, and the sensor dropping events as unmapped during this capture.
Anomalies []string `json:"anomalies,omitempty"`
}
Observations is the deterministic aggregate of what a run actually used, computed purely from its already-captured audit events. Every slice is de-duplicated and sorted, so equal evidence yields equal Observations.
func Capture ¶
func Capture(events []types.AuditEvent, confined bool, kernel KernelWindow) Observations
Capture aggregates one run's already-captured audit events into a deduped, sorted Observations. Pure and input-order independent: reads only the egress.*, credential.mint, and kernel.* streams.
confined distinguishes an OPEN (learning) recording, where a deny is a real anomaly, from a CONFINED replay, where a deny is the containment proof working as designed — still captured on the per-host DomainObservation, but not landed in Anomalies.
kernel carries the one anomaly this run's OWN events cannot show: the sensor's unmapped-drop count while the capture was running. See KernelWindow.
Source Files