Documentation
¶
Overview ¶
Package aisecuritycontext defines the wire types of the CHAINLOOP_AI_SECURITY_CONTEXT material: a security context compiled from a repository's fix history, carrying recurring vulnerability fingerprints, the attack surfaces they share, ranked risks, and byte-verifiable evidence anchors backing each claim.
These structs mirror the producer's contract and exist for annotation extraction only. Validation always runs on the generically decoded payload, because a typed decode drops unknown fields and would defeat the schema's additionalProperties: false.
Index ¶
Constants ¶
const ( // EvidenceID is the identifier for the AI security context material type. EvidenceID = "CHAINLOOP_AI_SECURITY_CONTEXT" // EvidenceSchemaURL is the namespace label of the JSON schema for the AI // security context payload. Nothing fetches it; the producer writes this // exact string into the envelope and the validator binds it to an embedded // schema at compile time. EvidenceSchemaURL = "https://schemas.chainloop.dev/aisecuritycontext/0.1/ai-security-context.schema.json" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Anchor ¶
type Anchor struct {
Revision string `json:"revision"`
RevisionSHA string `json:"revision_sha"`
Path string `json:"path"`
StartLine int `json:"start_line"`
EndLine int `json:"end_line"`
QuotedSpan string `json:"quoted_span"`
SpanSHA256 string `json:"span_sha256"`
Verified bool `json:"verified"`
Relocated bool `json:"relocated"`
Supports []string `json:"supports,omitempty"`
}
Anchor is a byte-verifiable evidence span. A consumer can re-verify it independently: git show <revision_sha>:<path> sliced at the line range must hash to SpanSHA256.
type CommitRef ¶
type CommitRef struct {
CommitSHA string `json:"commit_sha"`
Description string `json:"description,omitempty"`
CommittedAt string `json:"committed_at,omitempty"`
Verified bool `json:"verified"`
// TraceSessions are the Chainloop Trace session IDs (session_external_id)
// declared on this introducing commit via the Chainloop-Trace-Sessions git
// trailer — the AI coding session(s) that introduced the flaw. Recorded
// verbatim by the producer with no DB lookup; sorted + deduped.
TraceSessions []string `json:"trace_sessions,omitempty"`
}
CommitRef names a commit and what it did there, with the producer's proof attached. Verified means the commit was proved to be an ancestor of the fix — not that it is where the flaw actually entered.
type Data ¶
type Data struct {
SchemaVersion string `json:"schema_version"`
GeneratedAt string `json:"generated_at"`
Repo RepoRef `json:"repo"`
Provenance Provenance `json:"provenance"`
Scan ScanStats `json:"scan"`
ClassCounts map[string]int `json:"class_counts"`
// MinSupport is how many origin fixes a derived claim needs before it is
// stated as a pattern, emitted so a reader can tell a suppressed claim from
// an absent one.
MinSupport int `json:"min_support"`
TopRisks []TopRisk `json:"top_risks"`
Fingerprints []Fingerprint `json:"fingerprints"`
// Survivors is the adjudication work queue — the commits that survived
// Phase-1 triage, retained after draining as the coverage record. Present on
// an un-adjudicated (triage-only) or incrementally-built context; absent for
// a combined triage+adjudicate scan.
Survivors []Survivor `json:"survivors,omitempty"`
// Discarded are the commits Phase-1 triage classified and REJECTED — SHAs
// only, because a discard carries nothing else worth recording. Together with
// Survivors and Scan.Unresolved it states the full set of commits ever handed
// to the classifier.
Discarded []string `json:"discarded,omitempty"`
}
Data is the AI security context payload: the object the producer writes under the envelope's `data` field, and what the JSON schema validates.
type Evidence ¶
type Evidence struct {
ID string `json:"chainloop.material.evidence.id"`
Schema string `json:"schema"`
Data Data `json:"data"`
}
Evidence is the Chainloop material envelope around a security context.
The producer writes it: the crafter streams the file as it sits on disk and records the digest of those exact bytes, so a wrapper added downstream would mean attesting a digest for content that was never written. The envelope is also what makes the blob self-identifying once it is in CAS with none of the surrounding attestation context.
func NewEvidence ¶
NewEvidence wraps a payload in the material envelope.
type Fingerprint ¶
type Fingerprint struct {
ID string `json:"id"`
PatchID string `json:"patch_id,omitempty"`
CommitSHA string `json:"commit_sha"`
CommitDate string `json:"commit_date"`
CommitSubject string `json:"commit_subject"`
Class string `json:"class"`
CWE []string `json:"cwe"`
// Components are the paths the fix modified; ReachableFrom are paths the
// vulnerability was reachable through but which the fix did not change.
// Derived sections key off Components, so folding the two together would
// manufacture hot components out of untouched files.
Components []string `json:"components"`
ReachableFrom []string `json:"reachable_from,omitempty"`
SinkSymbols []string `json:"sink_symbols,omitempty"`
GuardSymbols []string `json:"guard_symbols,omitempty"`
Sink string `json:"sink,omitempty"`
FixKind string `json:"fix_kind,omitempty"`
FixShape string `json:"fix_shape,omitempty"`
Severity Severity `json:"severity"`
Confidence string `json:"confidence,omitempty"`
Summary string `json:"summary"`
POC string `json:"poc,omitempty"`
RootCause string `json:"root_cause,omitempty"`
AttackerPreconditions string `json:"attacker_preconditions,omitempty"`
Invariant string `json:"invariant,omitempty"`
FixCompleteness string `json:"fix_completeness"`
Anchors []Anchor `json:"anchors,omitempty"`
Reachability Reachability `json:"reachability"`
FailureContainment string `json:"failure_containment,omitempty"`
// IntroducedBy lists commits that each independently introduced the flaw —
// a set of co-introductions, never candidates the producer was choosing
// between. Absent, never empty, means the archaeology was inconclusive.
IntroducedBy []CommitRef `json:"introduced_by,omitempty"`
IntroducedToFixedSeconds int64 `json:"introduced_to_fixed_seconds,omitempty"`
// Status is empty when the invariant the fix established still holds, and
// "reverted" when a later commit undid it. A reverted fingerprint is
// annotated rather than dropped.
Status string `json:"status,omitempty"`
RevertedBy string `json:"reverted_by,omitempty"`
// TraceSessions are the Chainloop Trace session IDs (session_external_id)
// declared on the fix commit via the Chainloop-Trace-Sessions git trailer —
// the AI coding session(s) that produced the fix. Recorded verbatim by the
// producer with no DB lookup; sorted + deduped.
TraceSessions []string `json:"trace_sessions,omitempty"`
}
Fingerprint is one adjudicated past fix, the atom the security context is built from.
type Provenance ¶
type Provenance struct {
Tool string `json:"tool"`
ToolVersion string `json:"tool_version"`
Protocol string `json:"protocol"`
TriageModel string `json:"triage_model,omitempty"`
AdjudicationModel string `json:"adjudication_model,omitempty"`
TriagePromptID string `json:"triage_prompt_id,omitempty"`
AdjudicationPromptID string `json:"adjudication_prompt_id,omitempty"`
InputProfile string `json:"input_profile,omitempty"`
DecisionProfile string `json:"decision_profile,omitempty"`
CWECatalogVersion string `json:"cwe_catalog_version,omitempty"`
AnchorVerification string `json:"anchor_verification,omitempty"`
}
Provenance records what produced the artifact. The output is model-dependent, so a scan is not reproducible or auditable without the tool version and the per-phase model, prompt, and profile identity.
type Reachability ¶
type Reachability struct {
Verdict string `json:"verdict"`
Before string `json:"before,omitempty"`
After string `json:"after,omitempty"`
}
Reachability records how a fix changed what an attacker can reach. Before and After are the evidence for the verdict, not a restatement of it.
type RepoRef ¶
type RepoRef struct {
Owner string `json:"owner"`
Name string `json:"name"`
URL string `json:"url"`
Ref string `json:"ref"`
HeadSHA string `json:"head_sha"`
}
RepoRef identifies the scanned repository at a specific revision. Downstream this is a cross-check against the dispatch record that requested the scan, never a join key.
type ScanStats ¶
type ScanStats struct {
Window ScanWindow `json:"window"`
CommitsScanned int `json:"commits_scanned"`
CommitsTriaged int `json:"commits_triaged"`
CommitsSkipped int `json:"commits_skipped"`
TriageCandidates int `json:"triage_candidates"`
Adjudicated int `json:"adjudicated"`
Findings int `json:"findings"`
Abstained int `json:"abstained"`
Rejected int `json:"rejected"`
NoFinding int `json:"no_finding"`
TriageErrors int `json:"triage_errors"`
AdjudicationErrors int `json:"adjudication_errors"`
AnchorsVerified int `json:"anchors_verified"`
AnchorsRelocated int `json:"anchors_relocated"`
AnchorsRejected int `json:"anchors_rejected"`
InputTokens int64 `json:"input_tokens"`
OutputTokens int64 `json:"output_tokens"`
WallClockS float64 `json:"wall_clock_s"`
Reconciles bool `json:"reconciles"`
DuplicatesMerged int `json:"duplicates_merged,omitempty"`
Unresolved []Unresolved `json:"unresolved,omitempty"`
TruncatedUnresolved int `json:"truncated_unresolved,omitempty"`
// AdjudicatedCommits are the commit SHAs driven to a terminal Phase-2 state
// across all runs — the adjudication frontier.
AdjudicatedCommits []string `json:"adjudicated_commits,omitempty"`
// SurvivorsTotal is how many survivors the context holds at the covered
// window.
SurvivorsTotal int `json:"survivors_total,omitempty"`
// PendingSurvivors is how many survivors still await adjudication: neither in
// the frontier, nor a triage hole, nor abandoned after the retry cap. Zero
// alongside AdjudicationComplete is the drained queue.
PendingSurvivors int `json:"pending_survivors,omitempty"`
// TriageBudgetHit is true when the most recent triage run stopped because it
// reached its survivor budget (the --max-new-survivors cap) rather than
// because it exhausted its window, so known-untriaged history sits immediately
// behind Scan.Window.FromSHA. Cleared by a later run that exhausts its window
// without hitting the budget. It says nothing about the adjudication queue,
// and is not the same as a window that does not reach the repository root — a
// --last-bounded run does not either, and only git can answer that.
TriageBudgetHit bool `json:"triage_budget_hit,omitempty"`
// TriageInputTokens is the cumulative Phase-1 input tokens across every
// triage run.
TriageInputTokens int64 `json:"triage_input_tokens,omitempty"`
// TriageOutputTokens is the cumulative Phase-1 output tokens across every
// triage run.
TriageOutputTokens int64 `json:"triage_output_tokens,omitempty"`
// AdjudicationComplete is true when every survivor (outside holes/abandoned)
// reached a terminal state — the signal that an empty fingerprints list is
// "clean" rather than "not adjudicated yet".
AdjudicationComplete bool `json:"adjudication_complete,omitempty"`
// Abandoned is how many survivors adjudication gave up on after the retry cap — a
// terminal coverage gap, distinct from a still-pending survivor. Nonzero alongside
// AdjudicationComplete means the queue drained partly by giving up: complete, but
// not a clean bill of health.
Abandoned int `json:"abandoned,omitempty"`
}
ScanStats is the funnel every stage reports into, so that a silent failure cannot masquerade as a clean scan. Reconciles asserts
adjudicated == findings + abstained + rejected + no_finding + adjudication_errors
and a false value means the scan must not be read as complete.
type ScanWindow ¶
type ScanWindow struct {
FromSHA string `json:"from_sha,omitempty"`
ToSHA string `json:"to_sha,omitempty"`
LastN int `json:"last_n,omitempty"`
}
ScanWindow pins the history the scan covered, so a reader knows what was not examined.
type Severity ¶
type Severity struct {
Level string `json:"level"`
Source string `json:"source"`
Score *float64 `json:"score,omitempty"`
Vector string `json:"vector,omitempty"`
}
Severity carries the level together with how it was derived, so a consumer can tell a CVSS-backed rating from a model estimate.
type SharedSurface ¶
type SharedSurface struct {
}
SharedSurface is one invariant that must hold at every entry point reaching a shared sink, corroborated by two or more independent fixes.
Class is not a single taxonomy token: surfaces cluster on shared sink symbols, so a cluster spanning several classes carries them slash-joined.
type Survivor ¶ added in v1.109.2
type Survivor struct {
CommitSHA string `json:"commit_sha"`
ParentSHA string `json:"parent_sha,omitempty"`
CommitDate string `json:"commit_date,omitempty"`
Subject string `json:"subject,omitempty"`
// PatchID is git patch-id --stable: a rebase-durable key for history-rewrite
// reconciliation. Empty for merge commits.
PatchID string `json:"patch_id,omitempty"`
// DiffBytes is the size of the survivor's normalised diff in bytes.
DiffBytes int `json:"diff_bytes,omitempty"`
// Attempts counts failed adjudication tries; at the cap the survivor is
// abandoned.
Attempts int `json:"attempts,omitempty"`
// Verdict is the terminal adjudication outcome for a survivor that produced no
// fingerprint: no_finding | abstain | rejected. A survivor with a fingerprint is
// a finding and carries no verdict. Descriptive only — never affects scheduling.
Verdict string `json:"verdict,omitempty"`
// VerdictReason is the adjudicator's short explanation, carried only for
// abstentions (Verdict == "abstain"). Truncated by the producer.
VerdictReason string `json:"verdict_reason,omitempty"`
}
Survivor is one commit that survived Phase-1 triage: an entry in the adjudication work queue the context carries. Retained after draining as the coverage record. All but CommitSHA are optional.
type TopRisk ¶
type TopRisk struct {
Component string `json:"component"`
Kind string `json:"kind"`
Classes []string `json:"classes"`
Severity string `json:"severity"`
FixCount int `json:"fix_count"`
Recurring bool `json:"recurring"`
SeverityMass int `json:"severity_mass"`
RecencyWeight float64 `json:"recency_weight"`
CWE []string `json:"cwe"`
Evidence []string `json:"evidence"`
}
TopRisk is a component with a security-fix history, ranked by severity mass then recency-weighted fix count.
type Unresolved ¶
type Unresolved struct {
SHA string `json:"sha"`
Reason string `json:"reason"`
// Retryable is true when a later run should re-examine this commit: a transient
// diff-load, triage, or backend/adjudication failure. Absent (false) for a
// deterministic hole (an oversize diff) or a context written before this field
// existed.
Retryable bool `json:"retryable,omitempty"`
}
Unresolved is one commit inside the covered window that produced no answer.
Source Files