Documentation
¶
Index ¶
- Constants
- Variables
- func EnsureEventID(ev *Event)
- func HashEvent(prevHash string, ev Event) string
- func LinkEvent(prevHash string, ev *Event)
- func LocalIncarnationID(sandboxID, toolboxToken string) string
- func MintEgressCapability(key, sandboxID, incarnationID string, expiry time.Time) (string, error)
- func NewEventID(nodeID string) string
- func ParseAndVerifyEgressCapability(key, capability string, now time.Time) (sandboxID, incarnationID string, err error)
- func WithFileLock(lockPath string, fn func() error) error
- type Event
- type IndexEntry
- type SpillFile
- type SpillRecord
Constants ¶
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 )
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.
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" )
const GenesisPrevHash = "0"
GenesisPrevHash is the prev_hash of the first event in a chain.
Variables ¶
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.
var ErrNoSpillPath = errors.New("audit spill path is unset")
ErrNoSpillPath reports a SpillFile with no destination.
Functions ¶
func HashEvent ¶
HashEvent returns SHA-256 hex of prevHash || canonical JSON of ev with EventHash cleared (so the hash does not depend on itself).
func LocalIncarnationID ¶
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 MintEgressCapability ¶
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 NewEventID ¶
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 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 WithFileLock ¶
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 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"`
}
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.
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 SpillFile ¶
SpillFile is one audit directory's overflow buffer.
func SpillFileIn ¶
SpillFileIn names the spill buffer and lock of an audit directory.
func (SpillFile) Append ¶
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 ¶
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.