graphfrag

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2026 License: GPL-2.0, GPL-2.0-only Imports: 7 Imported by: 0

Documentation

Overview

Package graphfrag — schema-5.x JSON converter.

ToCallgraphExport projects a stitched Result into the schema-5.x JSON shape used by crypto-finder's customer-facing callgraph export (and consumed by the mining-service render layer). The schema-5.x structs are intentionally duplicated here as exported types: they are pkg/graphfrag's public contract for the serving path, keeping the package's schema+semantics together with their owner.

Relationship to internal/scan/export.go: the unexported callGraphChainNode, callGraphEntryCall, etc. types in export.go share the same JSON field names and semantics. This file is the promoted copy for the stitched/serving path.

Package graphfrag is crypto-finder's public contract for reusable component graph fragments: the structural call-graph + rules-versioned crypto annotations that `crypto-finder scan --export-graph-fragment` emits for a single component, plus the pure stitcher that composes a dependency closure of those fragments into root-to-crypto reachability chains.

Why this lives in crypto-finder (not a downstream service): the graph fragment schema and the resolution-quality semantics are crypto-finder's public contract — the scanner produces them, so the rules for consuming them (which edges may extend a chain) belong with the contract owner. A reimplementation in a downstream catalog/mining service would drift the moment the schema bumps. Mirrors the rationale of pkg/stitch.

The package is intentionally dependency-light: it does NOT import the scanner or callgraph builder, read storage, or gzip. Inputs are exported fragments (or decoded Fragments); the caller fetches and decompresses them.

Index

Constants

View Source 
const (
	// SuppressReasonUnknown: an edge had no resolution kind (producer bug or an
	// intentionally untrusted edge).
	SuppressReasonUnknown = "unknown_resolution"
	// SuppressReasonNameOnly: a name+arity guess with no receiver type anchor.
	SuppressReasonNameOnly = "name_only"
	// SuppressReasonAmbiguousDispatch: an interface call site with more than one
	// concrete implementation present in the current component's direct dependencies.
	SuppressReasonAmbiguousDispatch = "interface_dispatch_ambiguous"
)

Suppression reasons recorded on a SuppressedEdge.

View Source 
const ConfidenceHigh = "high"

ConfidenceHigh is the confidence of every chain emitted under the default fail-closed policy (only exact and unique-implementation interface edges are traversed). The constant exists so a future opt-in mode can surface lower-confidence chains explicitly.

View Source 
const FindingsSchemaVersion = "1.3"

FindingsSchemaVersion is the findings.json envelope version emitted by ToFindingsEnvelope. It matches the schema crypto-finder's scanner writes so downstream consumers see a uniform `version` regardless of whether the findings came from a live scan or were reconstructed from graph fragments.

View Source 
const SchemaVersion = "graph-fragment-1.2"

SchemaVersion is the current graph-fragment export schema version.

1.1 added per-edge resolution metadata (resolution / declared_type / method_name / arity) on internal_edges and external_calls. The fields are additive: a 1.0 fragment decodes with an empty resolution, which the stitcher treats as untrusted (fail-closed).

1.2 adds per-edge call-site data-flow (entry_call on internal_edges and external_calls) and full crypto-call identity + asset metadata on crypto_annotations. All additions are additive: a 1.1 fragment decodes with nil entry_call / nil CryptoCall fields, which the stitcher degrades to structural-only chains (safe fail-closed behavior).

Variables

This section is empty.

Functions

This section is empty.

Types

type CallFrame 

type CallFrame struct {
	Component ComponentKey
	// Signature is the function key (fragment edge join key).
	Signature string
	// Function carries the full rich identity of this node (1.2+).
	Function Function
	// EntryCall is the call-site data-flow for the edge that led to this frame (1.2+).
	EntryCall *CallSite
	// Module is the fragment's root module string (e.g. "net.crypto:lib"), used
	// to stamp dependency_info.module at projection time.
	Module string
}

CallFrame is one frame in a stitched path.

Signature is the fragment key used internally for graph traversal (matches Function.Signature on the resolved node). Function carries the full identity of the resolved node (1.2+; zero-value on legacy fragments). EntryCall is the call-site argument data-flow for the edge traversed to ARRIVE at this frame from the previous frame (nil on the root frame and on legacy fragments). Module is the Maven/npm/etc. module string for the component (from Fragment.Module), carried here so dependency_info can be stamped at projection time without re-reading the original fragment.

type CallSite added in v0.7.0 

type CallSite struct {
	// Line is the source line of the call expression in the caller.
	Line int
	// Parameters carries the resolved argument data-flow for each positional argument.
	Parameters []Parameter
}

CallSite carries the per-edge call-site invocation detail: the line number and the resolved argument data-flow for each positional argument passed by the caller at this edge. Mirrors the schema-5.x entry_call shape.

type CallgraphExport added in v0.7.0 

type CallgraphExport struct {
	SchemaVersion   string               `json:"schema_version"`
	ScanMetadata    ExportScanMeta       `json:"scan_metadata"`
	FindingGraphs   []ExportFindingGraph `json:"finding_graphs"`
	EntryPointIndex []ExportEntryPoint   `json:"entry_point_index,omitempty"`
}

