Documentation
¶
Index ¶
- Constants
- Variables
- func CanonicalProcessInstance(instance string, pid int64) string
- func CaptureOrigin(layers []map[string]any, pid int64) (string, bool)
- func CloseBinding(db *sql.DB, processID, endedAt string) error
- func CloseBindingByID(db bindingExecer, bindingID, endedAt string) error
- func CloseBindingByPID(db bindingPIDStore, pid int64, endedAt string) error
- func CloseProcessInstance(db ProcessStore, raw RawIdentity) error
- func DefaultBindingConfidence(bindingSource string) float64
- func EventPayloadWithCorrelation(payload string, match Match, resolved bool) string
- func ObserveProcessInstance(db ProcessStore, raw RawIdentity) error
- func ProcessInstanceBootID(instance string, pid int64) string
- func RecordBinding(db bindingExecer, binding Binding) (string, error)
- func RelatedProcessLifetime(parent, child string) bool
- type Binding
- type BindingFilter
- type Match
- type ProcessStore
- type Queryer
- type RawIdentity
Constants ¶
const ( AppProcessMethod = "agentprov.command_time_process/v3" AppProcessConfidence = 0.8 // Attribution tier, not a calibrated probability. AppProcessEdgePrefix = "agent-correlation-v3-" )
AppProcessMethod identifies derived app-to-runtime links, not kernel-proven agent identity. Keep its version in the stored edge ID for portable readers.
const BindingSourceK8sCgroup = "k8s_cgroup"
BindingSourceK8sCgroup marks a scope established by passive cgroup→pod attribution (a node sensor observing an externally-scheduled pod we did not launch), as opposed to a scope we launched via record/control-plane.
Variables ¶
var MaxOpenBindingAge = 24 * time.Hour
MaxOpenBindingAge bounds how long a binding left open (ended_at = "") is allowed to match telemetry. Without it, a binding whose CloseBinding was dropped - every close call is best-effort (record/control) - would match every future event for its container/pid forever, silently over-binding later, unrelated executions to a stale context. An open binding only matches events within this window after it started; older events fall through to the next resolution tier or to unresolved.
PRODUCT SEMANTICS: this assumes an open binding represents a SHORT-LIVED ToolCallScope (a tool call / process lifetime), not a session-lifetime identity. A long-running agent or session that stays open past this window without a close/reopen will see its real events go unresolved rather than risk mis-binding - which is the safe failure here. Session-lifetime identity that legitimately exceeds 24h must keep its binding refreshed (re-record on activity) or model itself as a series of scoped bindings, not one perpetual open binding. Tune via this var if the deployment's scope lifetimes differ.
Functions ¶
func CanonicalProcessInstance ¶ added in v0.10.0
func CaptureOrigin ¶ added in v0.10.0
CaptureOrigin namespaces kernel-local identifiers by the strongest recorded host identity and boot. A boot ID never hides a conflicting explicit host. Layers are storage envelopes, not alternative identities to choose between.
func CloseBindingByID ¶ added in v0.7.2
CloseBindingByID closes one exact binding. Kubernetes informer attribution uses this when a container restarts or its pod is deleted: closing by cgroup or session could accidentally terminate a sibling container's scope.
func CloseBindingByPID ¶ added in v0.3.0
func CloseProcessInstance ¶ added in v0.9.0
func CloseProcessInstance(db ProcessStore, raw RawIdentity) error
CloseProcessInstance uses the captured lifetime identity. A delayed exit must not close a different process that has reused the same numeric PID.
func DefaultBindingConfidence ¶ added in v0.7.0
DefaultBindingConfidence caps how much a binding may vouch for a match by how it was established, when the caller did not set an explicit confidence. Resolution takes the MIN of this binding confidence and the method's own confidence, so an app-asserted (ai_asserted) join can never read as certain as a kernel-verified one even if it happens to match by pid. This is the honesty tier: a scope the model merely CLAIMED is worth less than one the control plane launched or the kernel witnessed.
func ObserveProcessInstance ¶ added in v0.9.0
func ObserveProcessInstance(db ProcessStore, raw RawIdentity) error
ObserveProcessInstance retains a process-scoped anchor, never a new whole- cgroup binding. Only an observed cgroup/container or a kernel-identified parent can seed it; bare PID/PPID proximity cannot establish ancestry.
func ProcessInstanceBootID ¶ added in v0.10.0
ProcessInstanceBootID returns the kernel boot identity only for a validated native process instance. It is shared by scope attribution and graph analysis.
func RecordBinding ¶
func RelatedProcessLifetime ¶ added in v0.10.0
RelatedProcessLifetime accepts validated, canonical identities only.
Types ¶
type Binding ¶
type Binding struct {
ID string `json:"id"`
RunID string `json:"run_id"`
SessionID string `json:"session_id"`
AttemptID string `json:"attempt_id"`
ToolCallID string `json:"tool_call_id"`
ProcessID string `json:"process_id"`
ContainerID string `json:"container_id"`
CgroupID string `json:"cgroup_id"`
RootPID int64 `json:"root_pid"`
PID int64 `json:"pid"`
StartedAt string `json:"started_at"`
EndedAt string `json:"ended_at"`
BindingSource string `json:"binding_source"`
Confidence float64 `json:"confidence"`
// ConfidenceSet distinguishes an explicit zero from the legacy Go default.
ConfidenceSet bool `json:"-"`
}
func ListBindings ¶
func ListBindings(db *sql.DB, filter BindingFilter) ([]Binding, error)
func (Binding) MarshalJSON ¶ added in v0.10.0
func (*Binding) UnmarshalJSON ¶ added in v0.10.0
Preserve input presence across JSON and Go callers without changing the stored numeric contract. A missing field keeps the source-specific default.
type BindingFilter ¶
type Match ¶
type ProcessStore ¶ added in v0.9.0
type ProcessStore interface {
Queryer
// contains filtered or unexported methods
}
Source Files