triage

package
v1.37.4 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package triage provides a provider abstraction for fetching vulnerability alerts from external sources (GitHub Dependabot, Snyk, etc.) and enriching them with VDB remediation data.

Package triage provides VEX generation for vulnerability triage.

Index

Constants

This section is empty.

Variables

View Source 
var TriageProviders = map[string]func() TriageProvider{}

TriageProviders is the registry of providers that support per-CVE triage.

Functions

func ApplyResolution added in v1.27.2 

func ApplyResolution(ctx context.Context, client *GitHubClient, repo string, a Alert, opt ResolutionOption, rationale string) error

ApplyResolution sends a PATCH request to GitHub to update the alert state. If opt.GitHubState is empty (VEX-only option) the call is skipped.

func ComponentInfo added in v1.27.0 

func ComponentInfo(pkg string) (name, version, ecosystem string)

ComponentInfo extracts package name, version, and ecosystem from a CDX component or PURL.

func DefaultVulnetixDir added in v1.27.2 

func DefaultVulnetixDir() string

DefaultVulnetixDir returns the .vulnetix directory relative to the current working directory, matching the convention used by scan and other commands.

func DetectRepo 

func DetectRepo() string

DetectRepo attempts to detect the current repository from various sources.

func DiscoverCVEs added in v1.27.0 

func DiscoverCVEs(sbomPath, memPath string, all bool, statusFilter string) ([]string, error)

DiscoverCVEs returns a list of CVE IDs to triage.

func GenerateCDXVEX added in v1.27.0 

func GenerateCDXVEX(findings []*TriageFinding, specVersion string) ([]byte, error)

GenerateCDXVEX produces a minimal CycloneDX document with VEX data for the given findings. The output is CycloneDX 1.5 JSON with vulnerabilities declared.

func GenerateOpenVEX added in v1.27.0 

func GenerateOpenVEX(findings []*TriageFinding, opts OpenVEXOptions) ([]byte, error)

GenerateOpenVEX produces an OpenVEX 0.2.0 document from triage findings.

func RecordResolutionInMemory added in v1.27.2 

func RecordResolutionInMemory(vulnetixDir string, a Alert, opt ResolutionOption, rationale string) error

RecordResolutionInMemory persists the chosen resolution to .vulnetix/memory.yaml.

func WriteVEXForResolution added in v1.28.0 

func WriteVEXForResolution(vulnetixDir string, a Alert, opt ResolutionOption, rationale, vexFormat string) (string, error)

WriteVEXForResolution generates a VEX document for the resolved alert and writes it to the memory directory. Returns the file path written.

Types

type Alert 

type Alert struct {
	// Number or ID of the alert in the provider system
	Number string
	// State: "open", "dismissed", "fixed"
	State string
	// CVE identifier (empty for non-CVE alerts like CodeQL rules or secrets)
	CVE string
	// RuleID is the provider-specific rule identifier (e.g. CodeQL "js/bad-tag-filter")
	RuleID string
	// Description is a short summary of the finding
	Description string
	// Severity: "critical", "high", "medium", "low"
	Severity string
	// Package name (e.g. "lodash", "express")
	Package string
	// Current vulnerable version
	Version string
	// Ecosystem as reported by the provider (needs mapping to VDB format)
	Ecosystem string
	// Path to the manifest file containing the vulnerable dependency
	Manifest string
	// URL to the alert in the provider's UI
	URL string
	// Dismissal reason if state is "dismissed"
	DismissalReason string
	// CWE identifier if available
	CWE string
}

Alert represents a normalized vulnerability alert from any provider.

func (Alert) Identifier added in v1.27.2 

func (a Alert) Identifier() string

Identifier returns the best display identifier for the alert: CVE if available, otherwise RuleID, otherwise the alert number.

type CDXBOM added in v1.27.0 

type CDXBOM struct {
	Vulnerabilities []CDXVuln      `json:"vulnerabilities,omitempty"`
	Components      []CDXComponent `json:"components,omitempty"`
}