CallgraphExport is the schema-5.x JSON envelope produced by ToCallgraphExport. It mirrors the callGraphExportV2 shape in internal/scan/export.go.

type ComponentKey 

type ComponentKey struct {
	Purl    string
	Version string
}

ComponentKey identifies one mined component version.

func (ComponentKey) String 

func (k ComponentKey) String() string

type CryptoCall added in v0.7.0 

type CryptoCall struct {
	// FunctionName is the fully qualified function name of the matched crypto call.
	FunctionName string
	// CanonicalSignature is the canonical function signature.
	CanonicalSignature string
	// ReturnType is the declared return type.
	ReturnType string
	// ParameterTypes lists the declared parameter types.
	ParameterTypes []string
	// Line is the source line of the matched crypto call.
	Line int
	// Parameters carries the resolved argument data-flow.
	Parameters []Parameter
}

CryptoCall carries the identity and call-site argument data-flow of a matched crypto invocation. It is stored on CryptoOperation (1.2+) and mirrors the schema-5.x callGraphCalledFunction shape.

type CryptoOperation 

type CryptoOperation struct {
	Function  string
	FindingID string
	RuleID    string
	Symbol    string

	// FilePath is the source file path (relative to the component root) where
	// the crypto finding was detected. Used by the callgraph exporter to recompute
	// finding_id with a dep-prefix when the op belongs to a non-root component.
	// Populated from graph-fragment-1.2+ exports; empty on legacy fragments.
	FilePath string
	// StartLine is the source line of the crypto finding. Together with FilePath
	// and RuleID it is the input to the finding_id hash:
	//   sha256(path + ":" + startLine + ":" + ruleID)[:8]
	// where path is prefixed with "module@version/" for dep components.
	StartLine int
	// EndLine is the last source line of the crypto finding (often == StartLine
	// for single-line detections). Carried through so the serving layer can emit
	// the findings.json `end_line` field. Populated from graph-fragment-1.2+.
	EndLine int
	// Match is the exact source expression that triggered the detection (the
	// findings.json `match` field), e.g. `Cipher.getInstance("AES")`. Carried
	// through so the serving layer can emit it. Populated from graph-fragment-1.2+.
	Match string

	// CryptoCall carries the identity and argument data-flow of the matched
	// crypto invocation (1.2+).
	CryptoCall *CryptoCall
	// OID is the Object Identifier for the cryptographic algorithm (1.2+).
	OID string
	// Metadata is the raw asset metadata block from the scanner (1.2+).
	// Stored verbatim so the serving layer can pass it through without re-serialization.
	Metadata json.RawMessage
	// Source indicates how the finding was discovered: "direct" or "indirect" (1.2+).
	Source string
	// MatchedOperation records the kind/symbol/expression of the matched crypto
	// operation (1.2+).
	MatchedOperation *MatchedOp
}

CryptoOperation is a crypto finding attached to a function.

The rich fields (CryptoCall, OID, Metadata, Source, MatchedOperation) are populated from graph-fragment-1.2+ exports. They are zero/nil on legacy fragments — the stitcher still emits structural chains, just without data-flow / asset metadata (safe degradation).

type DependencyGraph 

type DependencyGraph map[ComponentKey][]ComponentKey

DependencyGraph is the authoritative component-version graph resolved from build metadata. Stitching only crosses into components reachable through this graph, even if extra fragments are available in storage.

type ErrMissingFragment 

type ErrMissingFragment struct {
	Components []ComponentKey
}

ErrMissingFragment means the dependency closure references components whose graph fragments are absent. The stitcher fails closed instead of returning a partial graph.

func (*ErrMissingFragment) Error 

func (e *ErrMissingFragment) Error() string

type ExportChainNode added in v0.7.0 

type ExportChainNode struct {
	// FunctionName is the human-readable fully qualified function name.
	FunctionName string `json:"function_name"`
	// CanonicalSignature is the canonical function signature.
	CanonicalSignature string `json:"canonical_signature,omitempty"`
	// ReturnType is the declared return type.
	ReturnType string `json:"return_type,omitempty"`
	// ParameterTypes lists the declared parameter types.
	ParameterTypes []string `json:"parameter_types,omitempty"`
	// Visibility is the access modifier.
	Visibility string `json:"visibility,omitempty"`
	// OwnerVisibility is the access modifier of the enclosing type.
	OwnerVisibility string `json:"owner_visibility,omitempty"`
	// FilePath is the source file path.
	FilePath string `json:"file_path"`
	// StartLine is the first line of the function body.
	StartLine int `json:"start_line,omitempty"`
	// DependencyInfo is stamped for non-root frames. Nil for root-component frames.
	DependencyInfo *ExportDependencyInfo `json:"dependency_info,omitempty"`
	// EntryCall is the call-site data-flow for the edge that led to this frame.
	// Nil on the root frame and on frames derived from legacy 1.0/1.1 fragments.
	EntryCall *ExportEntryCall `json:"entry_call,omitempty"`
	// CryptoCall is the matched crypto invocation, present only on the terminal frame.
	CryptoCall *ExportCryptoCall `json:"crypto_call,omitempty"`
}

