Documentation
¶
Overview ¶
Package hostvuln correlates the OS packages a fleet host agent reports with vulnerability advisories and exposes the result per host (#820).
A host does not get its own vulnerability pipeline. Each Kind=host asset that reports packages owns one hidden engagement (engagement.HostAssetID, the fleet twin of the Project analysis context). The package list is recorded there as the engagement's active imported SBOM and the existing SCA imported-SBOM scan runs against it: the same detectors, distro-qualified PURL matching, severity backfill, risk ranking, dedup and finding derivation a repository or image scan gets, and the same continuous reconciliation when advisories change. The console reads the findings back through the asset, never through the engagement routes, which keep hiding internal contexts.
Recording is idempotent per package set: the CycloneDX document is a pure function of the packages, so an unchanged host does not re-import or re-scan on every hourly sweep.
Index ¶
- Constants
- func Document(host *asset.Asset, packages []sbom.Component) ([]byte, error)
- func TargetRef(host *asset.Asset) string
- type FindingLister
- type HostPackages
- type HostSummary
- type HostVulnerabilities
- type SBOMScanner
- type Service
- func (s *Service) Hosts(ctx context.Context, tenantID shared.ID) ([]HostSummary, error)
- func (s *Service) Packages(ctx context.Context, tenantID, assetID shared.ID) (*HostPackages, error)
- func (s *Service) Record(ctx context.Context, actor string, tenantID shared.ID, host *asset.Asset, ...) (hostinventory.VulnerabilityOutcome, error)
- func (s *Service) SetFindingSummaries(r ports.FindingSummaryReader)
- func (s *Service) Vulnerabilities(ctx context.Context, tenantID, assetID shared.ID) (*HostVulnerabilities, error)
- type Summary
Constants ¶
const Filename = "host-inventory.cdx.json"
Filename is the artifact name the host package list is recorded under in the imported-SBOM store.
const MaxPackages = 50000
MaxPackages bounds one inventory. A real host carries a few thousand packages; a list far beyond that is not an inventory, and an agent must not be able to make the server render and scan one.
const MinRecordInterval = 10 * time.Minute
MinRecordInterval is the shortest gap between two recorded package sets for one host. The sweep cadence is hourly; a host whose package set changes on every sync is being driven, not maintained, and the server records at most one set per interval instead of importing and scanning each time.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type FindingLister ¶
type FindingLister interface {
List(ctx context.Context, engagementID shared.ID) ([]finding.Finding, error)
}
FindingLister reads the findings of one engagement.
type HostPackages ¶
type HostPackages struct {
Asset *asset.Asset
EngagementID shared.ID
RecordedAt time.Time
Packages []sbom.Component
}
HostPackages is the package inventory recorded for a host: the components of its active SBOM.
type HostSummary ¶
type HostSummary struct {
Asset *asset.Asset
EngagementID shared.ID
Packages int
RecordedAt time.Time
LastScan *ports.ScanJob
Summary Summary
}
HostSummary is the list-view projection of HostVulnerabilities without the findings.
type HostVulnerabilities ¶
type HostVulnerabilities struct {
Asset *asset.Asset
EngagementID shared.ID // zero when the host has never reported packages
Packages int
RecordedAt time.Time
LastScan *ports.ScanJob
Summary Summary
Findings []finding.Finding
}
HostVulnerabilities is one host's recorded package set, its latest scan, and the findings.
type SBOMScanner ¶
type SBOMScanner interface {
ImportContextSBOM(ctx context.Context, actor string, tenantID, engagementID shared.ID, filename string, data []byte) (*scauc.ScanResult, error)
StartScanWithOptions(ctx context.Context, actor string, engagementID shared.ID, req ports.AcquireRequest, opts scauc.ScanOptions) (ports.ScanJob, error)
}
SBOMScanner is the slice of the SCA service this use case drives.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service records host packages and reads host vulnerabilities.
func NewService ¶
func NewService(engagements ports.EngagementRepository, assets ports.AssetRepository, findings FindingLister, scanner SBOMScanner, imported ports.ImportedSBOMStore, jobs ports.ScanJobStore, ids ports.IDGenerator, clock ports.Clock, audit ports.AuditLogger) (*Service, error)
NewService validates its dependencies and constructs the service.
func (*Service) Hosts ¶
Hosts lists every host asset with its vulnerability summary. It is five round trips for the whole fleet, independent of the host count: the host assets, their contexts, the active SBOM metadata, the per-context finding summary and the latest scan jobs. Without a summary reader it falls back to listing each context's findings, which is O(H) reads and fine for a small fleet only.
func (*Service) Packages ¶
Packages returns the OS packages recorded for the host, sorted by name then version. A host without a recorded set returns an empty list with a zero EngagementID.
func (*Service) Record ¶
func (s *Service) Record(ctx context.Context, actor string, tenantID shared.ID, host *asset.Asset, inv dhi.HostInventory) (hostinventory.VulnerabilityOutcome, error)
Record stores the host's packages as its SBOM and queues a vulnerability scan. It returns a skipped outcome when the host reported no packages or when the package set is unchanged since the last recorded scan and that scan did not fail.
func (*Service) SetFindingSummaries ¶
func (s *Service) SetFindingSummaries(r ports.FindingSummaryReader)
SetFindingSummaries wires the aggregate read Hosts uses to count findings per context in one query instead of loading every context's finding rows.
func (*Service) Vulnerabilities ¶
func (s *Service) Vulnerabilities(ctx context.Context, tenantID, assetID shared.ID) (*HostVulnerabilities, error)
Vulnerabilities returns the host's current vulnerability findings, highest risk first.
type Summary ¶
type Summary = ports.VulnerabilitySummary
Summary counts a host's vulnerability findings.
Source Files