CDXBOM is a minimal CycloneDX BOM for extracting vulnerability IDs.

type CDXComponent added in v1.27.0 

type CDXComponent struct {
	Name    string `json:"name,omitempty"`
	Version string `json:"version,omitempty"`
	PURL    string `json:"purl,omitempty"`
	BOMRef  string `json:"bom-ref,omitempty"`
}

CDXComponent is a minimal component entry in a BOM.

type CDXVuln added in v1.27.0 

type CDXVuln struct {
	ID string `json:"id"`
}

CDXVuln is a minimal representation of a vulnerability in a CycloneDX BOM.

type CWSSData added in v1.27.0 

type CWSSData struct {
	Score    float64            `json:"score"`
	Priority string             `json:"priority,omitempty"`
	Factors  map[string]float64 `json:"factors,omitempty"`
}

CWSSData holds a CWSS-derived priority score.

type EnrichedAlert 

type EnrichedAlert struct {
	Alert       Alert           `json:"alert"`
	Remediation *map[string]any `json:"remediation,omitempty"`
	Fixes       *FixesMerged    `json:"fixes,omitempty"`
	Error       string          `json:"error,omitempty"`
}

EnrichedAlert holds a provider alert with VDB enrichment data.

type FetchOptions 

type FetchOptions struct {
	IncludeDismissed bool
	Repo             string
}

FetchOptions controls which alerts are retrieved.

type FixesMerged 

type FixesMerged struct {
	Registry      map[string]any
	Distributions map[string]any
	Source        map[string]any
}

FixesMerged holds fix data from multiple sources.

func (*FixesMerged) HasFix 

func (f *FixesMerged) HasFix() bool

HasFix returns true if any fix source has fixes available.

type GHStatus 

type GHStatus struct {
	BinaryFound   bool   `json:"binary_found"`
	BinaryPath    string `json:"binary_path,omitempty"`
	Authenticated bool   `json:"authenticated"`
	User          string `json:"user,omitempty"`
	Host          string `json:"host,omitempty"`
	TokenSource   string `json:"token_source,omitempty"`
	RepoDetected  bool   `json:"repo_detected"`
	Repo          string `json:"repo,omitempty"`
	BinaryError   string `json:"binary_error,omitempty"`
	AuthError     string `json:"auth_error,omitempty"`
}

GHStatus holds the results of GitHub health checks.

func CheckGHAuth 

func CheckGHAuth(client *GitHubClient) GHStatus

CheckGHAuth verifies GitHub API access using the GitHubClient.

type GitHubClient added in v1.27.0 

type GitHubClient struct {
	// contains filtered or unexported fields
}

GitHubClient is a native Go HTTP client for the GitHub REST API. It resolves a token once (from env or gh CLI) and reuses it for all requests.

func NewGitHubClient added in v1.27.0 

func NewGitHubClient() (*GitHubClient, error)

NewGitHubClient creates a GitHubClient by resolving a token from environment variables or the gh CLI (single exec call).

func (*GitHubClient) CheckAuth added in v1.27.0 

func (c *GitHubClient) CheckAuth(ctx context.Context) (string, error)

CheckAuth validates the token by calling GET /user and returns the login name.

func (*GitHubClient) Do added in v1.27.0 

func (c *GitHubClient) Do(ctx context.Context, method, path string, result any) (*http.Response, error)

Do performs an authenticated GitHub API request and decodes the JSON response.

func (*GitHubClient) GetPaginated added in v1.27.0 

func (c *GitHubClient) GetPaginated(ctx context.Context, path string) ([]json.RawMessage, error)

GetPaginated fetches all pages of a paginated GitHub API endpoint, following Link rel="next" headers. Returns concatenated JSON array items.

func (*GitHubClient) PatchCodeQLAlert added in v1.27.2 

