fleetagent

type AckLedger ¶ added in v0.2.0

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

AckLedger tracks, for ONE stream incarnation, which sequences have been received, and derives the highest-contiguous ACK and the explicit gaps below it. The ACK a stream reports is the highest sequence S such that every sequence in 1..S has been received — so an ACK can never skip a hole, and any sequence received out of order above a hole is remembered but does NOT advance the ACK until the hole fills. The gaps are the still-missing sequences below the highest one received, i.e. the explicit, queryable "we know these are outstanding" set. A zero-value AckLedger is ready to use.

NOT safe for concurrent use: it is a per-stream, per-caller accumulator — synchronize externally (or use one ledger per goroutine) rather than sharing an instance across goroutines.

func NewAckLedger() *AckLedger

func (l *AckLedger) Gaps() []SeqRange

func (l *AckLedger) HighestContiguous() uint64

func (l *AckLedger) Observe(seq uint64) bool

func (l *AckLedger) Pending() []uint64

func (l *AckLedger) SeedContiguous(n uint64)

type Agent ¶

type Agent struct {
	ID           shared.ID
	TenantID     shared.ID
	Name         string
	Platform     string
	OSVersion    string
	AgentVersion string
	Capabilities []string
	// Group is the rollout group an OPERATOR placed this agent in. It is never self-declared: an agent
	// that could name its own group could place itself in one pinned to an older, vulnerable version,
	// turning a rollout control into a downgrade primitive. Empty means the default group.
	Group     string
	TokenHash string
	// Fingerprint is the SHA-256 of the agent's issued client certificate (#408). Empty until a
	// certificate is issued from a CSR; it is the cryptographic identity used by mutual-TLS auth.
	Fingerprint  string
	State        State
	Audit        shared.Audit
	LastSeenAt   time.Time
	RevokedAt    *time.Time
	RevokedBy    shared.ID
	RevokeReason string
	// DecommissionedAt is when the agent self-reported a clean uninstall (#412). Nil unless the agent
	// is in StateDecommissioned. There is no "by": decommission is self-reported, not operator-attributed.
	DecommissionedAt *time.Time
}

Agent is an enrolled fleet agent. TokenHash is the hash of the bearer credential presented on every call; the plaintext is shown once at enrolment and never stored.

func NewAgent(id, tenantID shared.ID, name, platform, osVersion, agentVersion string, capabilities []string, tokenHash string, now time.Time) (*Agent, error)

func (a *Agent) AssignGroup(group string, now time.Time)

func (a *Agent) AttestCertificate(fingerprint string)

func (a *Agent) Decommission(now time.Time)

func (a *Agent) Decommissioned() bool

func (a *Agent) Removed() bool

func (a *Agent) Revoke(by shared.ID, reason string, now time.Time)

func (a *Agent) Revoked() bool

type AgentBatch ¶

type AgentBatch struct {
	AgentID      shared.ID
	EngagementID shared.ID
	Sequence     uint64
	KeyID        string // the AgentSigningKey this batch is signed with; resolved + verified server-side
	Signature    string // base64 ed25519 over BatchMessage
	Detections   []DetectionRef
}

