Documentation
¶
Overview ¶
Package vulnerability provides core domain types for vulnerability identification and classification.
This package contains stable value types that represent vulnerability-related identifiers and metadata. Unlike the [intel] package which handles external data sources requiring network calls, this package is pure: no network calls, filesystem access, or global state.
Package Organization ¶
The vulnerability domain is organized into conceptually meaningful subpackages:
- vulnerability/id/cve: CVE identifier handling and validation
- vulnerability/severity/cvss: CVSS vector parsing and scoring
- vulnerability/severity: Deputy's normalized severity levels
- vulnerability/weakness/cwe: CWE identifier handling
- vulnerability/affected/cpe: CPE identifier handling for NVD matching
- vulnerability/intel: External intelligence (KEV, EPSS) enrichment
CWE (Common Weakness Enumeration) ¶
CWEs categorize software weaknesses that can lead to vulnerabilities. They're useful for understanding root causes and grouping similar issues:
import "github.com/picatz/deputy/internal/vulnerability/weakness/cwe"
id := cwe.Parse("CWE-79")
if id.IsValid() {
fmt.Printf("XSS vulnerability: %s\n", id.URL())
}
CPE (Common Platform Enumeration) ¶
CPEs identify software products for NVD vulnerability matching. Generation from PURLs is heuristic-based:
import "github.com/picatz/deputy/internal/vulnerability/affected/cpe"
gen := cpe.NewGenerator()
c := gen.FromPURL("golang", "github.com/foo", "bar", "1.0.0")
if c.IsValid() {
fmt.Printf("Vendor: %s, Product: %s\n", c.Vendor(), c.Product())
}
Severity and CVSS ¶
The package provides severity classification and CVSS score parsing:
import "github.com/picatz/deputy/internal/vulnerability/severity/cvss"
score := cvss.ParseScore("CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H")
fmt.Printf("Score: %.1f\n", score) // 9.8
level := cvss.LevelFromScore(score)
fmt.Printf("Level: %s\n", level) // CRITICAL
Advisory and Finding ¶
Higher-level types for vulnerability records:
- [Advisory]: Vulnerability as published by an upstream source
- Finding: Scan-time occurrence of an advisory in a dependency
Design Principles ¶
This package is intentionally pure and composable:
- No network calls or filesystem access
- All types are safe for concurrent use
- Parsing functions handle common input variations gracefully
- Invalid inputs return zero values rather than errors where sensible
Index ¶
- Constants
- func AdvisoryCWEs(a *vulnerabilityv1.Advisory) []cwe.ID
- func AdvisoryModified(a *vulnerabilityv1.Advisory) time.Time
- func AdvisoryPublished(a *vulnerabilityv1.Advisory) time.Time
- func CloneAffectedImports(imports []vulnerabilityv1.AffectedImport) []vulnerabilityv1.AffectedImport
- func FindBestFixedVersion(fixed []string, current string) string
- func MergeAdvisory(base, extra *vulnerabilityv1.Advisory) *vulnerabilityv1.Advisory
- func MergeAffectedImports(importSets ...[]vulnerabilityv1.AffectedImport) []vulnerabilityv1.AffectedImport
- func MergeSeverity(base, extra *vulnerabilityv1.Severity) *vulnerabilityv1.Severity
- func MergeStringMap(base map[string]string, extra map[string]string) map[string]string
- func MergeUniqueStrings(base, extra []string) []string
- func NewAdvisory(id string) *vulnerabilityv1.Advisory
- func NewSeverity(raw, rawType string) *vulnerabilityv1.Severity
- func NewStats() *vulnerabilityv1.Stats
- func ParseSeverityLevel(raw string) vulnerabilityv1.SeverityLevel
- func ParseSeverityType(raw string) vulnerabilityv1.SeverityType
- func ParseTimeRFC3339(raw string) time.Time
- func SetAdvisoryCWEs(a *vulnerabilityv1.Advisory, cwes []cwe.ID)
- func SetAdvisoryModified(a *vulnerabilityv1.Advisory, t time.Time)
- func SetAdvisoryPublished(a *vulnerabilityv1.Advisory, t time.Time)
- func SeverityFromCVSS(score float64) vulnerabilityv1.SeverityLevel
- func StatsFromConsolidated(cons []Consolidated, totalFindings int) vulnerabilityv1.Stats
- type Consolidated
- type ConsolidatedResult
- type Finding
Constants ¶
const ( SeverityUnknown = vulnerabilityv1.SeverityLevel_SEVERITY_LEVEL_UNSPECIFIED SeverityLow = vulnerabilityv1.SeverityLevel_SEVERITY_LEVEL_LOW SeverityMedium = vulnerabilityv1.SeverityLevel_SEVERITY_LEVEL_MEDIUM SeverityHigh = vulnerabilityv1.SeverityLevel_SEVERITY_LEVEL_HIGH SeverityCritical = vulnerabilityv1.SeverityLevel_SEVERITY_LEVEL_CRITICAL )
SeverityLevel constants using proto enum values directly.
const ( SeverityTypeUnknown = vulnerabilityv1.SeverityType_SEVERITY_TYPE_UNSPECIFIED SeverityTypeCVSSv2 = vulnerabilityv1.SeverityType_SEVERITY_TYPE_CVSS_V2 SeverityTypeCVSSv3 = vulnerabilityv1.SeverityType_SEVERITY_TYPE_CVSS_V3 SeverityTypeCVSSv4 = vulnerabilityv1.SeverityType_SEVERITY_TYPE_CVSS_V4 SeverityTypeGHSA = vulnerabilityv1.SeverityType_SEVERITY_TYPE_GHSA SeverityTypeCustom = vulnerabilityv1.SeverityType_SEVERITY_TYPE_CUSTOM )
SeverityType constants using proto enum values directly.
Variables ¶
This section is empty.
Functions ¶
func AdvisoryCWEs ¶
func AdvisoryCWEs(a *vulnerabilityv1.Advisory) []cwe.ID
AdvisoryCWEs returns the CWEs as []cwe.ID for backward compatibility.
func AdvisoryModified ¶
func AdvisoryModified(a *vulnerabilityv1.Advisory) time.Time
AdvisoryModified returns the Modified timestamp as time.Time. Returns zero time if Modified is nil.
func AdvisoryPublished ¶
func AdvisoryPublished(a *vulnerabilityv1.Advisory) time.Time
AdvisoryPublished returns the Published timestamp as time.Time. Returns zero time if Published is nil.
func CloneAffectedImports ¶
func CloneAffectedImports(imports []vulnerabilityv1.AffectedImport) []vulnerabilityv1.AffectedImport
CloneAffectedImports deep clones a slice of AffectedImport. Returns nil if imports is empty or nil.
func FindBestFixedVersion ¶
FindBestFixedVersion selects the smallest applicable fix >= current. It preserves the original version format from the fixed slice.
func MergeAdvisory ¶
func MergeAdvisory(base, extra *vulnerabilityv1.Advisory) *vulnerabilityv1.Advisory
MergeAdvisory combines two Advisory pointer records, preferring non-empty values from base and filling in gaps from extra. Slice fields are merged with deduplication. Timestamps are merged by taking the earliest Published and latest Modified. Returns nil if both inputs are nil.
func MergeAffectedImports ¶
func MergeAffectedImports(importSets ...[]vulnerabilityv1.AffectedImport) []vulnerabilityv1.AffectedImport
MergeAffectedImports deduplicates import paths and symbols across multiple sets. Callers can pass multiple slices and receive a merged, sorted result.
func MergeSeverity ¶
func MergeSeverity(base, extra *vulnerabilityv1.Severity) *vulnerabilityv1.Severity
MergeSeverity combines two Severity records, preferring the higher severity level and filling in empty Raw/RawType fields from extra.
func MergeStringMap ¶
MergeStringMap combines two string maps, keeping existing entries in base when keys collide. Empty keys and values are skipped. The base map may be mutated.
func MergeUniqueStrings ¶
MergeUniqueStrings combines two string slices, preserving order and removing duplicates and empty strings. Items from extra are appended if not already present.
func NewAdvisory ¶
func NewAdvisory(id string) *vulnerabilityv1.Advisory
NewAdvisory creates an Advisory with the common fields populated. This is a convenience constructor.
func NewSeverity ¶
func NewSeverity(raw, rawType string) *vulnerabilityv1.Severity
NewSeverity creates a Severity from raw value and type. This is a convenience wrapper around severity.FromRaw.
func NewStats ¶
func NewStats() *vulnerabilityv1.Stats
NewStats creates a new Stats instance with zero values.
func ParseSeverityLevel ¶
func ParseSeverityLevel(raw string) vulnerabilityv1.SeverityLevel
ParseSeverityLevel converts a string into a SeverityLevel. This is a convenience wrapper around severity.ParseLevel.
func ParseSeverityType ¶
func ParseSeverityType(raw string) vulnerabilityv1.SeverityType
ParseSeverityType converts a string into a SeverityType. This is a convenience wrapper around severity.ParseType.
func ParseTimeRFC3339 ¶
ParseTimeRFC3339 parses a timestamp in RFC3339 format or date-only (YYYY-MM-DD) format. Returns zero time if raw is empty or unparseable.
func SetAdvisoryCWEs ¶
func SetAdvisoryCWEs(a *vulnerabilityv1.Advisory, cwes []cwe.ID)
SetAdvisoryCWEs sets the CWEs from []cwe.ID.
func SetAdvisoryModified ¶
func SetAdvisoryModified(a *vulnerabilityv1.Advisory, t time.Time)
SetAdvisoryModified sets the Modified timestamp from time.Time. Sets to nil if t is zero.
func SetAdvisoryPublished ¶
func SetAdvisoryPublished(a *vulnerabilityv1.Advisory, t time.Time)
SetAdvisoryPublished sets the Published timestamp from time.Time. Sets to nil if t is zero.
func SeverityFromCVSS ¶
func SeverityFromCVSS(score float64) vulnerabilityv1.SeverityLevel
SeverityFromCVSS maps a CVSS score to a severity level. This is a convenience wrapper around severity.FromCVSS.
func StatsFromConsolidated ¶
func StatsFromConsolidated(cons []Consolidated, totalFindings int) vulnerabilityv1.Stats
StatsFromConsolidated computes aggregate stats from consolidated records.
Types ¶
type Consolidated ¶
type Consolidated struct {
PrimaryID string
SecondaryIDs []string
AllIDs []string
HiddenAliasCount int
Summary string
Details string
Severity string
SeverityType string
Package string
Version string
IsDirect bool
Ecosystem string
PURL string
Published string
Modified string
References []string
FixedVersions []string
RelatedCount int
Locations []string
ManifestRefs []dependencyv1.ManifestRef
AffectedImports []vulnerabilityv1.AffectedImport
DatabaseSpecific map[string]string
// LayerDetails contains information about the container image layer where
// the vulnerable package was found. Nil for non-container-image scans.
LayerDetails *containerv1.LayerDetails
}
Consolidated represents a deduplicated vulnerability record formed by merging findings that share common aliases.
func Consolidate ¶
func Consolidate(findings []Finding, advisories map[string]*vulnerabilityv1.Advisory) []Consolidated
Consolidate groups findings by advisory aliases and returns consolidated records.
type ConsolidatedResult ¶
type ConsolidatedResult struct {
Vulnerabilities []Consolidated
Stats vulnerabilityv1.Stats
}
ConsolidatedResult bundles consolidated vulnerabilities with their computed stats. This avoids the common pattern of calling Consolidate then StatsFromConsolidated separately.
func ConsolidateAll ¶
func ConsolidateAll(findings []Finding, advisories map[string]*vulnerabilityv1.Advisory) ConsolidatedResult
ConsolidateAll groups findings by advisory aliases and computes stats in one pass. This is the preferred API when you need both consolidated records and statistics.
type Finding ¶
type Finding struct {
AdvisoryID string
Dependency dependency.ID
Version string
Direct bool
Locations []string
ManifestRefs []dependencyv1.ManifestRef
AffectedImports []vulnerabilityv1.AffectedImport
Affected bool
// LayerDetails contains information about the container image layer where
// the vulnerable package was found. Nil for non-container-image scans.
LayerDetails *containerv1.LayerDetails
// Enrichment fields - populated when enrichment is enabled.
// EPSS is the Exploit Prediction Scoring System score (0.0-1.0).
EPSS *float64
// EPSSPercentile indicates what percentage of CVEs have a lower EPSS score.
EPSSPercentile *float64
// InKEV indicates whether this CVE is in CISA's Known Exploited Vulnerabilities catalog.
InKEV *bool
}
Finding represents a scan-time occurrence of an advisory in a dependency.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package affected provides affected product identification for vulnerabilities.
|
Package affected provides affected product identification for vulnerabilities. |
|
cpe
Package cpe provides CPE (Common Platform Enumeration) identifier handling.
|
Package cpe provides CPE (Common Platform Enumeration) identifier handling. |
|
Package id provides vulnerability identifier parsing and validation.
|
Package id provides vulnerability identifier parsing and validation. |
|
cve
Package cve provides CVE (Common Vulnerabilities and Exposures) identifier handling.
|
Package cve provides CVE (Common Vulnerabilities and Exposures) identifier handling. |
|
Package intel provides threat intelligence enrichment for vulnerabilities.
|
Package intel provides threat intelligence enrichment for vulnerabilities. |
|
epss
Package epss provides a client for FIRST's Exploit Prediction Scoring System.
|
Package epss provides a client for FIRST's Exploit Prediction Scoring System. |
|
kev
Package kev provides a client for the CISA Known Exploited Vulnerabilities catalog.
|
Package kev provides a client for the CISA Known Exploited Vulnerabilities catalog. |
|
Package severity provides vulnerability severity classification and normalization.
|
Package severity provides vulnerability severity classification and normalization. |
|
cvss
Package cvss provides CVSS (Common Vulnerability Scoring System) parsing and scoring.
|
Package cvss provides CVSS (Common Vulnerability Scoring System) parsing and scoring. |
|
Package ssvc implements Stakeholder-Specific Vulnerability Categorization.
|
Package ssvc implements Stakeholder-Specific Vulnerability Categorization. |
|
Package suppression provides vulnerability suppression via VEX documents.
|
Package suppression provides vulnerability suppression via VEX documents. |
|
Package weakness provides weakness classification for vulnerabilities.
|
Package weakness provides weakness classification for vulnerabilities. |
|
cwe
Package cwe provides CWE (Common Weakness Enumeration) identifier handling.
|
Package cwe provides CWE (Common Weakness Enumeration) identifier handling. |