func (c *GitHubClient) PatchCodeQLAlert(ctx context.Context, repo string, alertNumber int, reason, comment string) error

PatchCodeQLAlert dismisses a Code Scanning (CodeQL) alert. reason must be one of: false positive, won't fix, used in tests

func (*GitHubClient) PatchDependabotAlert added in v1.27.2 

func (c *GitHubClient) PatchDependabotAlert(ctx context.Context, repo string, alertNumber int, reason, comment string) error

PatchDependabotAlert dismisses a Dependabot alert. reason must be one of: fix_started, no_bandwidth, inaccurate, not_used, tolerable_risk

func (*GitHubClient) PatchSecretAlert added in v1.27.2 

func (c *GitHubClient) PatchSecretAlert(ctx context.Context, repo string, alertNumber int, resolution, comment string) error

PatchSecretAlert resolves a Secret Scanning alert. resolution must be one of: false_positive, wont_fix, revoked, used_in_tests, pattern_noisy, pattern_deleted

func (*GitHubClient) TokenSource added in v1.27.0 

func (c *GitHubClient) TokenSource() string

TokenSource returns how the token was resolved (for status display).

type GitHubMultiProvider added in v1.27.0 

type GitHubMultiProvider struct {
	Client *GitHubClient
	Kinds  []string // subset of "dependabot", "codeql", "secrets"
}

GitHubMultiProvider fetches alerts from one or more GitHub security tools (Dependabot, CodeQL, Secret Scanning) using native HTTP calls.

func NewGitHubMultiProvider added in v1.27.0 

func NewGitHubMultiProvider(client *GitHubClient, kinds []string) *GitHubMultiProvider

NewGitHubMultiProvider creates a multi-provider. Call NewGitHubClient first.

func (*GitHubMultiProvider) FetchAlerts added in v1.27.0 

func (p *GitHubMultiProvider) FetchAlerts(ctx context.Context, opts FetchOptions) ([]Alert, error)

FetchAlerts retrieves alerts from all configured GitHub security tools.

type OpenVEXOptions added in v1.27.0 

type OpenVEXOptions struct {
	// ID is the document identifier. If empty, a URN is generated.
	ID string
	// Author is the document author.
	Author string
	// Tooling identifies the tool that generated the document.
	Tooling string
}

OpenVEXOptions controls OpenVEX document generation.

type Provider 

type Provider interface {
	// FetchAlerts retrieves vulnerability alerts from the provider.
	FetchAlerts(ctx context.Context, opts FetchOptions) ([]Alert, error)
}

Provider is the interface that all triage providers must implement.

func GetProvider 

func GetProvider(name string, client *GitHubClient) (Provider, error)

GetProvider returns the provider for the given name, or an error if unknown. For GitHub-backed providers, a GitHubClient must be supplied.

type ResolutionOption added in v1.27.2 

type ResolutionOption struct {
	// Label is the short display string shown in the TUI list.
	Label string
	// Description is a one-line human explanation shown beneath the label.
	Description string

	// GitHubState is the target GitHub alert state ("dismissed", "resolved", "").
	// Empty means "VEX only" – save to memory without touching the GitHub alert.
	GitHubState string
	// GitHubReason is the dismissal reason (Dependabot/CodeQL) or resolution
	// value (Secret Scanning).  Empty when GitHubState is "".
	GitHubReason string

	// VEXStatus is the OpenVEX / CycloneDX VEX status to persist in memory:
	//   not_affected | affected | fixed | under_investigation
	VEXStatus string
	// VEXJustification is the OpenVEX justification code (used only for
	// not_affected status):
	//   component_not_present | vulnerable_code_not_present |
	//   vulnerable_code_not_in_execute_path |
	//   vulnerable_code_cannot_be_controlled_by_adversary |
	//   inline_mitigations_already_exist
	VEXJustification string
}

ResolutionOption represents one selectable resolution action for an alert. It captures both what to tell GitHub and what to record in VEX/memory.