ExportChainNode is one node in a schema-5.x call chain. It mirrors callGraphChainNode in internal/scan/export.go.

type ExportCryptoCall added in v0.7.0 

type ExportCryptoCall struct {
	// FunctionName is the fully qualified matched crypto function name.
	FunctionName string `json:"function_name"`
	// CanonicalSignature is the canonical signature.
	CanonicalSignature string `json:"canonical_signature,omitempty"`
	// ReturnType is the declared return type.
	ReturnType string `json:"return_type,omitempty"`
	// ParameterTypes lists the declared parameter types.
	ParameterTypes []string `json:"parameter_types,omitempty"`
	// Line is the source line of the matched crypto call.
	Line int `json:"line"`
	// Parameters carries the resolved argument data-flow.
	Parameters []ExportParameter `json:"parameters,omitempty"`
}

ExportCryptoCall is the schema-5.x crypto_call shape on the terminal node. It mirrors callGraphCalledFunction in internal/scan/export.go.

type ExportDependencyInfo added in v0.7.0 

type ExportDependencyInfo struct {
	Module  string `json:"module"`
	Version string `json:"version,omitempty"`
}

ExportDependencyInfo mirrors the schema-5.x dependency_info shape. It is stamped on non-root frames using the frame's Component module string.

type ExportEntryCall added in v0.7.0 

type ExportEntryCall struct {
	// FunctionName is the fully qualified callee function name.
	FunctionName string `json:"function_name,omitempty"`
	// CanonicalSignature is the callee's canonical signature.
	CanonicalSignature string `json:"canonical_signature,omitempty"`
	// ReturnType is the callee's declared return type.
	ReturnType string `json:"return_type,omitempty"`
	// ParameterTypes lists the callee's declared parameter types.
	ParameterTypes []string `json:"parameter_types,omitempty"`
	// Line is the source line in the caller where the call is made.
	Line int `json:"line,omitempty"`
	// Parameters carries the resolved argument data-flow.
	Parameters []ExportParameter `json:"parameters,omitempty"`
}

ExportEntryCall is the schema-5.x entry_call shape on a chain node. It carries the caller's invocation detail for the edge that led to this frame.

type ExportEntryPoint added in v0.7.0 

type ExportEntryPoint struct {
	// Function is the fully qualified function name.
	Function string `json:"function"`
	// CanonicalSignature is the canonical function signature.
	CanonicalSignature string `json:"canonical_signature,omitempty"`
	// Class is the enclosing class name.
	Class string `json:"class,omitempty"`
	// Method is the simple method name.
	Method string `json:"method"`
	// ReturnType is the declared return type.
	ReturnType string `json:"return_type,omitempty"`
	// ParameterTypes lists the declared parameter types.
	ParameterTypes []string `json:"parameter_types,omitempty"`
	// Visibility is the access modifier.
	Visibility string `json:"visibility,omitempty"`
	// OwnerVisibility is the access modifier of the enclosing type.
	OwnerVisibility string `json:"owner_visibility,omitempty"`
	// ReachableFindings lists all crypto findings reachable from this entry point.
	ReachableFindings []ExportReachableFinding `json:"reachable_findings"`
}

ExportEntryPoint is one entry in the entry_point_index. It mirrors callGraphEntryPoint in internal/scan/export.go.

type ExportFindingGraph added in v0.7.0 

type ExportFindingGraph struct {
	// FindingID is the crypto finding identifier.
	FindingID string `json:"finding_id"`
	// MatchedOperation carries the kind/symbol/expression of the matched crypto op.
	MatchedOperation *ExportMatchedOperation `json:"matched_operation,omitempty"`
	// CallChains is the set of surviving root-to-crypto paths for this finding.
	CallChains [][]ExportChainNode `json:"call_chains,omitempty"`
}

ExportFindingGraph groups all surviving chains for one crypto finding.

type ExportMatchedOperation added in v0.7.0 

type ExportMatchedOperation struct {
	Kind       string `json:"kind"`
	Symbol     string `json:"symbol,omitempty"`
	Expression string `json:"expression,omitempty"`
	Line       int    `json:"line,omitempty"`
}

ExportMatchedOperation mirrors the schema-5.x matched_operation shape.

type ExportParameter added in v0.7.0 

type ExportParameter struct {
	ParameterIndex     int                `json:"parameter_index"`
	Type               string             `json:"type,omitempty"`
	VariableName       string             `json:"variable_name,omitempty"`
	ArgumentExpression string             `json:"argument_expression,omitempty"`
	ResolvedValue      string             `json:"resolved_value,omitempty"`
	SourceNodes        []ExportSourceNode `json:"source_nodes,omitempty"`
}

ExportParameter is the schema-5.x callGraphParameter shape.

type ExportReachableFinding added in v0.7.0 

type ExportReachableFinding struct {
	// FindingID is the crypto finding identifier.
	FindingID string `json:"finding_id"`
	// MatchedOperation carries kind/symbol for the finding.
	MatchedOperation *ExportMatchedOperation `json:"matched_operation"`
	// ChainDepth is the number of frames from this entry point to the crypto sink.
	// Shallowest depth wins when the same finding is reachable via multiple chains.
	ChainDepth int `json:"chain_depth"`
	// FindingGraphRef is the finding_id cross-reference.
	FindingGraphRef string `json:"finding_graph_ref"`
}

