Documentation
¶
Overview ¶
Package intent turns the model/agent's declared intent and the system's observed runtime effects into a first-class Intent-Runtime Diff.
The old model could only draw one edge: "the model said command X, and command X ran" (a positive match). It could not represent DIVERGENCE -- the agent said read-only but the network egressed, an install that read a foreign secret, a refusal that happened anyway. Those divergences are the whole security value.
This package generalizes past shell commands to three layers:
IntentContract -- what an action (tool call / peer message / refusal)
declares it should do and must-not do (effect sets)
RuntimeEffect -- what the system actually did, normalized tool-agnostically
IntentRuntimeDiff-- the typed reconciliation: match, boundary violation,
refusal-bypass, or an honest coverage gap
It reuses the existing pieces rather than replacing them: the eBPF/record events are the effect source, hooksbridge.CorrelateSyscalls provides the effect->agent attribution (command-match), and the security policy engine classifies whether a secret read is a foreign secret or the agent's own creds.
Index ¶
Constants ¶
const ( ContractToolCall = "tool_call" ContractPeerMessage = "peer_message" ContractRefusal = "refusal" )
Contract kinds.
const ( StatusMismatch = "declared_vs_effect_mismatch" // effect violates the contract boundary StatusRefusedBypass = "refused_but_runtime_happened" // a refused action's effects happened anyway StatusExecuted = "decided_and_executed" // declared effects appeared, no violation StatusCoverageGap = "intent_coverage_gap" // effects seen for a scope with NO captured intent )
Diff states. v1 deliberately ships the security-relevant states and the honesty state, and does NOT emit executed_without_intent (which needs complete intent capture to avoid false positives -- an effect with no contract is reported as intent_coverage_gap, not as a rogue action).
const FindingPeerMessageMismatch = "peer_message_intent_mismatch"
FindingPeerMessageMismatch marks a boundary violation whose intent originated from a peer message -- the multi-agent lateral-influence finding.
Variables ¶
This section is empty.
Functions ¶
func DefaultProfiles ¶
DefaultProfiles maps an operation to its contract. bash/exec is intentionally broad (it may read/write/connect) -- the residual hard case where the contract is nearly vacuous and we fall back to command semantics -- but even bash is still bound by the baseline (foreign-secret read + metadata egress are drift for ANY operation). Structured operations (file_read, install) have tight contracts and are where the diff earns its keep.
Types ¶
type EffectKind ¶
type EffectKind string
EffectKind is a normalized, tool-agnostic classification of what a runtime event actually did. Raw telemetry is preserved in the events table; the diff engine reasons only over these normalized effects.
const ( EffectProcessExec EffectKind = "process_exec" EffectFileRead EffectKind = "file_read" EffectFileWrite EffectKind = "file_write" EffectNetworkConnect EffectKind = "network_connect" // EffectSecretRead is a read of a FOREIGN secret/credential path -- i.e. one // the policy engine does not classify as the agent's own operational creds. // The self-vs-foreign split is what keeps the agent reading its own // ~/.claude creds from flooding every run as a mismatch. EffectSecretRead EffectKind = "secret_read" // EffectMetadataEgress is egress to the link-local cloud metadata IP. EffectMetadataEgress EffectKind = "metadata_egress" EffectPrivateCIDR EffectKind = "private_cidr_access" )
type IntentContract ¶
type IntentContract struct {
ID string `json:"id"`
Kind string `json:"kind"`
ScopeAgent string `json:"scope_agent"`
ToolCallID string `json:"tool_call_id,omitempty"`
Operation string `json:"operation"`
Target string `json:"target"`
Profile Profile `json:"-"`
Source string `json:"source"`
Confidence float64 `json:"confidence"`
// Negative marks a refusal: the agent declared it would NOT do the proposed
// action, so the baseline sensitive effects become a hard forbid for it.
Negative bool `json:"negative,omitempty"`
}
IntentContract is what one agent action declares it should and must-not do.
func ExtractContracts ¶
func ExtractContracts(db *sql.DB, runID string, profiles map[string]Profile) ([]IntentContract, error)
ExtractContracts builds every IntentContract for a run from the captured intent surfaces: each agent tool call (via its profile), each peer message (governing the recipient), and each refusal (a negative contract).
type IntentRuntimeDiff ¶
type IntentRuntimeDiff struct {
ID string `json:"id"`
RunID string `json:"run_id"`
AgentID string `json:"agent_id"`
ToolCallID string `json:"tool_call_id,omitempty"`
ContractKind string `json:"contract_kind"`
Operation string `json:"operation"`
Target string `json:"target"`
Status string `json:"status"`
Finding string `json:"finding,omitempty"`
Confidence float64 `json:"confidence"`
Declared []EffectKind `json:"declared_effects"`
Forbidden []EffectKind `json:"forbidden_effects"`
Observed []EffectKind `json:"observed_effects"`
MismatchReason string `json:"mismatch_reason,omitempty"`
Source string `json:"source"`
EventIDs []string `json:"event_ids,omitempty"`
}
IntentRuntimeDiff is one reconciliation of a contract against the effects attributed to its scope.
func Diff ¶
func Diff(contracts []IntentContract, effects []RuntimeEffect) []IntentRuntimeDiff
Diff reconciles contracts against runtime effects and returns typed diffs.
type Profile ¶
type Profile struct {
Operation string `yaml:"operation" json:"operation"`
Declared []EffectKind `yaml:"declared" json:"declared"`
Allowed []EffectKind `yaml:"allowed" json:"allowed"`
Forbidden []EffectKind `yaml:"forbidden" json:"forbidden"`
}
Profile is a tool/operation's effect contract: what it is expected to do (Declared), what it may additionally do without it counting as drift (Allowed), and what it must not do beyond the baseline (Forbidden).
type Result ¶
type Result struct {
RunID string `json:"run_id"`
Effects int `json:"effects"`
Contracts int `json:"contracts"`
Diffs int `json:"diffs"`
ByStatus map[string]int `json:"by_status"`
Mismatches int `json:"mismatches"`
CoverageGaps int `json:"coverage_gaps"`
}
Result summarizes a Materialize run.
func Materialize ¶
Materialize computes the Intent-Runtime Diff for a run and persists it. It is idempotent: prior diff rows and edges for the run are cleared first. It first runs the command-match attribution (hooksbridge.CorrelateSyscalls) so runtime effects are tied to the agent whose tool call caused them -- the effects are normally pinned by the sensor to the record-scope tool call, not the agent's hook tool call, and this bridge closes that gap.
type RuntimeEffect ¶
type RuntimeEffect struct {
Kind EffectKind `json:"kind"`
Target string `json:"target"`
AgentID string `json:"agent_id"`
ToolCallID string `json:"tool_call_id"`
EventID string `json:"event_id"`
Confidence float64 `json:"confidence"`
}
RuntimeEffect is one normalized effect attributed to an agent scope.
Source Files