Documentation
¶
Index ¶
- Constants
- func FailingFindingCount(findings []sdk.Finding) int
- func Write(w io.Writer, format Format, payload any, renderers Renderers) error
- func WriteSARIF(w io.Writer, findings []sdk.Finding, registry *sdk.PackageRegistry, ...) error
- type AuditFinding
- type AuditSummary
- type DependencyPath
- type DiffAudit
- type DiffChangedPackage
- type DiffComparison
- type DiffDependencyResults
- type DiffLicenseChange
- type DiffLicenseDelta
- type DiffLicenseResults
- type DiffManifestResult
- type DiffPackageChange
- type DiffResponse
- type DiffResults
- type DiffSummary
- type DiffVulnerabilityChange
- type DiffVulnerabilityResults
- type ExplainQuery
- type ExplainResponse
- type ExplainTargetResponse
- type Format
- type LicenseRef
- type LocationRef
- type Metadata
- type PackageRef
- type PositionRef
- type ProjectDescriptor
- type Renderers
- type ReportOptions
- type SARIFOptions
- type ScanDependency
- type ScanManifest
- type ScanPackageEntry
- type ScanResponse
- type ScanTargetResponse
- type VulnerabilityRef
Constants ¶
const SchemaVersion = "1.0"
SchemaVersion is the current CLI output schema version.
Variables ¶
This section is empty.
Functions ¶
func FailingFindingCount ¶
FailingFindingCount reports how many findings should fail policy evaluation.
func WriteSARIF ¶
func WriteSARIF(w io.Writer, findings []sdk.Finding, registry *sdk.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 → *sdk.Package and f.VulnerabilityID → *sdk.Vulnerability so each result carries the rich properties (CVSS / EPSS / KEV / CWE / fix state / reachability call paths) as SARIF `properties` / `codeFlows`.
Types ¶
type AuditFinding ¶
type AuditFinding struct {
ID string `json:"id"`
Kind string `json:"kind"`
Severity string `json:"severity"`
Package PackageRef `json:"package"`
Title string `json:"title"`
Reasons []string `json:"reasons,omitempty"`
Source string `json:"source"`
Auditor string `json:"auditor,omitempty"`
Disposition string `json:"disposition,omitempty"`
FixedIn string `json:"fixed_in,omitempty"`
FixedVersions []string `json:"fixed_versions,omitempty"`
FixState string `json:"fix_state,omitempty"`
FixAvailable []sdk.FixAvailable `json:"fix_available,omitempty"`
Aliases []string `json:"aliases,omitempty"`
Description string `json:"description,omitempty"`
SeveritySource string `json:"severity_source,omitempty"`
CVSS []sdk.CVSSScore `json:"cvss,omitempty"`
AffectedVersionRange string `json:"affected_version_range,omitempty"`
References []sdk.Reference `json:"references,omitempty"`
KEVExploited bool `json:"kev_exploited,omitempty"`
KnownExploited []sdk.KnownExploited `json:"known_exploited,omitempty"`
EPSS []sdk.EPSSScore `json:"epss,omitempty"`
CWEs []sdk.CWE `json:"cwes,omitempty"`
RiskScore float64 `json:"risk_score,omitempty"`
DataSource string `json:"data_source,omitempty"`
Namespace string `json:"namespace,omitempty"`
CPEs []string `json:"cpes,omitempty"`
Reachability *sdk.Reachability `json:"reachability,omitempty"`
}
AuditFinding is the serialized form of one normalized scan finding.
func FindingsFromScan ¶
func FindingsFromScan(findings []sdk.Finding, registry *sdk.PackageRegistry) []AuditFinding
FindingsFromScan converts normalized findings into JSON-friendly DTOs. When registry is non-nil the AuditFinding output is re-enriched: the PackageRef is resolved against the registry, and (for vulnerability findings) the specific Vulnerability identified by f.VulnerabilityID supplies CVSS / EPSS / KEV / CWE / fix-state / reachability properties.
type AuditSummary ¶
type AuditSummary struct {
Critical int `json:"critical"`
High int `json:"high"`
Medium int `json:"medium"`
Low int `json:"low"`
Unknown int `json:"unknown"`
Total int `json:"total"`
}
AuditSummary aggregates finding counts by severity.
func SummaryFromFindings ¶
func SummaryFromFindings(findings []sdk.Finding) *AuditSummary
SummaryFromFindings aggregates finding counts by severity band.
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 []AuditFinding `json:"introduced,omitempty"`
Resolved []AuditFinding `json:"resolved,omitempty"`
Persisted []AuditFinding `json:"persisted,omitempty"`
AuditSummary *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,omitempty"`
Removed []DiffPackageChange `json:"removed,omitempty"`
Changed []DiffChangedPackage `json:"changed,omitempty"`
}
DiffDependencyResults aggregates package changes across all manifests.
type DiffLicenseChange ¶
type DiffLicenseChange struct {
Package PackageRef `json:"package"`
Licenses []LicenseRef `json:"licenses"`
}
DiffLicenseChange is a package whose license set was introduced or removed.
type DiffLicenseDelta ¶
type DiffLicenseDelta struct {
Package PackageRef `json:"package"`
Before []LicenseRef `json:"before"`
After []LicenseRef `json:"after"`
}
DiffLicenseDelta is a package whose license set changed.
type DiffLicenseResults ¶
type DiffLicenseResults struct {
Added []DiffLicenseChange `json:"added,omitempty"`
Removed []DiffLicenseChange `json:"removed,omitempty"`
Changed []DiffLicenseDelta `json:"changed,omitempty"`
}
DiffLicenseResults aggregates license changes across all manifests.
type DiffManifestResult ¶
type DiffManifestResult struct {
Status string `json:"status"`
Path string `json:"path,omitempty"`
Kind string `json:"kind,omitempty"`
Subproject string `json:"subproject,omitempty"`
Ecosystem string `json:"ecosystem,omitempty"`
PackageManager string `json:"package_manager,omitempty"`
Added []DiffPackageChange `json:"added,omitempty"`
Removed []DiffPackageChange `json:"removed,omitempty"`
Changed []DiffChangedPackage `json:"changed,omitempty"`
}
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"`
Audit *DiffAudit `json:"audit,omitempty"`
Metadata Metadata `json:"metadata"`
}
DiffResponse is the structured payload for the diff command.
func BuildDiffResponse ¶
func BuildDiffResponse(projectPath, baseRef, headRef string, baseConsolidated, headConsolidated sdk.ConsolidatedGraph, audit *DiffAudit, started time.Time, options ...ReportOptions) DiffResponse
BuildDiffResponse constructs the structured diff payload from consolidated manifest selections.
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"`
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 VulnerabilityRef `json:"vulnerability"`
}
DiffVulnerabilityChange is one vulnerability introduced or removed for a package.
type DiffVulnerabilityResults ¶
type DiffVulnerabilityResults struct {
Added []DiffVulnerabilityChange `json:"added,omitempty"`
Removed []DiffVulnerabilityChange `json:"removed,omitempty"`
}
DiffVulnerabilityResults aggregates vulnerability changes across all manifests.
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 PackageRef `json:"dependency,omitempty"`
Paths []DependencyPath `json:"paths,omitempty"`
Findings []AuditFinding `json:"findings,omitempty"`
AuditSummary *AuditSummary `json:"audit_summary,omitempty"`
Targets []ExplainTargetResponse `json:"targets,omitempty"`
Metadata 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) 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"`
Dependency PackageRef `json:"dependency"`
Paths []DependencyPath `json:"paths"`
Findings []AuditFinding `json:"findings,omitempty"`
AuditSummary *AuditSummary `json:"audit_summary,omitempty"`
}
ExplainTargetResponse represents explain output for one resolved target.
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.6 JSON SBOM. FormatCycloneDX Format = "cyclonedx" )
func ParseFormat ¶
ParseFormat validates a format value.
type LicenseRef ¶
type LicenseRef struct {
Value string `json:"value,omitempty"`
SPDXExpression string `json:"spdxExpression,omitempty"`
Type string `json:"type,omitempty"`
}
LicenseRef identifies one package license in command outputs.
func LicenseRefsFromGraphLicenses ¶
func LicenseRefsFromGraphLicenses(licenses []sdk.PackageLicense) []LicenseRef
LicenseRefsFromGraphLicenses converts graph licenses into output-friendly values.
func (LicenseRef) Identifier ¶
func (l LicenseRef) Identifier() string
Identifier returns the most useful license identifier for display.
type LocationRef ¶
type LocationRef struct {
RealPath string `json:"real_path,omitempty"`
AccessPath string `json:"access_path,omitempty"`
Position *PositionRef `json:"position,omitempty"`
}
LocationRef points at where a package was declared in a lockfile or manifest. Detectors populate this when their input format makes position cheaply recoverable; consumers (SARIF / explain output / IDE plugins) use it to deep-link into the source.
func LocationRefsFromGraphLocations ¶
func LocationRefsFromGraphLocations(locations []sdk.PackageLocation) []LocationRef
LocationRefsFromGraphLocations converts SDK locations into output-friendly values, dropping entries with no useful content.
type Metadata ¶
type Metadata struct {
DurationMS int64 `json:"duration_ms"`
ReachabilityEnabled bool `json:"reachability_enabled,omitempty"`
AnalyzerRuns []string `json:"analyzer_runs,omitempty"`
AnalyzerStats map[string]sdk.ReachabilityStats `json:"analyzer_stats,omitempty"`
}
Metadata captures execution metadata shared by all command outputs.
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 []LocationRef `json:"locations,omitempty"`
Licenses []LicenseRef `json:"licenses"`
Vulnerabilities []VulnerabilityRef `json:"vulnerabilities"`
Scorecard *sdk.PackageScorecard `json:"scorecard,omitempty"`
}
PackageRef identifies a package in command outputs.
func PackageFromDependencyAndRegistry ¶
func PackageFromDependencyAndRegistry(dep *sdk.Dependency, registry *sdk.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.PURL against the registry. registry may be nil — callers without a registry get the detection-only projection.
func PackageFromGraphPackage ¶
func PackageFromGraphPackage(dep *sdk.Dependency) 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 PositionRef ¶
type PositionRef struct {
File string `json:"file,omitempty"`
Line int `json:"line,omitempty"`
Column int `json:"column,omitempty"`
EndLine int `json:"end_line,omitempty"`
}
PositionRef is the JSON shape of sdk.SourcePosition.
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 string `json:"ecosystem"`
PackageManager string `json:"package_manager,omitempty"`
}
ProjectDescriptor describes the project being analyzed.
type ReportOptions ¶
type ReportOptions struct {
ReachabilityEnabled bool
AnalyzerRuns []string
AnalyzerStats map[string]sdk.ReachabilityStats
BaseRegistry *sdk.PackageRegistry
HeadRegistry *sdk.PackageRegistry
}
ReportOptions controls optional experimental data in structured command outputs.
type SARIFOptions ¶
type SARIFOptions struct {
IncludeReachability bool
}
SARIFOptions controls optional experimental data in SARIF output.
type ScanDependency ¶
type ScanDependency struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version,omitempty"`
Purl string `json:"purl,omitempty"`
Scopes []string `json:"scopes,omitempty"`
DependsOn []string `json:"depends_on"`
Matched bool `json:"matched,omitempty"`
PackageRef string `json:"package_ref,omitempty"`
Locations []LocationRef `json:"locations,omitempty"`
Licenses []LicenseRef `json:"licenses"`
}
ScanDependency is one detection-stage dependency node in a manifest. It is a lean projection of sdk.Dependency: identity, scopes, edges, detection-time licenses, and a package_ref (PURL) link into the top-level packages collection. Matching-stage enrichment (vulnerabilities, scorecard, EOL, licenses learned during matching) is NOT carried here — it lives on the resolved ScanPackageEntry referenced by PackageRef.
func DependenciesFromGraph ¶
func DependenciesFromGraph(g *sdk.Graph, registry *sdk.PackageRegistry) []ScanDependency
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 (ScanDependency) PrimaryScope ¶
func (d ScanDependency) PrimaryScope() string
PrimaryScope returns the merged precedence scope across the dependency's recorded scopes, mirroring sdk.Dependency.PrimaryScope so text/markdown renderers reproduce the same scope label as before the model split.
type ScanManifest ¶
type ScanManifest struct {
Path string `json:"path,omitempty"`
Kind string `json:"kind,omitempty"`
Subproject string `json:"subproject,omitempty"`
Ecosystem string `json:"ecosystem,omitempty"`
PackageManager string `json:"package_manager,omitempty"`
Detector string `json:"detector,omitempty"`
Dependencies []ScanDependency `json:"dependencies"`
}
ScanManifest is one manifest-scoped dependency inventory in the scan payload.
func ScanManifestsFromConsolidated ¶
func ScanManifestsFromConsolidated(consolidated sdk.ConsolidatedGraph, registry *sdk.PackageRegistry) []ScanManifest
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.
type ScanPackageEntry ¶
type ScanPackageEntry struct {
Purl string `json:"purl"`
Name string `json:"name,omitempty"`
Version string `json:"version,omitempty"`
Ecosystem string `json:"ecosystem,omitempty"`
Matched bool `json:"matched,omitempty"`
Licenses []LicenseRef `json:"licenses"`
Vulnerabilities []VulnerabilityRef `json:"vulnerabilities"`
Scorecard *sdk.PackageScorecard `json:"scorecard,omitempty"`
EOL *sdk.PackageEOL `json:"eol,omitempty"`
CPEs []string `json:"cpes,omitempty"`
Digests []sdk.Digest `json:"digests,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
ScanPackageEntry is one matching-stage artifact in the top-level packages collection: a PURL-keyed, deduplicated projection of sdk.Package carrying the enrichment (licenses, vulnerabilities, scorecard, EOL, CPEs, digests) that manifest dependencies reference by package_ref.
func PackagesFromRegistry ¶
func PackagesFromRegistry(registry *sdk.PackageRegistry) []ScanPackageEntry
PackagesFromRegistry projects the matching-stage registry into the top-level packages collection, deduplicated by PURL. registry.All() is already PURL-sorted. Returns a non-nil (possibly empty) slice so JSON consumers always see a "packages" array.
type ScanResponse ¶
type ScanResponse struct {
SchemaVersion string `json:"schema_version"`
Command string `json:"command"`
Project ProjectDescriptor `json:"project"`
Manifests []ScanManifest `json:"manifests"`
Packages []ScanPackageEntry `json:"packages"`
Findings []AuditFinding `json:"findings,omitempty"`
AuditSummary *AuditSummary `json:"audit_summary,omitempty"`
Metadata Metadata `json:"metadata"`
}
ScanResponse is the structured payload for the scan command. It surfaces the three-collection model: manifests carry lean detection-stage dependencies, packages is the deduplicated matching-stage registry projection, and findings is the reference-style audit output.
func BuildScanResponse ¶
func BuildScanResponse(project ProjectDescriptor, consolidated sdk.ConsolidatedGraph, registry *sdk.PackageRegistry, findings []sdk.Finding, started time.Time, options ...ReportOptions) ScanResponse
BuildScanResponse constructs the structured scan payload from consolidated manifest selections and findings. Reachability metadata (analyzer runs and per-analyzer stats) is attached afterwards via ScanResponse.WithAnalyzerRuns.
func (ScanResponse) WithAnalyzerRuns ¶
func (r ScanResponse) WithAnalyzerRuns(runs []string, stats map[string]sdk.ReachabilityStats) ScanResponse
WithAnalyzerRuns annotates a ScanResponse with analyzer run names and per-analyzer reachability stats. Returns the response by value so it can be chained from BuildScanResponse callers without intermediate state.
func (ScanResponse) WithReportOptions ¶
func (r ScanResponse) WithReportOptions(options ReportOptions) ScanResponse
WithReportOptions annotates a ScanResponse with optional report data and strips experimental reachability annotations when the flag is disabled.
type ScanTargetResponse ¶
type ScanTargetResponse struct {
Project ProjectDescriptor `json:"project"`
Detector string `json:"detector,omitempty"`
Dependencies []ScanDependency `json:"dependencies"`
}
ScanTargetResponse represents one target-specific scan payload.
type VulnerabilityRef ¶
type VulnerabilityRef struct {
ID string `json:"id"`
Source string `json:"source"`
Title string `json:"title,omitempty"`
Severity string `json:"severity,omitempty"`
SeveritySource string `json:"severity_source,omitempty"`
Aliases []string `json:"aliases,omitempty"`
Description string `json:"description,omitempty"`
Reasons []string `json:"reasons,omitempty"`
CVSS []sdk.CVSSScore `json:"cvss,omitempty"`
FixedIn string `json:"fixed_in,omitempty"`
FixedVersions []string `json:"fixed_versions,omitempty"`
FixState string `json:"fix_state,omitempty"`
FixAvailable []sdk.FixAvailable `json:"fix_available,omitempty"`
AffectedVersionRange string `json:"affected_version_range,omitempty"`
References []sdk.Reference `json:"references,omitempty"`
KEVExploited bool `json:"kev_exploited,omitempty"`
KnownExploited []sdk.KnownExploited `json:"known_exploited,omitempty"`
EPSS []sdk.EPSSScore `json:"epss,omitempty"`
CWEs []sdk.CWE `json:"cwes,omitempty"`
RiskScore float64 `json:"risk_score,omitempty"`
DataSource string `json:"data_source,omitempty"`
Namespace string `json:"namespace,omitempty"`
CPEs []string `json:"cpes,omitempty"`
AffectedSymbols []sdk.AffectedSymbol `json:"affected_symbols,omitempty"`
Reachability *sdk.Reachability `json:"reachability,omitempty"`
}
VulnerabilityRef identifies one package vulnerability in command outputs.
func VulnerabilityRefsFromPackageVulnerabilities ¶
func VulnerabilityRefsFromPackageVulnerabilities(vulnerabilities []sdk.Vulnerability) []VulnerabilityRef
VulnerabilityRefsFromPackageVulnerabilities converts package vulnerability enrichment into output-friendly values.