ExportReachableFinding is one reachable crypto finding entry inside an ExportEntryPoint.

type ExportScanMeta added in v0.7.0 

type ExportScanMeta struct {
	Ecosystem  string `json:"ecosystem,omitempty"`
	RootModule string `json:"root_module,omitempty"`
}

ExportScanMeta is the scan_metadata block inside a CallgraphExport.

type ExportSourceLoc added in v0.7.0 

type ExportSourceLoc struct {
	FilePath string `json:"file_path,omitempty"`
	Line     int    `json:"line,omitempty"`
}

ExportSourceLoc is a source location reference.

type ExportSourceNode added in v0.7.0 

type ExportSourceNode struct {
	Type           string             `json:"type"`
	Name           string             `json:"name,omitempty"`
	DeclaredType   string             `json:"declared_type,omitempty"`
	Value          string             `json:"value,omitempty"`
	ParameterIndex *int               `json:"parameter_index,omitempty"`
	CallTarget     string             `json:"call_target,omitempty"`
	Location       *ExportSourceLoc   `json:"location,omitempty"`
	SourceNodes    []ExportSourceNode `json:"source_nodes,omitempty"`
}

ExportSourceNode is the schema-5.x exportSourceNode shape. The SourceNodes field makes it recursive so PARAMETER→CALL_RESULT chains are preserved.

type ExternalCall 

type ExternalCall struct {
	Caller          string
	TargetSignature string

	// Resolution classifies how the producer resolved TargetSignature. The zero
	// value (ResolutionUnknown) is fail-closed: the stitcher will not traverse it.
	Resolution ResolutionKind

	// DeclaredType is the static/interface type observed at the call site (e.g.
	// the interface whose method was dispatched). Provenance plus part of the
	// dispatch-group identity used to detect ambiguous interface dispatch.
	DeclaredType string

	// MethodName and Arity identify the invoked method independently of the
	// resolved target, so sibling candidates of one ambiguous call site can be
	// grouped together.
	MethodName string
	Arity      int

	// CallSite is the source line of the call expression. Together with Caller,
	// MethodName, and Arity it discriminates distinct call sites that happen to
	// share a method name within the same caller.
	CallSite int

	// EntryCall carries the call-site argument data-flow for this edge (1.2+).
	// Nil on fragments exported with schema < 1.2.
	EntryCall *CallSite
}

ExternalCall is a call from this component to a function whose implementation may live in another component from the dependency graph.

type FindingAsset added in v0.7.0 

type FindingAsset struct {
	FindingID string          `json:"finding_id"`
	OID       string          `json:"oid,omitempty"`
	Match     string          `json:"match"`
	Source    string          `json:"source"`
	StartLine int             `json:"start_line"`
	EndLine   int             `json:"end_line"`
	Metadata  json.RawMessage `json:"metadata,omitempty"`
}

FindingAsset is one cryptographic asset, mirroring a findings.json `cryptographic_assets[]` entry. Metadata is the verbatim camelCase block.

type FindingChain 

type FindingChain struct {
	FindingID string
	RuleID    string
	Symbol    string
	Frames    []CallFrame

	// Confidence is the weakest-link confidence of the traversed edges. Under
	// the default policy this is always ConfidenceHigh.
	Confidence string

	// CryptoOp carries the full crypto operation from the terminal frame (1.2+).
	// Populated by the stitcher from the fragment's CryptoOperation for the
	// terminal node so the converter can emit crypto_call without re-reading the
	// fragments.
	CryptoOp *CryptoOperation
}

FindingChain is one root-to-crypto path.

type FindingFile added in v0.7.0 

type FindingFile struct {
	Language            string         `json:"language"`
	FilePath            string         `json:"file_path"`
	CryptographicAssets []FindingAsset `json:"cryptographic_assets"`
}

FindingFile is one file-level grouping in the envelope, mirroring a findings.json `findings[]` entry.

type FindingsEnvelope added in v0.7.0 

type FindingsEnvelope struct {
	Version  string        `json:"version"`
	Findings []FindingFile `json:"findings"`
}

FindingsEnvelope is the findings.json v1.3 envelope reconstructed from a dependency closure of graph fragments. It is the asset-metadata companion to ToCallgraphExport: the serving layer joins assets (here) to call chains (callgraph export) by finding_id, so the two MUST agree on finding_id — which they do by construction, since both derive it from the same CryptoOperation fields via computeFindingID/depPrefixedPath.

func ToFindingsEnvelope added in v0.7.0 

func ToFindingsEnvelope(root ComponentKey, deps DependencyGraph, fragments map[ComponentKey]Fragment, meta ScanMeta) FindingsEnvelope

ToFindingsEnvelope reconstructs the findings.json v1.3 envelope for the root component and its transitive dependency closure, from the stored crypto annotations in each fragment. Unlike ToCallgraphExport (which emits only reachable findings), this emits EVERY crypto operation in the closure — reachability decoration is the serving layer's job.

