Documentation
¶
Overview ¶
Package reachability is the Tier-2 reachability query API: it wraps a ports.CallGraphBuilder + the deterministic callgraph domain queries into the service consumers use to turn "is this vulnerable symbol actually called?" into an evidence-backed reachability judgment. It is pure deterministic orchestration – no LLM, no persistence, no engagement state – so it is table-testable with a fake builder.
COVERAGE vs NOT-REACHABLE (the load-bearing distinction): a build error from the builder means the target had NO call-graph coverage (un-buildable module, unsupported language) – the caller must fall back to a lower reachability tier, NEVER record a false "not reachable". A successful build that simply does not reach a symbol is a definitive "not reachable" for that symbol. Analyze surfaces the first as an error and the second as Result{Reachable:false}.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Analysis ¶
Analysis is the outcome of a successful reachability run: the per-symbol verdicts plus the Entrypoints the graph was measured from. Entrypoints is the provenance sealed with the Tier-2 judgment ("proven reachable from these roots") – and a zero-entrypoint analysis is a soft no-coverage signal a consumer may choose to treat as inconclusive rather than definitive. BlindConstructs names analysis-WIDE blind spots (e.g. the target uses reflection anywhere on the reachable surface): they taint EVERY not_reachable verdict from this run, because any of them could be wrong for the same reason, so none may suppress.
type Result ¶
type Result struct {
Symbol string
Reachable bool
Path []string
Provenance *SourceProvenance
BlindConstructs []string
}
Result is one symbol's reachability verdict. Path is the proof – a shortest entrypoint→symbol call chain ("main → … → vulnFunc") – present only when Reachable. Provenance is an optional source declaration location for a lexical proof and is never used as a substitute for Path. BlindConstructs names any reachable-surface construct the analysis could NOT follow while deciding THIS symbol (reflection, dynamic dispatch beyond its bound, cgo, generated code). A not_reachable Result carrying a blind construct is not a sound proof of absence: the coordinator folds it into the claim so it can never drive an OpenVEX not_affected.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service answers reachability queries for a target by building its call graph once and querying it.
func NewService ¶
func NewService(builder ports.CallGraphBuilder) (*Service, error)
NewService validates and returns the reachability service.
func (*Service) Analyze ¶
func (s *Service) Analyze(ctx context.Context, targetRef string, symbols []string) (*Analysis, error)
Analyze builds the target's call graph ONCE, then resolves each symbol to a reachability Result. The symbols are vulnerability AffectedSymbols (the "importPath.Symbol" form the builder emits – no translation). Input order is preserved; duplicate symbols are de-duplicated.
A builder error (or a nil graph from a misbehaving builder) means NO coverage and is returned as an error → the caller falls back to a lower tier, NOT a false "not reachable". A successful, non-nil graph is definitive: every queried symbol gets a Result (Reachable + Path when called).
type SourceProvenance ¶ added in v0.2.0
SourceProvenance identifies a declaration in source. ModulePath is a slash-separated path relative to the analyzed root and Line is one-based. It never carries an absolute or parent-traversing path into evidence.
func NormalizeSourceProvenance ¶ added in v0.2.0
func NormalizeSourceProvenance(value SourceProvenance) (SourceProvenance, bool)
NormalizeSourceProvenance validates and normalizes a source declaration location before it reaches a reachability result or capture evidence. Invalid locations are omitted rather than exposing a private root.
Source Files