Documentation
¶
Overview ¶
Package risk holds the deterministic, math-only side of the audit output. Everything an operator can verify without invoking an LLM lives here.
IMPORTANT: this package must not import internal/provider or internal/agent. The compiler enforces the MIT/paid product line: nothing in risk_evidence depends on a provider adapter, a model, or an API key. If a contributor needs LLM context to compute a risk signal, that signal does not belong in this package.
Index ¶
Constants ¶
const MaxHighRiskFunctionsReported = 50
MaxHighRiskFunctionsReported caps how many high-risk functions land in RiskEvidence.HighRiskFunctions. The output goes into CI logs and a runaway diff (1000-file rewrite) could otherwise spill thousands of entries. Anything beyond the cap is summarised by the count fields.
const RiskScoreEscalation = 15
RiskScoreEscalation is the per-function score above which the function counts toward the ESCALATION classification. The value matches semantic_firewall's models.RiskScoreHigh so v3-compat scripts that grepped "high risk" entries still trip the same boundary.
Sources of contribution to a function's RiskScore (from the engine at v4.0.0):
Goroutine spawn +15 Each new loop +10 Each new call +5 Panic introduction +5 Defer introduction +3 Each new branch +2 Entropy delta * 3 (high-entropy literal additions)
A single goroutine-add hits the threshold on its own; that is intentional. A goroutine appearing in a "fix typo" commit is the canonical deceptive-commit signal.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Evidence ¶
type Evidence struct {
AddedFunctions int `json:"added_functions"`
ModifiedFunctions int `json:"modified_functions"`
RemovedFunctions int `json:"removed_functions"`
HighRiskFunctions []FunctionRisk `json:"high_risk_functions"`
SignatureHits []SignatureHit `json:"signature_hits"`
DeterministicVerdict Verdict `json:"deterministic_verdict"`
}
Evidence is the full deterministic side of the audit output. Populated entirely from api.DiffOutput plus (later) signature scan results -- no LLM call required.
func FromDiff ¶
func FromDiff(diff *models.DiffOutput) Evidence
FromDiff builds an Evidence record from the diff output the audit engine pre-computed. The function is total: a nil diff produces a zero-value Evidence with VerdictClean (no diff means no risk to surface). Callers that have signature scan results should call AppendSignatureHits afterwards and then Classify.
type FunctionRisk ¶
type FunctionRisk struct {
Function string `json:"function"`
File string `json:"file,omitempty"`
RiskScore int `json:"risk_score"`
TopologyDelta string `json:"topology_delta,omitempty"`
Status string `json:"status"` // models.Status* constants
}
FunctionRisk is one row in the HighRiskFunctions list. Mirrors the data points an operator would otherwise have to derive by hand from a DiffOutput, surfaced as a flat record.
type SignatureHit ¶
type SignatureHit struct {
Function string `json:"function"`
File string `json:"file,omitempty"`
SignatureID string `json:"signature_id"`
SignatureName string `json:"signature_name"`
Severity string `json:"severity"`
Confidence float64 `json:"confidence"`
}
SignatureHit is a recorded match between a function in the diff and an entry in the signature database. signature_hits is always present in the output -- empty today (no shipped DB), populated when the threat-intel feed is wired up. Schema stability across that transition is intentional.
type Verdict ¶
type Verdict string
Verdict is the deterministic classification reported in risk_evidence.deterministic_verdict. It is the field a math-only operator greps when they ignore llm_assessments entirely.
const ( // VerdictClean: no high-risk function deltas and no signature // hits. The diff may still modify code, but nothing crosses the // ESCALATION threshold and nothing matches a known-malware // signature. VerdictClean Verdict = "CLEAN" // VerdictEscalation: at least one function's risk score crossed // RiskScoreEscalation. The commit introduced new goroutines, // loops, calls, panics, or other control-flow shifts that a // vague commit message would normally hide. VerdictEscalation Verdict = "ESCALATION" // VerdictSignatureMatch: a function's topology matched an entry // in the signature database. Strictly dominant over ESCALATION // when both fire -- a named-pattern match is a stronger claim // than a heuristic score. VerdictSignatureMatch Verdict = "SIGNATURE_MATCH" )
func Classify ¶
Classify is the one place the MIT/paid product boundary is computed. Keep it pure (no side effects, no I/O) so callers can trust the output is a function of its input alone.
Precedence rules:
any SignatureHits -> VerdictSignatureMatch (strictly dominant) any HighRiskFunctions -> VerdictEscalation otherwise -> VerdictClean
Source Files