finding_id, file_path, and source are computed to match a live `--scan-dependencies` run:

  • root-component ops: unprefixed file_path, source="direct".
  • dependency ops: file_path prefixed with "module@version/", source="indirect".

finding_id is computed with the SAME inputs as ToCallgraphExport (computeFindingID over the resolved path + start_line + rule_id), so the serving layer's asset->call_chains join by finding_id holds.

type Fragment 

type Fragment struct {
	Component ComponentKey
	Module    string

	Functions        []Function
	InternalEdges    []InternalEdge
	ExternalCalls    []ExternalCall
	CryptoOperations []CryptoOperation
}

Fragment is one reusable structural graph fragment plus rules-versioned crypto annotations for a single component version. The production storage layer may split this into structural graph blobs and separate crypto annotation blobs, but the stitcher consumes the combined view.

func DecodeFragment 

func DecodeFragment(component ComponentKey, data []byte) (Fragment, error)

DecodeFragment parses one graph-fragment export (JSON) into a Fragment for the given component. Legacy fragments exported before the resolution fields existed decode to ResolutionUnknown, which the stitcher fails closed on — safe under-reporting, never a false positive.

type Function 

type Function struct {
	// Signature is the fragment's function key used by edges (e.g. "org.bridge.(Bridge).bridge#0").
	Signature string
	// FunctionName is the fully-qualified human-readable function name (e.g. "org.bridge.Bridge.bridge").
	FunctionName string
	// CanonicalSignature is the canonical function signature (1.2+).
	CanonicalSignature string
	// ReturnType is the declared return type (1.2+).
	ReturnType string
	// ParameterTypes lists the declared parameter types in order (1.2+).
	ParameterTypes []string
	// Visibility is the declared access modifier of the function (1.2+).
	Visibility string
	// OwnerVisibility is the declared access modifier of the enclosing type (1.2+).
	OwnerVisibility string
	// StartLine is the first source line of the function body (1.2+).
	StartLine int
	// FilePath is the source file path, relative to the component root.
	FilePath string
}

Function identifies one callable node inside a component graph.