func OptionsForAlert added in v1.27.2 

func OptionsForAlert(a Alert) []ResolutionOption

OptionsForAlert returns the ordered list of resolution options appropriate for the alert's ecosystem / provider type.

func (ResolutionOption) GitHubOnly added in v1.27.2 

func (r ResolutionOption) GitHubOnly() bool

GitHubOnly returns true when this option produces a GitHub API call.

func (ResolutionOption) VEXBadge added in v1.27.2 

func (r ResolutionOption) VEXBadge() string

VEXBadge returns a short string showing the VEX status (and justification).

type ThreatModel added in v1.27.0 

type ThreatModel struct {
	Techniques         []string `json:"techniques,omitempty"`
	Tactics            []string `json:"tactics,omitempty"`
	AttackVector       string   `json:"attack_vector,omitempty"`
	AttackComplexity   string   `json:"attack_complexity,omitempty"`
	PrivilegesRequired string   `json:"privileges_required,omitempty"`
	UserInteraction    string   `json:"user_interaction,omitempty"`
	Reachability       string   `json:"reachability,omitempty"`
	Exposure           string   `json:"exposure,omitempty"`
}

ThreatModel holds MITRE ATT&CK-derived threat modelling data.

type TriageFinding added in v1.27.0 

type TriageFinding struct {
	CVEID          string
	Package        string
	Ecosystem      string
	InstalledVer   string
	FixedVer       string
	Status         string // not_affected | affected | fixed | under_investigation
	Justification  string // VEX justification for not_affected
	ActionResponse string // VEX action for affected
	Severity       string // critical | high | medium | low | unknown
	SafeHarbour    float64
	ThreatModel    *ThreatModel
	CWSS           *CWSSData
	Decision       *memory.Decision
	History        []memory.HistoryEntry
	Source         string // "vulnetix" | "github"
	ExploitCount   int
	InKEV          bool
}

TriageFinding holds all triage data for a single vulnerability, aligned with the SKILL file memory schema.

type TriageProvider added in v1.27.0 

type TriageProvider interface {
	Provider
	// TriageCVE fetches full vulnerability intelligence for a single CVE and
	// maps it to a TriageFinding (with CWSS, threat model, VEX status).
	TriageCVE(ctx context.Context, cveID string, pkgName, pkgVersion, ecosystem string, existing *memory.FindingRecord) (*TriageFinding, error)
}

TriageProvider extends Provider with per-CVE triage capability.

func GetTriageProvider added in v1.27.0 

func GetTriageProvider(name string) (TriageProvider, error)

GetTriageProvider returns a triage-capable provider for the given name.

type VulnetixProvider added in v1.27.0 

type VulnetixProvider struct {
	// contains filtered or unexported fields
}

VulnetixProvider fetches triage data from the Vulnetix VDB API.

func NewVulnetixProvider added in v1.27.0 

func NewVulnetixProvider(v1, v2 *vdb.Client) *VulnetixProvider

NewVulnetixProvider creates a new Vulnetix provider from the given VDB client. The v1 client is used for vuln/exploit lookups; the v2 client for affected ranges, remediation plans, and scorecard data.

func (*VulnetixProvider) FetchAlerts added in v1.27.0 

func (p *VulnetixProvider) FetchAlerts(ctx context.Context, opts FetchOptions) ([]Alert, error)

FetchAlerts is not implemented for the Vulnetix provider — it only supports per-CVE triage via TriageCVE. Returns nil to satisfy Provider interface.

func (*VulnetixProvider) TriageCVE added in v1.27.0 

func (p *VulnetixProvider) TriageCVE(ctx context.Context, cveID string, pkgName, pkgVersion, ecosystem string, existing *memory.FindingRecord) (*TriageFinding, error)

TriageCVE fetches full vulnerability intelligence from the VDB and maps it to a TriageFinding with CWSS score, threat model, and VEX status.

Source Files

View all Source files

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.