Documentation
¶
Index ¶
- Constants
- func BuildScanRecord(target plugin.ExecutionTarget, run scan.Run, auditEnabled bool, ...) scan.Record
- func ClassifyManifest(subprojectRel, manifestPath string) (subprojectDir, moduleDir string)
- func DependenciesFromGraph(g *model.Graph, registry *model.PackageRegistry) []scan.Dependency
- func DependencyDetailNeedsReview(transition DiffDependencyTransition) bool
- func DependencyDetailReviewReasons(transition DiffDependencyTransition) []model.DependencyDetailReviewReason
- func DependencyPrimaryScope(d scan.Dependency) string
- func FailingFindingCount(findings []model.Finding) int
- func FindingAdvisory(registry *model.PackageRegistry, f model.Finding) (*model.Package, *model.Vulnerability)
- func FindingLabel(f model.Finding) string
- func FindingResolvedVulnerabilityID(f model.Finding) string
- func FindingVulnerabilityID(f model.Finding) string
- func FindingVulnerabilityInPackages(f model.Finding, packages []*model.Package) *model.Vulnerability
- func FindingsWithSeverity(findings []model.Finding, registry *model.PackageRegistry) []model.Finding
- func LicenseIdentifier(l model.PackageLicense) string
- func ManifestRootName(manifest scan.Manifest) string
- func MatchVulnerabilityRef(refs []model.Vulnerability, id string) *model.Vulnerability
- func NewScanRun(toolVersion string, enrich, analyze, audit bool, failOn []string) scan.Run
- func NodePackageRef(node model.GraphNode) string
- func NodeVulnerabilities(registry *model.PackageRegistry, node model.GraphNode) []model.Vulnerability
- func PackageAdvisory(pkg *model.Package, vulnerabilityID string) *model.Vulnerability
- func PackagesFromRegistries(base, head *model.PackageRegistry) []*model.Package
- func PackagesFromRegistry(registry *model.PackageRegistry) []*model.Package
- func PurlFromGraphNode(node model.GraphNode) string
- func RegistryPackage(registry *model.PackageRegistry, packageRef string) *model.Package
- func RegistryPackageForNode(registry *model.PackageRegistry, node model.GraphNode) *model.Package
- func ResolvedLicenses(registry *model.PackageRegistry, node model.GraphNode) []model.PackageLicense
- func ScanManifestsFromConsolidated(consolidated plugin.ConsolidatedGraph, registry *model.PackageRegistry) []scan.Manifest
- func SubjectFromExecutionTarget(target plugin.ExecutionTarget) scan.Subject
- func SummaryFromFindings(findings []model.Finding) *scan.AuditSummary
- func WithScanAnalyzerRuns(r scan.Record, runs []string, stats map[string]plugin.ReachabilityStats) scan.Record
- func WithScanReportOptions(r scan.Record, options ReportOptions) scan.Record
- func Write(w io.Writer, format Format, payload any, renderers Renderers) error
- func WriteSARIF(w io.Writer, findings []model.Finding, registry *model.PackageRegistry, ...) error
- type DependencyPath
- type DiffAudit
- type DiffChangedPackage
- type DiffComparison
- type DiffDependencyResults
- type DiffDependencyTransition
- type DiffDependencyTransitionState
- type DiffLicenseChange
- type DiffLicenseDelta
- type DiffLicenseResults
- type DiffManifestResult
- type DiffPackageChange
- type DiffResponse
- type DiffResults
- type DiffSummary
- type DiffVulnerabilityChange
- type DiffVulnerabilityResults
- type ExplainDependency
- type ExplainQuery
- type ExplainResponse
- type ExplainTargetResponse
- type FindingPackageRef
- type Format
- type HierarchyNode
- type ManifestNodeKind
- type PackageRef
- type ProjectDescriptor
- type Renderers
- type ReportOptions
- type SARIFLineRange
- type SARIFOptions
Constants ¶
const SchemaVersion = "1.0"
SchemaVersion is the schema version of the diff and explain documents, which keep the CLI's own numbering. The scan document is the SDK's scan record and carries scan.SchemaVersion.
Variables ¶
This section is empty.
Functions ¶
func BuildScanRecord ¶ added in v0.27.0
func BuildScanRecord(target plugin.ExecutionTarget, run scan.Run, auditEnabled bool, consolidated plugin.ConsolidatedGraph, registry *model.PackageRegistry, findings []model.Finding, started time.Time, options ...ReportOptions) scan.Record
BuildScanRecord constructs the scan record from what the pipeline holds: the consolidated manifest selections, the registry, the findings, and the facts about the run itself -- what was scanned, when, by what -- that the document never used to carry. Reachability metadata (analyzer runs and per-analyzer stats) is attached afterwards via WithAnalyzerRuns.
func ClassifyManifest ¶ added in v0.18.0
ClassifyManifest resolves where a manifest belongs in the hierarchy from its subproject relative path ("", "." = scan root) and its repo-relative manifest path. It returns the normalized subproject directory ("." for root) and the module directory: "" when the manifest sits directly in its subproject directory, otherwise the repo-relative directory of the module that owns the manifest. A manifest whose directory is not beneath its subproject directory attaches directly to the subproject (defensive).
func DependenciesFromGraph ¶
func DependenciesFromGraph(g *model.Graph, registry *model.PackageRegistry) []scan.Dependency
DependenciesFromGraph converts a graph into stable, lean scan dependency payloads. registry, when non-nil, supplies the Matched flag via PURL lookup; all richer enrichment is surfaced through PackagesFromRegistry instead.
func DependencyDetailNeedsReview ¶ added in v0.21.0
func DependencyDetailNeedsReview(transition DiffDependencyTransition) bool
DependencyDetailNeedsReview reports whether a projected dependency detail transition should receive extra review.
func DependencyDetailReviewReasons ¶ added in v0.21.0
func DependencyDetailReviewReasons(transition DiffDependencyTransition) []model.DependencyDetailReviewReason
DependencyDetailReviewReasons classifies a projected dependency detail transition without adding a derived field to the JSON contract.
func DependencyPrimaryScope ¶ added in v0.27.0
func DependencyPrimaryScope(d scan.Dependency) string
DependencyPrimaryScope returns the merged precedence scope across the dependency's recorded scopes, mirroring model.DependencyNode.PrimaryScope so text/markdown renderers reproduce the same scope label.
func FailingFindingCount ¶
FailingFindingCount reports how many findings should fail policy evaluation. Warning and suppressed findings remain reportable but do not gate execution.
func FindingAdvisory ¶ added in v0.25.0
func FindingAdvisory(registry *model.PackageRegistry, f model.Finding) (*model.Package, *model.Vulnerability)
FindingAdvisory resolves a finding against the registry, returning the package it references and the advisory it names. Either may be nil: an unenriched scan has neither, and a license or policy finding has a package but names no advisory.
func FindingLabel ¶ added in v0.27.0
FindingLabel returns a human-readable name@version label for the package a finding references, derived from its package URL.
func FindingResolvedVulnerabilityID ¶ added in v0.27.0
FindingResolvedVulnerabilityID returns the advisory id a finding names, falling back to its own id for vulnerability findings.
func FindingVulnerabilityID ¶ added in v0.25.0
FindingVulnerabilityID returns the advisory id a finding references.
A finding's own id is the advisory id for the vulnerability auditor, which mints one finding per advisory, but not for auditors that mint several findings against one advisory; those carry it in VulnerabilityID. Every join from a finding to an advisory uses this precedence.
func FindingVulnerabilityInPackages ¶ added in v0.17.0
func FindingVulnerabilityInPackages(f model.Finding, packages []*model.Package) *model.Vulnerability
FindingVulnerabilityInPackages resolves a finding's advisory from the packages collection by package URL and advisory id.
func FindingsWithSeverity ¶ added in v0.27.0
func FindingsWithSeverity(findings []model.Finding, registry *model.PackageRegistry) []model.Finding
FindingsWithSeverity returns the findings as the document carries them: a clone of each, with a severity the finding itself did not state backfilled from the advisory it references, so a vulnerability finding never reads as severity-less beside the advisory that rates it.
func LicenseIdentifier ¶ added in v0.27.0
func LicenseIdentifier(l model.PackageLicense) string
LicenseIdentifier returns the most useful license identifier for display.
func ManifestRootName ¶ added in v0.18.0
ManifestRootName returns the package name of a manifest's root dependency — the project/module's own name (web, core-lib) — or "" when the manifest has no single unambiguous root. The root is the one dependency no other dependency in the manifest depends on.
func MatchVulnerabilityRef ¶ added in v0.17.0
func MatchVulnerabilityRef(refs []model.Vulnerability, id string) *model.Vulnerability
MatchVulnerabilityRef finds an advisory by id or alias.
func NewScanRun ¶ added in v0.27.0
NewScanRun describes the execution about to produce a record: a fresh run identifier, the host and its version, and the stage selections and policy inputs the user chose. Timestamps are filled by BuildScanRecord.
func NodePackageRef ¶ added in v0.25.0
NodePackageRef returns the registry key for a graph node: the package it resolved to.
The stored truth is DependencyNode.PackageRef, and identity (ADR-0041) makes that the node's canonical PURL, so today it equals NodeID(). Asking for the package reference rather than the node id says what the lookup means, and leaves the two free to diverge -- a graph carrying several occurrence nodes for one package would break every caller that had spelled this NodeID().
Structural nodes -- modules and manifests -- are not packages and get "", which resolves to a nil package rather than to some other node's entry.
func NodeVulnerabilities ¶ added in v0.25.0
func NodeVulnerabilities(registry *model.PackageRegistry, node model.GraphNode) []model.Vulnerability
NodeVulnerabilities returns the advisories the matching stage recorded against the package a graph node resolved to.
func PackageAdvisory ¶ added in v0.25.0
func PackageAdvisory(pkg *model.Package, vulnerabilityID string) *model.Vulnerability
PackageAdvisory returns the advisory a package carries under the given id, matching aliases as well, or nil when it carries none.
Aliases matter because the id a finding names is the id of the source that reported it: an OSV finding names GHSA-xxxx while the enriched advisory may be stored under its CVE, and an exact-id-only match silently renders the finding without severity, fix version, or KEV status.
func PackagesFromRegistries ¶ added in v0.17.0
func PackagesFromRegistries(base, head *model.PackageRegistry) []*model.Package
PackagesFromRegistries projects the union of the base and head registries into one PURL-deduplicated packages collection. Head entries win on conflict, so findings computed against the head state resolve to head advisory data while base-only (resolved-finding) packages stay joinable.
func PackagesFromRegistry ¶
func PackagesFromRegistry(registry *model.PackageRegistry) []*model.Package
PackagesFromRegistry projects the registry into the packages collection, sorted by package URL: a clone of each package, so the document never aliases the registry a later stage may still enrich.
func PurlFromGraphNode ¶ added in v0.25.0
PurlFromGraphNode returns the package URL a node publishes, or "" when it has none. It delegates to graphview, which is the one place that decides this for every surface that publishes a purl.
func RegistryPackage ¶ added in v0.25.0
func RegistryPackage(registry *model.PackageRegistry, packageRef string) *model.Package
RegistryPackage returns what the matching stage recorded for a package reference, or nil when it recorded nothing.
nil is the normal answer, not an error: a scan without --enrich has an empty registry, and every caller here is rendering a detection-time fact that has no enrichment behind it.
func RegistryPackageForNode ¶ added in v0.25.0
RegistryPackageForNode returns what the matching stage recorded for the package a graph node resolved to, or nil when it recorded nothing.
func ResolvedLicenses ¶ added in v0.25.0
func ResolvedLicenses(registry *model.PackageRegistry, node model.GraphNode) []model.PackageLicense
ResolvedLicenses returns the licenses to show for a graph node: the ones matching learned when it learned any, and otherwise the ones detection read out of the lockfile or manifest.
Matching wins as a whole rather than merging, because a registry package's licenses are the reconciled answer for that PURL and detection's are one producer's reading of one file.
func ScanManifestsFromConsolidated ¶
func ScanManifestsFromConsolidated(consolidated plugin.ConsolidatedGraph, registry *model.PackageRegistry) []scan.Manifest
ScanManifestsFromConsolidated converts consolidated manifest selections into stable scan payloads. registry, when non-nil, enriches each manifest's packages with matching-stage data (vulnerabilities / scorecard / etc.) resolved by PURL.
func SubjectFromExecutionTarget ¶ added in v0.27.0
func SubjectFromExecutionTarget(target plugin.ExecutionTarget) scan.Subject
SubjectFromExecutionTarget identifies what was scanned without its local location: a repository by URL, ref and the commit it resolved to; a filesystem target by its commit when it had one; an image by its reference. The path a target was read from stays out of the record, and so do any credentials the repository URL carried: the target is built without them, and a target built by another caller is held to the same rule here.
func SummaryFromFindings ¶
func SummaryFromFindings(findings []model.Finding) *scan.AuditSummary
SummaryFromFindings aggregates finding counts by severity band.
func WithScanAnalyzerRuns ¶ added in v0.27.0
func WithScanAnalyzerRuns(r scan.Record, runs []string, stats map[string]plugin.ReachabilityStats) scan.Record
WithScanAnalyzerRuns annotates a scan record with analyzer run names and per-analyzer reachability stats.
func WithScanReportOptions ¶ added in v0.27.0
func WithScanReportOptions(r scan.Record, options ReportOptions) scan.Record
WithScanReportOptions annotates a scan record with optional report data and strips experimental reachability annotations when the flag is disabled.
func WriteSARIF ¶
func WriteSARIF(w io.Writer, findings []model.Finding, registry *model.PackageRegistry, toolName, toolVersion string, options ...SARIFOptions) error
WriteSARIF writes findings as a SARIF 2.1.0 document to w. toolName and toolVersion are used to populate the driver section. registry, when non-nil, is used to resolve f.PackageRef → *model.Package and f.VulnerabilityID → *model.Vulnerability so each result carries the rich properties (CVSS / EPSS / KEV / CWE / fix state / reachability call paths) as SARIF `properties` / `codeFlows`.
Types ¶
type DependencyPath ¶
type DependencyPath struct {
Relationship string `json:"relationship,omitempty"`
Packages []PackageRef `json:"packages"`
IntroducedVia string `json:"introduced_via,omitempty"`
Cyclic bool `json:"cyclic,omitempty"`
CycleTo string `json:"cycle_to,omitempty"`
}
DependencyPath describes one resolved dependency path returned by the explain command.
type DiffAudit ¶
type DiffAudit struct {
Introduced []model.Finding `json:"introduced"`
Resolved []model.Finding `json:"resolved"`
Persisted []model.Finding `json:"persisted"`
AuditSummary *scan.AuditSummary `json:"audit_summary,omitempty"`
}
DiffAudit groups audit deltas for diff output.
type DiffChangedPackage ¶
type DiffChangedPackage struct {
After PackageRef `json:"after"`
Before PackageRef `json:"before"`
}
DiffChangedPackage is one version-changed package.
type DiffComparison ¶
DiffComparison identifies the compared dependency states.
type DiffDependencyResults ¶
type DiffDependencyResults struct {
Added []DiffPackageChange `json:"added"`
Removed []DiffPackageChange `json:"removed"`
Changed []DiffChangedPackage `json:"changed"`
Transitions []DiffDependencyTransition `json:"transitions"`
}
DiffDependencyResults aggregates package changes across all manifests.
type DiffDependencyTransition ¶ added in v0.21.0
type DiffDependencyTransition struct {
Before DiffDependencyTransitionState `json:"before"`
After DiffDependencyTransitionState `json:"after"`
ChangedFields []model.DependencyDetailField `json:"changed_fields"`
}
DiffDependencyTransition is one same-identity occurrence whose relationship, source, or registry-matching eligibility changed.
type DiffDependencyTransitionState ¶ added in v0.21.0
type DiffDependencyTransitionState struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version,omitempty"`
Purl string `json:"purl,omitempty"`
Scope string `json:"scope,omitempty"`
Relationship model.DependencyRelationship `json:"relationship"`
Source model.DependencySource `json:"source,omitempty"`
RegistryEligible bool `json:"registry_eligible"`
}
DiffDependencyTransitionState preserves the identity and details of one occurrence before or after a transition.
type DiffLicenseChange ¶
type DiffLicenseChange struct {
Package PackageRef `json:"package"`
Licenses []model.PackageLicense `json:"licenses"`
}
DiffLicenseChange is a package whose license set was introduced or removed.
type DiffLicenseDelta ¶
type DiffLicenseDelta struct {
Package PackageRef `json:"package"`
Before []model.PackageLicense `json:"before"`
After []model.PackageLicense `json:"after"`
}
DiffLicenseDelta is a package whose license set changed.
type DiffLicenseResults ¶
type DiffLicenseResults struct {
Added []DiffLicenseChange `json:"added"`
Removed []DiffLicenseChange `json:"removed"`
Changed []DiffLicenseDelta `json:"changed"`
}
DiffLicenseResults aggregates license changes across all manifests.
type DiffManifestResult ¶
type DiffManifestResult struct {
Status string `json:"status"`
Path string `json:"path,omitempty"`
Kind model.ManifestKind `json:"kind,omitempty"`
Subproject string `json:"subproject,omitempty"`
Ecosystem model.Ecosystem `json:"ecosystem,omitempty"`
PackageManager model.PackageManager `json:"package_manager,omitempty"`
Added []DiffPackageChange `json:"added"`
Removed []DiffPackageChange `json:"removed"`
Changed []DiffChangedPackage `json:"changed"`
Transitions []DiffDependencyTransition `json:"transitions"`
}
DiffManifestResult describes changes for one manifest.
type DiffPackageChange ¶
type DiffPackageChange struct {
Package PackageRef `json:"package"`
}
DiffPackageChange is one added or removed package.
type DiffResponse ¶
type DiffResponse struct {
SchemaVersion string `json:"schema_version"`
Command string `json:"command"`
Project ProjectDescriptor `json:"project"`
Comparison DiffComparison `json:"comparison"`
Results DiffResults `json:"results"`
Summary DiffSummary `json:"summary"`
Packages []*model.Package `json:"packages"`
Audit *DiffAudit `json:"audit,omitempty"`
Warnings []plugin.DetectorWarning `json:"warnings"`
Metadata scan.Metadata `json:"metadata"`
}
DiffResponse is the structured payload for the diff command. Packages is the PURL-deduplicated union of the base and head registries (head wins on conflict) so audit findings can be joined against advisory data the same way scan findings join against scan.Record.Packages.
func BuildDiffResponse ¶
func BuildDiffResponse(projectPath, baseRef, headRef string, baseConsolidated, headConsolidated plugin.ConsolidatedGraph, audit *DiffAudit, started time.Time, options ...ReportOptions) DiffResponse
BuildDiffResponse constructs the structured diff payload from consolidated manifest selections.
func (DiffResponse) MarshalJSON ¶ added in v0.27.0
func (r DiffResponse) MarshalJSON() ([]byte, error)
MarshalJSON writes the diff document with every collection present, and each package with its licenses and vulnerabilities written as [] when it has none (scan.Package). The receiver is a copy; only nil slices are replaced, which encodes the same value the holder already has.
func (DiffResponse) WithReportOptions ¶
func (r DiffResponse) WithReportOptions(options ReportOptions) DiffResponse
WithReportOptions annotates a DiffResponse with optional report data and strips experimental reachability annotations when the flag is disabled.
type DiffResults ¶
type DiffResults struct {
Dependencies DiffDependencyResults `json:"dependencies"`
Licenses DiffLicenseResults `json:"licenses"`
Vulnerabilities DiffVulnerabilityResults `json:"vulnerabilities"`
Manifests []DiffManifestResult `json:"manifests"`
}
DiffResults groups per-manifest diff results.
type DiffSummary ¶
type DiffSummary struct {
AddedManifestCount int `json:"added_manifest_count"`
ChangedManifestCount int `json:"changed_manifest_count"`
RemovedManifestCount int `json:"removed_manifest_count"`
UnchangedManifestCount int `json:"unchanged_manifest_count"`
AddedPackageCount int `json:"added_package_count"`
ChangedPackageCount int `json:"changed_package_count"`
TransitionedPackageCount int `json:"transitioned_package_count"`
RemovedPackageCount int `json:"removed_package_count"`
ExactMatchCount int `json:"exact_match_count"`
FuzzyMatchCount int `json:"fuzzy_match_count"`
UnmatchedPackageCount int `json:"unmatched_package_count"`
}
DiffSummary aggregates manifest and package counts for a diff.
type DiffVulnerabilityChange ¶
type DiffVulnerabilityChange struct {
Package PackageRef `json:"package"`
Vulnerability model.Vulnerability `json:"vulnerability"`
}
DiffVulnerabilityChange is one vulnerability introduced or removed for a package.
type DiffVulnerabilityResults ¶
type DiffVulnerabilityResults struct {
Added []DiffVulnerabilityChange `json:"added"`
Removed []DiffVulnerabilityChange `json:"removed"`
Persisted []DiffVulnerabilityChange `json:"persisted"`
}
DiffVulnerabilityResults aggregates vulnerability changes across all manifests. Persisted holds vulnerabilities that affect a version-changed package on both sides of the diff — i.e. carried-over findings the upgrade did not remediate.
type ExplainDependency ¶ added in v0.20.1
type ExplainDependency struct {
PackageRef
Remediation *model.PackageRemediation `json:"remediation,omitempty"`
}
ExplainDependency is the focused package in explain output. Remediation is intentionally attached here rather than to PackageRef so dependency-path entries and diff package changes do not repeat package-level enrichment.
type ExplainQuery ¶
type ExplainQuery struct {
Name string `json:"name"`
}
ExplainQuery records the user query issued to the explain command.
type ExplainResponse ¶
type ExplainResponse struct {
SchemaVersion string `json:"schema_version"`
Command string `json:"command"`
Project ProjectDescriptor `json:"project"`
Query ExplainQuery `json:"query"`
Dependency ExplainDependency `json:"dependency,omitempty"`
Paths []DependencyPath `json:"paths"`
Findings []model.Finding `json:"findings"`
AuditSummary *scan.AuditSummary `json:"audit_summary,omitempty"`
Targets []ExplainTargetResponse `json:"targets"`
Warnings []plugin.DetectorWarning `json:"warnings"`
Metadata scan.Metadata `json:"metadata"`
}
ExplainResponse is the structured payload for the explain command.
func BuildExplainResponse ¶
func BuildExplainResponse(project ProjectDescriptor, query string, targets []ExplainTargetResponse, started time.Time, options ...ReportOptions) ExplainResponse
BuildExplainResponse constructs the structured explain payload from resolved targets.
func (ExplainResponse) MarshalJSON ¶ added in v0.27.0
func (r ExplainResponse) MarshalJSON() ([]byte, error)
MarshalJSON writes the explain document with every collection present.
func (ExplainResponse) WithReportOptions ¶
func (r ExplainResponse) WithReportOptions(options ReportOptions) ExplainResponse
WithReportOptions annotates an ExplainResponse with optional report data and strips experimental reachability annotations when the flag is disabled.
type ExplainTargetResponse ¶
type ExplainTargetResponse struct {
Project ProjectDescriptor `json:"project"`
Detector string `json:"detector,omitempty"`
PackageManager model.PackageManager `json:"package_manager,omitempty"`
Dependency ExplainDependency `json:"dependency"`
Paths []DependencyPath `json:"paths"`
Findings []model.Finding `json:"findings"`
AuditSummary *scan.AuditSummary `json:"audit_summary,omitempty"`
}
ExplainTargetResponse represents explain output for one resolved target.
type FindingPackageRef ¶ added in v0.17.0
type FindingPackageRef struct {
Name string
Org string
Version string
Purl string
Ecosystem string
}
IdentifyPackageRef resolves the display identity of a package reference: what a table cell, a finding header, or an MCP payload should call it.
When matching knew the package its own record answers. When it did not, the reference is itself a package URL and already carries the answer, so the fallback parses it rather than printing it: a findings table that says "pkg:npm/%40scope/deep@2.0.0" where every other row says "@scope/deep" is showing the reader a key, not a name. Parsing and the ecosystem-native spelling are purlkit's and the SDK's jobs, not this file's -- there is no PURL grammar here.
The raw reference survives as Name only when it is not a package URL at all, which is the one case where there is nothing better to show.
The return type is FindingPackageRef because findings were the first surface to need this shape; it is the presentation identity of any package reference. FindingPackageRef is the presentation identity of a package a finding references: what a renderer prints for it. It is not part of any document -- the scan record's findings reference their package by URL and the packages collection carries the identity -- so it is derived here, from the registry when the package is in it and from the package URL otherwise.
func IdentifyPackageRef ¶ added in v0.25.0
func IdentifyPackageRef(registry *model.PackageRegistry, packageRef string) FindingPackageRef
func IdentityFromPackageRef ¶ added in v0.27.0
func IdentityFromPackageRef(packageRef string) FindingPackageRef
identityFromPURL derives a display identity from a package URL, falling back to the raw string when it is not one. IdentityFromPackageRef derives a display identity from a package URL alone, for a renderer that has no registry in scope.
func (FindingPackageRef) DisplayLabel ¶ added in v0.17.0
func (p FindingPackageRef) DisplayLabel() string
DisplayLabel returns a human-readable name@version label for the package.
type Format ¶
type Format string
Format identifies a supported output format.
const ( // FormatJSON renders structured JSON output. FormatJSON Format = "json" // FormatMarkdown renders a Markdown report. FormatMarkdown Format = "markdown" // FormatText renders a human-readable text format. FormatText Format = "text" // FormatSARIF renders SARIF 2.1.0 output for vulnerability findings. FormatSARIF Format = "sarif" // FormatSPDX renders an SPDX 2.3 JSON SBOM. FormatSPDX Format = "spdx" // FormatCycloneDX renders a CycloneDX 1.7 JSON SBOM. FormatCycloneDX Format = "cyclonedx" )
func ParseFormat ¶
ParseFormat validates a format value.
type HierarchyNode ¶ added in v0.18.0
type HierarchyNode struct {
Kind ManifestNodeKind
// Dir is the repo-relative directory of the node; "." for the project root.
Dir string
// Label is the display name: subproject labels are their repo-relative
// directory, module labels are relative to their parent node's directory.
Label string
// ManifestIndexes point into the manifests slice passed to BuildHierarchy
// for manifests attached directly to this node, preserving input order.
ManifestIndexes []int
// Children holds module nodes (under project or subproject nodes) and
// subproject nodes (under the project node only), modules first, each
// group sorted by Dir.
Children []HierarchyNode
// AttachedManifest is set on module nodes only: the index (into the
// manifests slice passed to BuildHierarchy) of the parent node's manifest
// that natively resolves this module — the workspace lockfile or reactor
// pom. -1 when no unambiguous parent manifest exists. Views nest modules
// under that manifest's node.
AttachedManifest int
}
HierarchyNode is one node of the derived project → subproject → module grouping of scan manifests. The hierarchy is a pure presentation view: it is derived from each manifest's Subproject and Path fields, never stored, so every consumer (TUI, text, markdown, MCP) shows the same structure without schema changes.
func BuildHierarchy ¶ added in v0.18.0
func BuildHierarchy(manifests []scan.Manifest) HierarchyNode
BuildHierarchy groups scan manifests into the derived project hierarchy: root-level manifests attach directly to the project node; module nodes and subproject nodes are its children (modules first, then subprojects, each sorted by directory); a subproject's own manifests attach to its node with its modules as children.
func (HierarchyNode) CountKind ¶ added in v0.18.0
func (n HierarchyNode) CountKind(kind ManifestNodeKind) int
CountKind returns the number of descendant nodes of the given kind.
func (HierarchyNode) HasGroups ¶ added in v0.18.0
func (n HierarchyNode) HasGroups() bool
HasGroups reports whether the hierarchy contains any subproject or module nodes. Consumers keep today's flat presentation when it does not.
type ManifestNodeKind ¶ added in v0.18.0
type ManifestNodeKind string
ManifestNodeKind labels one level of the derived project hierarchy.
const ( // ManifestNodeProject is the scan root. ManifestNodeProject ManifestNodeKind = "project" // ManifestNodeSubproject is an independently discovered nested directory // (a subproject planned by discovery with a non-root relative path). ManifestNodeSubproject ManifestNodeKind = "subproject" // ManifestNodeModule is a member the package manager natively resolves // under one root manifest (a Maven reactor module, an npm/pnpm/cargo // workspace member): its manifest path sits beneath the subproject // directory that produced it. ManifestNodeModule ManifestNodeKind = "module" )
type PackageRef ¶
type PackageRef struct {
Name string `json:"name"`
Version string `json:"version,omitempty"`
Scope string `json:"scope,omitempty"`
Purl string `json:"purl,omitempty"`
ID string `json:"id,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
Locations []model.PackageLocation `json:"locations"`
Licenses []model.PackageLicense `json:"licenses"`
Vulnerabilities []model.Vulnerability `json:"vulnerabilities"`
Scorecard *model.PackageScorecard `json:"scorecard,omitempty"`
Relationship string `json:"relationship,omitempty"`
// Direct reports whether the package is a direct dependency of a project
// root. nil means directness could not be determined (e.g. a flat SBOM with
// no dependency edges); it is only populated where a graph is in scope.
Direct *bool `json:"direct,omitempty"`
}
PackageRef identifies a package in command outputs.
func PackageFromDependencyAndRegistry ¶
func PackageFromDependencyAndRegistry(dep *model.DependencyNode, registry *model.PackageRegistry) PackageRef
PackageFromDependencyAndRegistry builds a PackageRef from a graph Dependency node and layers in matching-stage enrichment (vulnerabilities, scorecard, licenses learned during matching) by resolving dep.NodeID() against the registry. registry may be nil — callers without a registry get the detection-only projection.
func PackageFromGraphNode ¶ added in v0.25.0
func PackageFromGraphNode(node model.GraphNode) PackageRef
PackageFromGraphNode renders any graph node as a package reference.
A dependency path runs through the project's own artifacts before it reaches a consumed package, and those are module and manifest nodes now (ADR-0041). Rendering only the dependency nodes drops the head of every path -- "why is loose-envify here" answers with "react needs it" and never says which project pulled react in -- so a structural node renders too, with the fields its kind actually has.
func PackageFromGraphPackage ¶
func PackageFromGraphPackage(dep *model.DependencyNode) PackageRef
PackageFromGraphPackage builds a PackageRef from a graph Dependency node. Detection-time license facts (carried in the dependency's metadata under MetadataKeyDetectionLicenses) are surfaced directly from the dependency; matching-stage enrichment (Vulnerabilities, Scorecard, EOL, licenses learned during matching) must come from the registry — use PackageFromDependencyAndRegistry when a registry is in scope.
type ProjectDescriptor ¶
type ProjectDescriptor struct {
Name string `json:"name,omitempty"`
Path string `json:"path"`
TargetType string `json:"target_type,omitempty"`
TargetRef string `json:"target_ref,omitempty"`
Ecosystem model.Ecosystem `json:"ecosystem"`
PackageManager model.PackageManager `json:"package_manager,omitempty"`
}
ProjectDescriptor describes the project being analyzed.
type ReportOptions ¶
type ReportOptions struct {
// DetectorWarnings are the detection-stage warnings the run produced. They
// are surfaced in the response document so a consumer reading JSON sees the
// same problems the progress stream showed.
DetectorWarnings []plugin.DetectorWarning
ReachabilityEnabled bool
ScorecardEnabled bool
AnalyzerRuns []string
AnalyzerStats map[string]plugin.ReachabilityStats
BaseRegistry *model.PackageRegistry
HeadRegistry *model.PackageRegistry
}
ReportOptions controls optional experimental data in structured command outputs.
type SARIFLineRange ¶ added in v0.14.17
SARIFLineRange is an inclusive 1-based line range used to prefer dependency locations that intersect a source diff.
type SARIFOptions ¶
type SARIFOptions struct {
IncludeReachability bool
LocationGraphs []*model.Graph
BaselineState string
ChangedLines map[string][]SARIFLineRange
}
SARIFOptions controls optional experimental data in SARIF output.