The Signature field (the fragment's function key, e.g. "org.bridge.(Bridge).bridge#0") is the join key for edge resolution. The richer identity fields below are populated from graph-fragment-1.2+ exports so the stitcher can emit them verbatim in the schema-5.x output (callgraph_export.go). They are zero-value on legacy 1.0/1.1 fragments — graceful degradation.

type GraphFragmentCallSite added in v0.7.0 

type GraphFragmentCallSite struct {
	// Line is the source line of the call expression in the caller.
	Line int `json:"line,omitempty"`
	// Parameters carries the resolved argument data-flow for each positional
	// argument in the call.
	Parameters []GraphFragmentParameter `json:"parameters,omitempty"`
}

GraphFragmentCallSite carries the per-edge call-site invocation detail: the arguments the caller passed to the callee at this edge, mirroring the schema-5.x entry_call shape. It lives on the edge (not the function) because entry_call describes the caller→callee invocation.

type GraphFragmentCryptoCall added in v0.7.0 

type GraphFragmentCryptoCall struct {
	// FunctionName is the fully qualified function name of the matched crypto call.
	FunctionName string `json:"function_name,omitempty"`
	// CanonicalSignature is the canonical function signature.
	CanonicalSignature string `json:"canonical_signature,omitempty"`
	// ReturnType is the declared return type.
	ReturnType string `json:"return_type,omitempty"`
	// ParameterTypes lists the declared parameter types.
	ParameterTypes []string `json:"parameter_types,omitempty"`
	// Line is the source line of the matched crypto call.
	Line int `json:"line,omitempty"`
	// Parameters carries the resolved argument data-flow for each positional argument.
	Parameters []GraphFragmentParameter `json:"parameters,omitempty"`
}

GraphFragmentCryptoCall carries the identity and argument data-flow of the matched crypto invocation, mirroring the schema-5.x callGraphCalledFunction shape. It is a dedicated type (not reusing GraphFragmentCallSite) so it can carry function identity fields alongside the call-site parameters.

type GraphFragmentCryptoOp 

type GraphFragmentCryptoOp struct {
	FunctionKey string `json:"function_key,omitempty"`
	FindingID   string `json:"finding_id,omitempty"`
	RuleID      string `json:"rule_id,omitempty"`
	Symbol      string `json:"symbol,omitempty"`
	Expression  string `json:"expression,omitempty"`
	FilePath    string `json:"file_path,omitempty"`
	StartLine   int    `json:"start_line,omitempty"`
	EndLine     int    `json:"end_line,omitempty"`
	// CryptoCall carries the identity and argument data-flow of the matched
	// crypto invocation (1.2+). Nil on fragments exported with schema < 1.2.
	CryptoCall *GraphFragmentCryptoCall `json:"crypto_call,omitempty"`
	// OID is the Object Identifier for the cryptographic algorithm (1.2+).
	OID string `json:"oid,omitempty"`
	// Metadata is the raw asset metadata block from the scanner (1.2+).
	// It is stored verbatim so the stitcher can pass it through to the render
	// layer without re-serialization.
	Metadata json.RawMessage `json:"metadata,omitempty"`
	// Source indicates how the finding was discovered: "direct" or "indirect" (1.2+).
	Source string `json:"source,omitempty"`
	// MatchedOperation records the kind/symbol/expression of the matched crypto
	// operation (1.2+). Mirrors the schema-5.x matched_operation shape.
	MatchedOperation *GraphFragmentMatchedOp `json:"matched_operation,omitempty"`
}

GraphFragmentCryptoOp is one crypto finding annotation attached to a function in the exported graph fragment.

type GraphFragmentEdge 

type GraphFragmentEdge struct {
	CallerKey    string `json:"caller_key"`
	CalleeKey    string `json:"callee_key"`
	Line         int    `json:"line,omitempty"`
	Resolution   string `json:"resolution"`
	DeclaredType string `json:"declared_type,omitempty"`
	MethodName   string `json:"method_name,omitempty"`
	Arity        int    `json:"arity,omitempty"`
	// EntryCall carries the call-site argument data-flow for this edge (1.2+).
	// Nil on fragments exported with schema < 1.2.
	EntryCall *GraphFragmentCallSite `json:"entry_call,omitempty"`
}

GraphFragmentEdge is one internal (intra-component) call edge plus the resolution metadata that lets a consumer decide whether to traverse it.

type GraphFragmentExport 

type GraphFragmentExport struct {
	SchemaVersion     string                    `json:"schema_version"`
	ScanMetadata      GraphFragmentScanMetadata `json:"scan_metadata"`
	Functions         []GraphFragmentFunction   `json:"functions"`
	InternalEdges     []GraphFragmentEdge       `json:"internal_edges,omitempty"`
	ExternalCalls     []GraphFragmentExternal   `json:"external_calls,omitempty"`
	CryptoAnnotations []GraphFragmentCryptoOp   `json:"crypto_annotations,omitempty"`
}

GraphFragmentExport is the on-the-wire JSON shape emitted by `crypto-finder scan --export-graph-fragment` for a single component. It is crypto-finder's public contract; the scanner (internal/scan) builds it from a callgraph, and any consumer decodes it into a Fragment via DecodeFragment.

func (GraphFragmentExport) ToFragment 

func (e GraphFragmentExport) ToFragment(component ComponentKey) Fragment

ToFragment projects an exported graph fragment onto the stitch model for the given component. The component key is supplied by the caller because the export carries source-level identity (module, function keys) but not the (purl, version) it was requested for.

All graph-fragment-1.2 fields (CanonicalSignature, EntryCall, CryptoCall, asset metadata) are mapped when present. Legacy 1.0/1.1 fragments decode with nil/zero for the new fields — safe structural-only degradation.

type GraphFragmentExternal 

type GraphFragmentExternal struct {
	CallerKey          string `json:"caller_key"`
	TargetKey          string `json:"target_key"`
	TargetFunctionName string `json:"target_function_name,omitempty"`
	Raw                string `json:"raw,omitempty"`
	Line               int    `json:"line,omitempty"`
	Resolution         string `json:"resolution"`
	DeclaredType       string `json:"declared_type,omitempty"`
	MethodName         string `json:"method_name,omitempty"`
	Arity              int    `json:"arity,omitempty"`
	// EntryCall carries the call-site argument data-flow for this edge (1.2+).
	// Nil on fragments exported with schema < 1.2.
	EntryCall *GraphFragmentCallSite `json:"entry_call,omitempty"`
}

GraphFragmentExternal is one external (cross-component) call edge plus its resolution metadata.

type GraphFragmentFunction 

type GraphFragmentFunction struct {
	Key                string          `json:"key"`
	FunctionName       string          `json:"function_name"`
	CanonicalSignature string          `json:"canonical_signature,omitempty"`
	Package            string          `json:"package,omitempty"`
	Type               string          `json:"type,omitempty"`
	Name               string          `json:"name,omitempty"`
	FilePath           string          `json:"file_path,omitempty"`
	StartLine          int             `json:"start_line,omitempty"`
	EndLine            int             `json:"end_line,omitempty"`
	ReturnType         string          `json:"return_type,omitempty"`
	ParameterTypes     []string        `json:"parameter_types,omitempty"`
	Visibility         string          `json:"visibility,omitempty"`
	OwnerVisibility    string          `json:"owner_visibility,omitempty"`
	InferredReturn     json.RawMessage `json:"-"`
}

GraphFragmentFunction is one function declaration included in a component's graph-fragment export.

type GraphFragmentMatchedOp added in v0.7.0 

type GraphFragmentMatchedOp struct {
	// Kind is the operation kind: "call", "type_usage", or "expression".
	Kind string `json:"kind,omitempty"`
	// Symbol is the fully qualified API symbol (e.g., "javax.crypto.Cipher.getInstance").
	Symbol string `json:"symbol,omitempty"`
	// Expression is the raw source expression that matched.
	Expression string `json:"expression,omitempty"`
	// Line is the source line of the matched expression.
	Line int `json:"line,omitempty"`
}

GraphFragmentMatchedOp records the matched operation kind, symbol, and expression for a crypto finding — the same fields carried by the schema-5.x matched_operation shape.

type GraphFragmentParameter added in v0.7.0 

type GraphFragmentParameter struct {
	// ParameterIndex is the 0-based position of this argument in the call.
	ParameterIndex int `json:"parameter_index"`
	// Type is the declared parameter type in the callee's signature.
	Type string `json:"type,omitempty"`
	// VariableName is the local variable name if the argument was a simple identifier.
	VariableName string `json:"variable_name,omitempty"`
	// ArgumentExpression is the raw source text of the argument expression.
	ArgumentExpression string `json:"argument_expression,omitempty"`
	// ResolvedValue is a simplified literal value when it can be statically resolved.
	ResolvedValue string `json:"resolved_value,omitempty"`
	// SourceNodes carries the data-flow provenance for this argument.
	SourceNodes []GraphFragmentSourceNode `json:"source_nodes,omitempty"`
}

GraphFragmentParameter mirrors the schema-5.x callGraphParameter shape so the stitcher can emit entry_call.parameters[] verbatim.

type GraphFragmentScanMetadata 

type GraphFragmentScanMetadata struct {
	Ecosystem     string `json:"ecosystem,omitempty"`
	RootModule    string `json:"root_module,omitempty"`
	ToolName      string `json:"tool_name,omitempty"`
	ToolVersion   string `json:"tool_version,omitempty"`
	RulesVersion  string `json:"rules_version,omitempty"`
	ExportedAt    string `json:"exported_at"`
	FunctionCount int    `json:"function_count"`
	InternalEdges int    `json:"internal_edge_count"`
	ExternalCalls int    `json:"external_call_count"`
	CryptoOps     int    `json:"crypto_operation_count"`
}

GraphFragmentScanMetadata summarizes the scan that produced a graph-fragment export and the payload counts emitted for that component.

type GraphFragmentSourceLoc added in v0.7.0 

type GraphFragmentSourceLoc struct {
	FilePath string `json:"file_path,omitempty"`
	Line     int    `json:"line,omitempty"`
}

GraphFragmentSourceLoc identifies a position in source code.

type GraphFragmentSourceNode added in v0.7.0 

type GraphFragmentSourceNode struct {
	// Type classifies the origin: VALUE, VARIABLE, FIELD, PARAMETER, CALL_RESULT, EXPRESSION.
	Type string `json:"type"`
	// Name is the variable/field/parameter name.
	Name string `json:"name,omitempty"`
	// DeclaredType is the type if known.
	DeclaredType string `json:"declared_type,omitempty"`
	// Value is the actual value for VALUE nodes.
	Value string `json:"value,omitempty"`
	// ParameterIndex is set for PARAMETER nodes.
	ParameterIndex *int `json:"parameter_index,omitempty"`
	// CallTarget is set for CALL_RESULT nodes — the function that produced the value.
	CallTarget string `json:"call_target,omitempty"`
	// Location is where this source is defined.
	Location *GraphFragmentSourceLoc `json:"location,omitempty"`
	// SourceNodes traces where THIS node's value came from (recursive).
	SourceNodes []GraphFragmentSourceNode `json:"source_nodes,omitempty"`
}

GraphFragmentSourceNode is the recursive data-flow provenance node, mirroring the schema-5.x exportSourceNode shape. The SourceNodes field makes this type recursive so PARAMETER→CALL_RESULT chains are fully preserved.

type InternalEdge 

type InternalEdge struct {
	Caller string
	Callee string

	// Resolution classifies how the producer resolved Callee. Zero value
	// (ResolutionUnknown) is fail-closed.
	Resolution ResolutionKind

	// DeclaredType, MethodName, Arity, CallSite mirror ExternalCall and identify
	// the dispatched method / call site for ambiguity grouping.
	DeclaredType string
	MethodName   string
	Arity        int
	CallSite     int

	// EntryCall carries the call-site argument data-flow for this edge (1.2+).
	// Nil on fragments exported with schema < 1.2.
	EntryCall *CallSite
}

InternalEdge connects two functions inside the same component fragment.

Internal edges carry the same resolution metadata as ExternalCall: an interface or fluent call resolved by name+arity can land on a co-located implementation just as easily as a cross-component one, so it must be gated by the same policy. The dispatch-group identity (Caller + CallSite + MethodName + Arity) is shared with ExternalCall so that siblings of one call site that span the component boundary are judged together.

type MatchedOp added in v0.7.0 

type MatchedOp struct {
	// Kind is the operation kind: "call", "type_usage", or "expression".
	Kind string
	// Symbol is the fully qualified API symbol.
	Symbol string
	// Expression is the raw source expression that matched.
	Expression string
	// Line is the source line of the matched expression.
	Line int
}

MatchedOp records the matched operation kind, symbol, and expression for a crypto finding — the same fields carried by the schema-5.x matched_operation.

type Parameter added in v0.7.0 

type Parameter struct {
	// ParameterIndex is the 0-based position of this argument.
	ParameterIndex int
	// Type is the declared parameter type in the callee's signature.
	Type string
	// VariableName is the local variable name if the argument was a simple identifier.
	VariableName string
	// ArgumentExpression is the raw source text of the argument expression.
	ArgumentExpression string
	// ResolvedValue is a simplified literal value when statically resolvable.
	ResolvedValue string
	// SourceNodes carries the data-flow provenance for this argument (recursive).
	SourceNodes []SourceNode
}

Parameter is one positional argument at a call site, including any resolved data-flow provenance. Mirrors the schema-5.x callGraphParameter shape.

type ResolutionKind 

type ResolutionKind string

ResolutionKind classifies how confidently the producer resolved a call to its target. The stitcher uses this to decide whether an edge is allowed to extend a reachability chain. The zero value is ResolutionUnknown, which is treated as untrusted: the stitcher fails closed rather than guessing.

This is the central guard against over-broad dispatch false positives. An interface or fluent call resolved purely by method name + arity (no receiver type anchor) must never be presented as typed reachability proof. 

const (
	// ResolutionUnknown is the zero value: the producer did not classify the
	// edge. Treated as untrusted and never traversed. Its presence usually means
	// a producer bug (an edge exported without a resolution kind).
	ResolutionUnknown ResolutionKind = ""

	// ResolutionExact means the receiver's static type was known and the method
	// resolved to a unique declared target on that type (or an overload set on
	// that exact type). Always traversed.
	ResolutionExact ResolutionKind = "exact"

	// ResolutionInterfaceDispatch means the target was found by expanding an
	// interface/abstract method to concrete implementations matching name+arity
	// within a namespace root. Trusted ONLY when exactly one implementation is
	// present in the current component's direct dependencies; ambiguous (>1)
	// call sites fail closed.
	ResolutionInterfaceDispatch ResolutionKind = "interface_dispatch"

	// ResolutionNameOnly means the target was guessed by method name + arity
	// (plus namespace heuristics) with no receiver type anchor — e.g. fluent
	// fallback. Never traversed.
	ResolutionNameOnly ResolutionKind = "name_only"
)

type Result 

type Result struct {
	Chains []FindingChain

	// Suppressed records call edges the policy refused to traverse. It is the
	// audit trail for fail-closed decisions and the data source for a future
	// opt-in "show me the uncertain paths too" mode. It never affects Chains.
	Suppressed []SuppressedEdge
}

Result is the stitched reachability output in its minimal semantic form. Rendering into crypto-finder's customer-facing callgraph schema is a later adapter concern.

func Stitch 

func Stitch(root ComponentKey, deps DependencyGraph, fragments map[ComponentKey]Fragment) (*Result, error)

Stitch composes reusable component graph fragments into root-to-crypto reachability chains for root.

This is the pure graph algorithm. It deliberately does not know about storage, compression, or HTTP response DTOs.

func (*Result) ToCallgraphExport added in v0.7.0 

func (r *Result) ToCallgraphExport(root ComponentKey, meta ScanMeta) CallgraphExport

ToCallgraphExport converts the stitched Result into a schema-5.x JSON structure for root, stamped with meta. It groups chains by FindingID into finding_graphs[], stamps dependency_info on non-root frames, emits entry_call from frame.EntryCall and crypto_call on the terminal node, then builds the entry_point_index from all surviving chains.

The output is resolution-corrected by construction: only chains that passed buildAdjacency's fail-closed policy are present in r.Chains.

type ScanMeta added in v0.7.0 

type ScanMeta struct {
	// SchemaVersion is the schema_version value to emit (e.g. "5.3").
	SchemaVersion string
	// RootModule is the Maven/npm/etc. module string for the root component.
	RootModule string
	// Ecosystem identifies the language ecosystem (e.g. "java").
	Ecosystem string
}

ScanMeta carries the top-level metadata stamped onto a CallgraphExport.

type SourceLocation added in v0.7.0 

type SourceLocation struct {
	FilePath string
	Line     int
}

SourceLocation identifies a position in source code.

type SourceNode added in v0.7.0 

type SourceNode struct {
	// Type classifies the origin: VALUE, VARIABLE, FIELD, PARAMETER, CALL_RESULT, EXPRESSION.
	Type string
	// Name is the variable/field/parameter name.
	Name string
	// DeclaredType is the type if known.
	DeclaredType string
	// Value is the actual value for VALUE nodes.
	Value string
	// ParameterIndex is set for PARAMETER nodes.
	ParameterIndex *int
	// CallTarget is set for CALL_RESULT nodes — the function that produced the value.
	CallTarget string
	// Location is where this source is defined.
	Location *SourceLocation
	// SourceNodes traces where THIS node's value came from (recursive).
	SourceNodes []SourceNode
}

SourceNode is one node in the data-flow provenance graph. The SourceNodes field makes this type recursive so PARAMETER→CALL_RESULT chains are fully preserved. Mirrors the schema-5.x exportSourceNode shape.

type SuppressedEdge 

type SuppressedEdge struct {
	Caller     CallFrame
	MethodName string
	Arity      int
	Reason     string
	Candidates []ComponentKey
}

SuppressedEdge is one call edge (or grouped call site) the stitcher declined to traverse, with the reason and the candidate targets it would have reached.

Source Files

View all Source files

Directories

Path Synopsis
Package equiv provides a semantic equivalence diff tool for schema-5.x callgraph exports produced by crypto-finder.
 Package equiv provides a semantic equivalence diff tool for schema-5.x callgraph exports produced by crypto-finder.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.