AgentBatch is a sequenced, signed set of detections an agent shipped to the control plane (#423). The sequence is monotonic PER AGENT, so a gap in the sequence is a detectable potential loss rather than a silently-missing batch. The signature is over the batch's canonical membership (id AND content digest) AND its sequence, so neither the membership, the ordinal, nor a detection's CONTENT can be altered without breaking it.

func (b AgentBatch) IDs() []shared.ID

func (b AgentBatch) Validate() error

type AgentBatchV2 ¶ added in v0.2.0

type AgentBatchV2 struct {
	Context      string           `json:"context"`
	Version      int              `json:"version"`
	AgentID      shared.ID        `json:"agent_id"`
	EngagementID shared.ID        `json:"engagement_id"`
	Sequence     uint64           `json:"sequence"`
	KeyID        string           `json:"key_id"`
	Signature    string           `json:"signature"`
	Detections   []DetectionRefV2 `json:"detections"`
}

AgentBatchV2 is a separate wire and signature contract. AgentBatch, BatchMessage, SignBatch, and VerifyBatch remain the v1 contract and must not be changed by v2 callers.

func (b AgentBatchV2) Validate() error

type AgentSigningKey ¶ added in v0.2.0

type AgentSigningKey struct {
	KeyID      string            // evidence.KeyFingerprint(PublicKey); a key names itself, tamper-evident
	AgentID    shared.ID         // the canonical enrolled agent this key is bound to (#606)
	Algorithm  string            // SigningAlgorithm
	Purpose    SigningPurpose    // the one content stream this key may sign
	PublicKey  ed25519.PublicKey // raw 32-byte ed25519 public key
	NotBefore  time.Time         // key is not usable before this instant
	NotAfter   time.Time         // key is not usable at/after this instant (bounded — supports rotation)
	RevokedAt  time.Time         // zero = not revoked; a set value fails the key closed from that instant
	ReplacedBy string            // KeyID of the successor minted to rotate this key out; "" if none
}

AgentSigningKey is a first-class content-signing key with a lifecycle. It is minted by NewSigningKey so the KeyID↔PublicKey invariant always holds; a zero-value struct is not a valid key.

func ActiveKeyFor(ring []AgentSigningKey, purpose SigningPurpose, now time.Time) (AgentSigningKey, bool)

func NewSigningKey(agentID shared.ID, purpose SigningPurpose, pub ed25519.PublicKey, notBefore, notAfter time.Time) (AgentSigningKey, error)

func (k AgentSigningKey) SameIdentity(o AgentSigningKey) bool

func (k AgentSigningKey) StatusAt(now time.Time) KeyStatus

func (k AgentSigningKey) UsableAt(now time.Time) error

func (k AgentSigningKey) Validate() error

type BootID ¶ added in v0.2.0

type BootID string

type BoundedProcessObservation ¶ added in v0.2.0

type BoundedProcessObservation struct {
	BootID     shared.ID
	OccurredAt time.Time
	ObservedAt time.Time
	Process    telemetry.ProcessObservation
}

BoundedProcessObservation is one process lifecycle event independently retained from the local durable process sensor. It is intentionally an envelope fragment, not a claim about a response outcome.

type DeliveryClass ¶ added in v0.2.0

type DeliveryClass string

DeliveryClass is how an incoming position relates to the last one accepted for the same stream.

const (
	// DeliveryOK — exactly the expected next sequence within the current incarnation.
	DeliveryOK DeliveryClass = "ok"
	// DeliveryForwardGap — ahead of the expected next in the current incarnation: one or more sequences are
	// unaccounted for (a potential loss the caller MUST surface as an explicit gap, never silently accept).
	DeliveryForwardGap DeliveryClass = "forward_gap"
	// DeliveryReplay — the incoming batch sequence is not ahead of the high-water within the current
	// incarnation. This covers BOTH a true duplicate AND a genuine late arrival that fills an earlier gap,
	// because ClassifyDelivery only knows the scalar high-water, not which sequences were actually received.
	// It therefore MUST NOT be treated as "discard the payload": the authority for "already have this
	// signal" is AckLedger.Observe / DeliveryKey (see below), and a below-high-water sequence is frequently
	// a real gap-fill that closes an outstanding gap. Equating !IsProgress() with drop would silently lose
	// exactly the signal the contract exists to preserve.
	DeliveryReplay DeliveryClass = "replay"
	// DeliveryNewIncarnation — a higher Epoch: a legitimate reboot/reinstall reset, NOT a replay even though
	// the Sequence dropped back toward 1. If the new incarnation's first sequence is > 1, Missing says how
	// many were lost across the restart.
	DeliveryNewIncarnation DeliveryClass = "new_incarnation"
	// DeliveryStaleIncarnation — a lower Epoch than the one already accepted: an old incarnation resurfacing
	// (a delayed/duplicated batch from before a restart). Treated as a replay-class event, never accepted as
	// forward progress.
	DeliveryStaleIncarnation DeliveryClass = "stale_incarnation"
)

type DeliveryOutcome ¶ added in v0.2.0

type DeliveryOutcome struct {
	Class   DeliveryClass
	Missing uint64
}

DeliveryOutcome is the classification plus, when relevant, how many sequences are unaccounted for.

func ClassifyDelivery(last, incoming StreamPosition) DeliveryOutcome

func (o DeliveryOutcome) HasGap() bool

func (o DeliveryOutcome) IsProgress() bool

type DeliveryPriority ¶ added in v0.2.0

type DeliveryPriority int

DeliveryPriority is the spool/delivery priority class of a signal. The agent's durable spool drains by class so the signals that matter most for a live engagement survive back-pressure and disk pressure first. The ladder is the contract; assigning a concrete signal to a class is the producer's job (A2).

const (
	// PriorityP0 — response-verification results, coverage/honesty, and sensor-health. Losing these would
	// make the platform lie about what it did or saw, so they drain first and are evicted last.
	PriorityP0 DeliveryPriority = iota
	// PriorityP1 — confirmed detections.
	PriorityP1
	// PriorityP2 — privilege changes and critical-file events.
	PriorityP2
	// PriorityP3 — background process/network telemetry (the highest-volume, most-sheddable stream).
	PriorityP3
)

func TelemetryPriority(class detection.Class) (DeliveryPriority, error)

func (p DeliveryPriority) String() string

func (p DeliveryPriority) Valid() bool

type DetectionAttribution ¶ added in v0.2.0

type DetectionAttribution struct {
	TelemetryRefs         []TelemetryReference
	Rulepack              RulepackReference
	RedactionPolicyDigest string
}

DetectionAttribution is the typed source-side seam for sources that possess real telemetry transport references. Existing DetectionSink.Emit stays a legacy v1 path because DetectionSensor does not expose such references; callers cannot populate this type by guessing from a detection's host or timestamp.

func (a DetectionAttribution) Validate() error

type DetectionBatchItem ¶ added in v0.2.0

type DetectionBatchItem struct {
	ID        shared.ID
	Detection detection.Detection
	AssetID   shared.ID
}

DetectionBatchItem is one detection body covered by an AgentBatch ref. It lives beside the batch contract so the agent transport and control-plane ingest share the exact same wire shape without an infrastructure package importing a server-side use case. AssetID is explicit because the asset is part of DetectionContentHash and must therefore be verified under the batch signature.

func (i DetectionBatchItem) Validate() error

type DetectionBatchItemV2 ¶ added in v0.2.0

type DetectionBatchItemV2 struct {
	ID                    shared.ID            `json:"id"`
	Detection             detection.Detection  `json:"detection"`
	AssetID               shared.ID            `json:"asset_id"`
	TelemetryRefs         []TelemetryReference `json:"telemetry_refs"`
	Rulepack              RulepackReference    `json:"rulepack"`
	RedactionPolicyDigest string               `json:"redaction_policy_digest"`
}

DetectionBatchItemV2 carries the full body corresponding to a v2 signed manifest entry.

func (i DetectionBatchItemV2) Reference() (DetectionRefV2, error)

func (i DetectionBatchItemV2) Validate() error

type DetectionEvidenceEnvelope ¶ added in v0.2.0

type DetectionEvidenceEnvelope struct {
	Context         string              `json:"context"`
	EnvelopeVersion int                 `json:"envelope_version"`
	TenantID        shared.ID           `json:"tenant_id"`
	EngagementID    shared.ID           `json:"engagement_id"`
	AgentID         shared.ID           `json:"agent_id"`
	AssetID         shared.ID           `json:"asset_id"`
	DetectionID     shared.ID           `json:"detection_id"`
	BatchSequence   uint64              `json:"batch_sequence"`
	KeyID           string              `json:"key_id"`
	RuleID          string              `json:"rule_id"`
	RuleVersion     int                 `json:"rule_version"`
	ContentSHA256   string              `json:"content_sha256"`
	Provenance      ProvenanceState     `json:"provenance"`
	ObservedAt      time.Time           `json:"observed_at"`
	Detection       detection.Detection `json:"detection"`
}

DetectionEvidenceEnvelope is the SELF-CONTAINED permanent chain link for a sealed detection (A5, #626). It carries everything needed to attribute and verify the detection — tenant/agent/asset/engagement, the batch identity that admitted it, the agent's content commitment (ContentSHA256, the same digest the agent signed), the rule provenance, and the detection itself — so the link remains verifiable and explainable AFTER the expirable projection row is swept. It deliberately carries NO wall-clock "sealed at": the sealed bytes must be byte-identical across an idempotent re-seal (SealOnce compares content), so every field is derived from the batch/detection, never from the ingest clock.

func DecodeDetectionEvidenceEnvelope(content []byte) (DetectionEvidenceEnvelope, error)

func NewDetectionEvidenceEnvelope(tenantID, engagementID, agentID, assetID, detectionID shared.ID, batchSequence uint64, keyID, contentSHA256 string, prov ProvenanceState, det detection.Detection) (DetectionEvidenceEnvelope, error)

func (e DetectionEvidenceEnvelope) Canonical() ([]byte, error)

func (e DetectionEvidenceEnvelope) Validate() error

func (e DetectionEvidenceEnvelope) VerifyContent() error

type DetectionEvidenceEnvelopeV2 ¶ added in v0.2.0

type DetectionEvidenceEnvelopeV2 struct {
	Context               string               `json:"context"`
	EnvelopeVersion       int                  `json:"envelope_version"`
	TenantID              shared.ID            `json:"tenant_id"`
	EngagementID          shared.ID            `json:"engagement_id"`
	AgentID               shared.ID            `json:"agent_id"`
	AssetID               shared.ID            `json:"asset_id"`
	DetectionID           shared.ID            `json:"detection_id"`
	BatchSequence         uint64               `json:"batch_sequence"`
	KeyID                 string               `json:"key_id"`
	ContentSHA256         string               `json:"content_sha256"`
	TelemetryRefs         []TelemetryReference `json:"telemetry_refs"`
	Rulepack              RulepackReference    `json:"rulepack"`
	RedactionPolicyDigest string               `json:"redaction_policy_digest"`
	ObservedAt            time.Time            `json:"observed_at"`
	Detection             detection.Detection  `json:"detection"`
}

DetectionEvidenceEnvelopeV2 commits the v2 signed attribution as immutable evidence. It is a distinct envelope so the v1 envelope's canonical bytes and decoder contract remain unchanged.

func DecodeDetectionEvidenceEnvelopeV2(content []byte) (DetectionEvidenceEnvelopeV2, error)

func NewDetectionEvidenceEnvelopeV2(tenantID, engagementID, agentID shared.ID, batchSequence uint64, keyID string, item DetectionBatchItemV2) (DetectionEvidenceEnvelopeV2, error)

func (e DetectionEvidenceEnvelopeV2) Canonical() ([]byte, error)

func (e DetectionEvidenceEnvelopeV2) Validate() error

func (e DetectionEvidenceEnvelopeV2) VerifyContent() error

type DetectionRef ¶

type DetectionRef struct {
	ID            shared.ID
	ContentSHA256 string
}

DetectionRef binds a detection id to a digest of its content, so the batch signature covers WHAT each detection is, not merely its id. ContentSHA256 is the hex sha256 the agent computed over the exact bytes it is shipping (see DetectionContentHash); the control plane recomputes it and refuses a mismatch, so a transport that swaps a detection's body for a known id is rejected before sealing.

type DetectionRefV2 ¶ added in v0.2.0

type DetectionRefV2 struct {
	ID                    shared.ID            `json:"id"`
	ContentSHA256         string               `json:"content_sha256"`
	AssetID               shared.ID            `json:"asset_id"`
	TelemetryRefs         []TelemetryReference `json:"telemetry_refs"`
	Rulepack              RulepackReference    `json:"rulepack"`
	RedactionPolicyDigest string               `json:"redaction_policy_digest"`
}

DetectionRefV2 is the immutable, signature-covered manifest entry for a v2 detection.

func (r DetectionRefV2) Validate() error

type DetectionSpoolPayload ¶ added in v0.2.0

type DetectionSpoolPayload struct {
	Version    int                  `json:"version"`
	Item       DetectionBatchItemV2 `json:"item"`
	ObservedAt time.Time            `json:"observed_at"`
}

DetectionSpoolPayload allows v2 attribution to survive the detection WAL. Version 1 remains a deliberately un-attributed legacy payload and is decoded by the shipper for compatibility.

func (p DetectionSpoolPayload) Validate() error

type EnrolToken ¶

type EnrolToken struct {
	Hash      string
	TenantID  shared.ID
	IssuedBy  string
	ExpiresAt time.Time
	UsedAt    time.Time // zero until consumed
	CreatedAt time.Time
}

EnrolToken is a single-use, tenant-scoped, expiring token an operator issues so an agent can enrol once. Only its hash is stored.

func NewEnrolToken(hash string, tenantID shared.ID, issuedBy string, expiresAt, now time.Time) (*EnrolToken, error)

func (t *EnrolToken) Usable(now time.Time) bool

type EventRef ¶ added in v0.2.0

type EventRef struct {
	ID     shared.ID
	Digest string // hex sha256 over the event's canonical shipped bytes
}

EventRef binds one shipped telemetry event's id to a digest of its canonical bytes, so the manifest signature covers WHAT each event is, not merely its id — a transport that swaps an event body for a known id is rejected before ingest.

type KeyStatus ¶ added in v0.2.0

type KeyStatus string

KeyStatus is a signing key's lifecycle state AT A GIVEN TIME. It is derived (never stored) from the window + revocation, so the same stored key reads Pending, Active, Expired, or Revoked as time moves.

const (
	KeyPending KeyStatus = "pending" // now < NotBefore
	KeyActive  KeyStatus = "active"  // usable
	KeyExpired KeyStatus = "expired" // now >= NotAfter
	KeyRevoked KeyStatus = "revoked" // now >= RevokedAt
)

type PendingDetectionV2 ¶ added in v0.2.0

type PendingDetectionV2 struct {
	Batch AgentBatchV2         `json:"batch"`
	Item  DetectionBatchItemV2 `json:"item"`
}

PendingDetectionV2 is the verified immutable input retained until custody completes.

func DecodePendingDetectionV2(content []byte) (PendingDetectionV2, error)

func (p PendingDetectionV2) Canonical() ([]byte, error)

type ProvenanceState ¶ added in v0.2.0

type ProvenanceState string

ProvenanceState is the durability/consistency state of a sealed detection's evidence (A5, #626).

What the IMMUTABLE envelope records is the detection-evidence commitment at admission: once the detection (and its own embedded evidence) is sealed into the permanent chain it is ProvenanceComplete — that is the only state a stable, content-compared seal may honestly assert, since the sealed bytes must be identical across an idempotent re-seal. The remaining states are the QUERY/READ-LAYER lifecycle over a detection's evidence: Pending while the SEPARATE raw-telemetry stream (A3) that a detection summarizes is not yet confirmed durable, Expired when the expirable projection is swept, Broken when chain verification fails. Those transitions are tracked on the mutable projection, never by rewriting the immutable link — wiring the live telemetry-durability cross-check is the remaining A5 tail.

const (
	// ProvenancePending: read-layer state — the raw telemetry stream a detection summarizes is not yet
	// confirmed durable. A detection over not-yet-durable telemetry must NOT be presented as complete.
	ProvenancePending ProvenanceState = "pending"
	// ProvenanceComplete: the detection evidence is durably sealed into the permanent chain. This is the
	// admission state carried by the immutable envelope.
	ProvenanceComplete ProvenanceState = "complete"
	// ProvenanceExpired: read-layer state — the expirable projection view has aged out under retention; the
	// permanent envelope still stands and remains verifiable on its own.
	ProvenanceExpired ProvenanceState = "expired"
	// ProvenanceBroken: read-layer state — chain/consistency verification failed for this detection's evidence.
	ProvenanceBroken ProvenanceState = "broken"
)

func (p ProvenanceState) Valid() bool

type ResponseCommand ¶ added in v0.2.0

type ResponseCommand struct {
	ProtocolVersion       int
	CommandID             shared.ID
	TenantID              shared.ID
	AgentID               shared.ID
	AssetID               shared.ID
	EngagementID          shared.ID
	Action                rdom.Action
	ActionDigest          string
	AttemptKey            string
	VerificationChallenge string
	AuthorizationTarget   engagement.Target
	Target                responsesaga.TargetFingerprint
	Reversal              bool
	HaltGeneration        int64
	IssuedAt              time.Time
	NotAfter              time.Time
	SigningKeyID          string
	Signature             string
}

ResponseCommand is the control-plane-authorized command accepted by the endpoint response actuator. The signature covers every field that can change what executes. The first protocol version deliberately supports process stop/restart only; other response kinds require their own target-resolution review.

func (c ResponseCommand) Validate() error

type ResponseCommandSigningKey ¶ added in v0.2.0

type ResponseCommandSigningKey struct {
	KeyID     string
	PublicKey ed25519.PublicKey
	NotBefore time.Time
	NotAfter  time.Time
	RevokedAt time.Time
}

ResponseCommandSigningKey is one trusted control-plane command key. KeyID is the public-key fingerprint; bounded validity and monotonic revocation allow explicit overlap during rotation.

func NewResponseCommandSigningKey(publicKey ed25519.PublicKey, notBefore, notAfter time.Time) (ResponseCommandSigningKey, error)

func (k ResponseCommandSigningKey) UsableAt(at time.Time) error

func (k ResponseCommandSigningKey) Validate() error

type ResponseExecutionJournalEntry ¶ added in v0.2.0

type ResponseExecutionJournalEntry struct {
	Version            int
	Command            ResponseCommand
	CommandDigest      string
	LeaseID            string
	LeaseUntil         time.Time
	State              ResponseExecutionState
	Result             *ResponseExecutionResult
	ResultAcknowledged bool
}

func (e ResponseExecutionJournalEntry) Validate() error

type ResponseExecutionResult ¶ added in v0.2.0

type ResponseExecutionResult struct {
	AttemptKey     string
	CommandDigest  string
	LeaseID        string
	State          ResponseExecutionState
	ObservedRadius offensivepolicy.Radius
	AffectedCount  int
	AlreadyApplied bool
	CompletedAt    time.Time
}

ResponseExecutionResult is the local durable command outcome. It is not verification evidence; independent post-condition telemetry remains authoritative for VerifiedSucceeded.

func (r ResponseExecutionResult) Validate() error

type ResponseExecutionState ¶ added in v0.2.0

type ResponseExecutionState string

const (
	ResponseExecutionPrepared       ResponseExecutionState = "prepared"
	ResponseExecutionExecuting      ResponseExecutionState = "executing"
	ResponseExecutionApplied        ResponseExecutionState = "applied"
	ResponseExecutionOutcomeUnknown ResponseExecutionState = "outcome_unknown"
)

func (s ResponseExecutionState) Valid() bool

type ResponseHaltCommand ¶ added in v0.2.0

type ResponseHaltCommand struct {
	ProtocolVersion int
	CommandID       shared.ID
	TenantID        shared.ID
	AgentID         shared.ID
	AssetID         shared.ID
	Generation      int64
	AttemptKey      string
	IssuedAt        time.Time
	NotAfter        time.Time
	SigningKeyID    string
	Signature       string
}

ResponseHaltCommand durably raises one endpoint's monotonic response fence. It is separate from effect commands so a halt can carry no action or target that could itself change production state.

func (c ResponseHaltCommand) Validate() error

type ResponseObservation ¶ added in v0.2.0

type ResponseObservation struct {
	TargetExit  BoundedProcessObservation
	Replacement *BoundedProcessObservation
}

ResponseObservation is the only process evidence an observer may submit for an addressed request. Forward observations contain an actual target exit. Reversal observations additionally contain the unique actual replacement observed later.

func (o ResponseObservation) ValidateFor(request ResponseObservationRequest) error

type ResponseObservationRequest ¶ added in v0.2.0

type ResponseObservationRequest struct {
	ProtocolVersion       int
	RequestID             shared.ID
	TenantID              shared.ID
	ObserverAgentID       shared.ID
	AssetID               shared.ID
	EngagementID          shared.ID
	ActionID              shared.ID
	ActionDigest          string
	AttemptKey            string
	VerificationChallenge string
	ReceiptID             shared.ID
	ReceiptDigest         string
	Target                responsesaga.TargetFingerprint
	Reversal              bool
	AttemptedAt           time.Time
	IssuedAt              time.Time
	NotAfter              time.Time
}

ResponseObservationRequest asks an independently enrolled agent to emit a signed readiness report. It deliberately carries no verdict, process state, or coverage assertion.

func (r ResponseObservationRequest) Validate() error

type ResponseObserverBinding ¶ added in v0.2.0

type ResponseObserverBinding struct {
	TenantID   shared.ID
	AgentID    shared.ID
	AssetID    shared.ID
	AssignedBy string
	AssignedAt time.Time
	ExpiresAt  time.Time
	Version    int
}

ResponseObserverBinding is the server-owned authorization for a secondary agent to observe one canonical asset without becoming that asset's primary inventory owner.

func (b ResponseObserverBinding) ActiveAt(now time.Time) bool

func (b ResponseObserverBinding) Validate() error

type ResponseTargetEvidenceReceipt ¶ added in v0.2.0

type ResponseTargetEvidenceReceipt struct {
	Version               int                            `json:"version"`
	ReceiptID             shared.ID                      `json:"receipt_id"`
	Digest                string                         `json:"digest"`
	TenantID              shared.ID                      `json:"tenant_id"`
	EngagementID          shared.ID                      `json:"engagement_id"`
	ActionID              shared.ID                      `json:"action_id"`
	ActionDigest          string                         `json:"action_digest"`
	AttemptKey            string                         `json:"attempt_key"`
	VerificationChallenge string                         `json:"verification_challenge"`
	Target                responsesaga.TargetFingerprint `json:"target"`
	Reversal              bool                           `json:"reversal"`
	AttemptedAt           time.Time                      `json:"attempted_at"`
	WindowUntil           time.Time                      `json:"window_until"`
	RecordedAt            time.Time                      `json:"recorded_at"`
	SourceAgentID         shared.ID                      `json:"source_agent_id"`
	SourceAgentSessionID  shared.ID                      `json:"source_agent_session_id"`
	SourceHostID          shared.ID                      `json:"source_host_id"`
	Timeline              []endpoint.TimelineEntry       `json:"timeline"`
	Coverage              []sensorstate.CoverageWindow   `json:"coverage"`
	TimelineComplete      bool                           `json:"timeline_complete"`
	CoverageComplete      bool                           `json:"coverage_complete"`
	Saturated             bool                           `json:"saturated"`
	Reasons               []string                       `json:"reasons"`
}

ResponseTargetEvidenceReceipt is the immutable, server-generated snapshot of bounded target-primary telemetry. It is deliberately independent of the observer that later purpose-signs its binding.

func CloneResponseTargetEvidenceReceipt(r ResponseTargetEvidenceReceipt) ResponseTargetEvidenceReceipt

func (r ResponseTargetEvidenceReceipt) Validate() error

type ResponseVerificationReport ¶ added in v0.2.0

type ResponseVerificationReport struct {
	ProtocolVersion            int
	ReportID                   shared.ID
	AgentID                    shared.ID
	HostID                     shared.ID
	AgentSessionID             SessionID
	AssetID                    shared.ID
	EngagementID               shared.ID
	ActionID                   shared.ID
	ActionDigest               string
	AttemptKey                 string
	VerificationChallenge      string
	ReceiptID                  shared.ID
	ReceiptDigest              string
	Target                     responsesaga.TargetFingerprint
	Reversal                   bool
	ObservedAt                 time.Time
	ReplacementProcessEntityID shared.ID
	KeyID                      string
	Signature                  string
}

ResponseVerificationReport is a purpose-signed P0 readiness observation produced by a response observer, never by the command result endpoint. It carries no verdict, process state, or coverage claim: the control plane derives those from accepted endpoint timeline and coverage records. A reversal may nominate the distinct replacement entity whose lifecycle the control plane must independently confirm.

func (r ResponseVerificationReport) ObserverIdentity() string

func (r ResponseVerificationReport) Validate() error

type RulepackReference ¶ added in v0.2.0

type RulepackReference struct {
	ID      string `json:"id"`
	Version int    `json:"version"`
	Digest  string `json:"digest"`
}

RulepackReference binds a detection to the exact rulepack artifact that supplied its rule.

func (r RulepackReference) Validate() error

type SensorStateReport ¶ added in v0.2.0

type SensorStateReport struct {
	ProtocolVersion int
	ReportID        shared.ID
	AgentID         shared.ID
	HostID          shared.ID
	AgentSessionID  SessionID
	AssetID         shared.ID
	// ResponseObservationID is optional and permits target sensor state only for a live,
	// addressed response-observation work order; it never changes general host ownership.
	ResponseObservationID shared.ID `json:"response_observation_id,omitempty"`
	Kind                  string
	ObservedAt            time.Time
	SchemaVersion         int
	PayloadDigest         string
	States                []detection.ClassCoverage
	KeyID                 string
	Signature             string
}

SensorStateReport is a signed, self-contained P0 sensor-state/coverage record. It deliberately uses the existing telemetry signing key, but a separate message context prevents replay as a raw telemetry batch or spool gap.

func (r SensorStateReport) Validate() error

type SeqRange ¶ added in v0.2.0

type SeqRange struct {
	From uint64 // inclusive
	To   uint64 // inclusive
}

SeqRange is an inclusive range of sequence numbers, used to report gaps compactly.

type SequenceGap ¶

type SequenceGap struct {
	// Missing is how many batches are unaccounted for between the last seen and this one. > 0 means a
	// potential loss the caller must surface (a batch_gap coverage event), never silently accept.
	Missing uint64
	// Replay is true when the incoming sequence is not ahead of the last seen (duplicate or out-of-order),
	// which is also suspicious and must be reported rather than double-counted.
	Replay bool
}

SequenceGap describes what an incoming batch sequence implies against the last one seen for an agent.

func DetectSequenceGap(lastSeen, incoming uint64) SequenceGap

func (g SequenceGap) HasGap() bool

type SessionID ¶ added in v0.2.0

type SessionID string

SessionID identifies one agent run/enrolment session; BootID identifies one host boot. Both are opaque (typically random) — they are recorded for attribution and to detect corruption, but ordering is decided by the Epoch, because random ids cannot be compared. A reinstall changes the Session; a reboot changes the Boot; either resets the per-stream Sequence, and the agent signals that reset by advancing Epoch.

func CanonicalSessionID(agentID shared.ID) SessionID

type SigningPurpose ¶ added in v0.2.0

type SigningPurpose string

SigningPurpose is the single content stream a key may sign. A key is minted for exactly one purpose so a signature over one stream can never be replayed as another (domain separation).

const (
	PurposeTelemetryBatch SigningPurpose = "telemetry-batch"
	PurposeDetectionBatch SigningPurpose = "detection-batch"
	PurposeResponseResult SigningPurpose = "response-result"
)

func (p SigningPurpose) Valid() bool

type State ¶

type State string

State is the agent lifecycle.

const (
	StateActive State = "active"
	StateStale  State = "stale" // last seen longer ago than the freshness threshold (computed by fleet coverage)
	// StateRevoked is an OPERATOR decision: the credential is killed with attribution.
	StateRevoked State = "revoked"
	// StateDecommissioned is a terminal state the AGENT reports when it is cleanly uninstalled (#412).
	// It is distinct from Revoked (an operator killed it) and from Stale (it silently stopped reporting):
	// the control plane shows an orderly removal rather than leaving the identity to rot into Stale. A
	// decommissioned agent can no longer authenticate.
	StateDecommissioned State = "decommissioned"
)

func (s State) Valid() bool

type StreamPosition ¶ added in v0.2.0

type StreamPosition struct {
	Priority DeliveryPriority
	Epoch    uint64 // incarnation counter; increments on every Sequence reset (reboot/reinstall/spool-loss)
	Sequence uint64 // monotonic within (Priority, Epoch); restarts at 1 when Epoch increments
	Session  SessionID
	Boot     BootID
}

StreamPosition is where an agent is in one priority stream. Sequence is monotonic within an INCARNATION (Epoch); on a reboot/reinstall/spool-loss the agent starts a new incarnation — Epoch increments and Sequence restarts at 1. Carrying a monotonic Epoch (not just the opaque Session/Boot) is what lets the control plane tell a legitimate reset-to-1 apart from a replay of an old sequence: a higher Epoch is a new incarnation, never a replay.

func (p StreamPosition) Validate() error

type TelemetryBatchManifest ¶ added in v0.2.0

type TelemetryBatchManifest struct {
	ProtocolVersion int
	SchemaVersion   int
	BatchID         shared.ID
	AgentID         shared.ID
	HostID          shared.ID
	AssetID         shared.ID
	// ResponseObservationID is optional and, when present, binds target telemetry to one live,
	// addressed response-observation work order. It is never used to relabel general host telemetry.
	ResponseObservationID shared.ID `json:"response_observation_id,omitempty"`
	StreamID              shared.ID
	// Position carries Priority, Epoch, Sequence, Session (== the AgentSessionID) and Boot — the
	// incarnation-aware stream coordinate ClassifyDelivery/AckLedger reason over.
	Position         StreamPosition
	PreviousSequence uint64
	EventTimeMin     time.Time
	EventTimeMax     time.Time
	// The three loss outcomes are separate buckets; per-event reason lives on the first-class
	// TelemetryLoss/TelemetryGap, not here.
	ObservedCount        int
	KeptCount            int
	SampledOutCount      int
	TruncatedCount       int
	DroppedCount         int
	SamplingPolicyDigest string // digest of {SamplingAlgorithm, SamplingPolicyID, Seed, Version}
	// Events are the KeptCount shipped events, each bound by id + content digest.
	Events []EventRef
	// PayloadDigest commits to the canonical uncompressed transport payload (the events' shipped bytes).
	PayloadDigest string
	KeyID         string // the AgentSigningKey (Purpose=telemetry-batch) this manifest is signed with
	Signature     string // base64 ed25519 over TelemetryManifestMessage
}

TelemetryBatchManifest is a sequenced, signed manifest for one shipped telemetry batch (A3, #624). It binds the batch to a stream position (incarnation-aware, so a reboot reset-to-1 is not a replay — the A0.4 delivery contract), carries the three DISTINCT loss counts (Sampled ≠ Truncated ≠ Dropped, per D2/A0.6), and commits to the batch payload. AgentID/HostID/AssetID/AgentSessionID are carried so the control plane can compare every claimed identity coordinate with its authenticated/server-side binding. This is the TRANSPORT-integrity + ACK commitment only; the permanent evidence commitment (retention/proof/Merkle) is A5's, not computed here.

func (m TelemetryBatchManifest) AgentSessionID() SessionID

func (m TelemetryBatchManifest) Validate() error

type TelemetryGapReason ¶ added in v0.2.0

type TelemetryGapReason string

TelemetryGapReason is the stable wire vocabulary for durable A2 loss evidence. It intentionally mirrors the spool reasons without importing usecase ports into domain.

const (
	TelemetryGapQuotaEviction     TelemetryGapReason = "quota_eviction"
	TelemetryGapQuotaBackpressure TelemetryGapReason = "quota_backpressure"
	TelemetryGapCorruptFrame      TelemetryGapReason = "corrupt_frame"
	TelemetryGapTornWrite         TelemetryGapReason = "torn_write"
	TelemetryGapIOFailure         TelemetryGapReason = "io_failure"
	TelemetryGapUnsyncedTail      TelemetryGapReason = "unsynced_tail"
	TelemetryGapStateRecovery     TelemetryGapReason = "state_recovery"
)

func (r TelemetryGapReason) Valid() bool

type TelemetryGapReport ¶ added in v0.2.0

type TelemetryGapReport struct {
	ProtocolVersion int
	GapID           shared.ID
	AgentID         shared.ID
	HostID          shared.ID
	AgentSessionID  SessionID
	AssetID         shared.ID
	StreamID        shared.ID
	Priority        DeliveryPriority
	Epoch           uint64
	KnownSequence   bool
	FromSequence    uint64
	ToSequence      uint64
	Count           uint64
	Reason          TelemetryGapReason
	FromAt          time.Time
	ToAt            time.Time
	KeyID           string
	Signature       string
}

TelemetryGapReport is a signed, idempotent report of durable loss discovered by the agent spool. GapID is stable across retries and coalescing extensions. The server derives/validates AgentID, HostID, AgentSessionID, AssetID and StreamID against authenticated state before persisting it.

func (g TelemetryGapReport) Validate() error

type TelemetryReference ¶ added in v0.2.0

type TelemetryReference struct {
	StreamID shared.ID `json:"stream_id"`
	Epoch    uint64    `json:"epoch"`
	Sequence uint64    `json:"sequence"`
	EventID  shared.ID `json:"event_id"`
	Digest   string    `json:"digest"`
}

TelemetryReference identifies one durable transport event that causally supports a detection. It is deliberately transport-coordinate based: callers must not synthesize a reference from a host id, timestamp, or rendered evidence.

func (r TelemetryReference) Validate() error