detector

Documentation

Overview

Package detector provides the interface for security-related detection plugins.

Index

• type Advisory
• type AdvisoryID
• type CVSS
• type Detector
• type Finding
  • func Run(ctx context.Context, c stats.Collector, detectors []Detector, ...) ([]*Finding, []*plugin.Status, error)
• type Severity
• type SeverityEnum
• type TargetDetails
• type TypeEnum

Types

type Advisory

type Advisory struct {
	// A unique ID for the finding.
	ID   *AdvisoryID
	Type TypeEnum
	// Title, short description and recommendation steps for the finding. Users should be able to rely
	// on these fields to understand the vulnerability and remediate it.
	// Title of the finding, e.g. "CVE-2024-1234 - RCE Vulnerability on Foo".
	Title string
	// Description of the finding, e.g. "Foo prior to version 1.2.3 is affected by a Remote Code
	// Execution vulnerability.".
	Description string
	// Recommendation for how to remediate the finding, e.g. "Upgrade Foo to version 1.2.4 or
	// higher.".
	Recommendation string
	Sev            *Severity
}

Advisory describes a security finding and how to remediate it. It should not contain any information specific to the target (e.g. which files were found vulnerable).

type AdvisoryID

type AdvisoryID struct {
	Publisher string // e.g. "CVE".
	Reference string // e.g. "CVE-2023-1234".
}

AdvisoryID is a unique identifier per advisory.

type CVSS

type CVSS struct {
	BaseScore          float32
	TemporalScore      float32
	EnvironmentalScore float32
}

CVSS contains the CVSS scores for the finding.

type Detector

type Detector interface {
	plugin.Plugin
	// RequiredExtractors returns a list of Extractors that need to be enabled for this
	// Detector to run.
	RequiredExtractors() []string
	// Scan performs the security scan, considering scanRoot to be the root directory.
	// Implementations may use PackageIndex to check if a relevant software package is installed and
	// terminate early if it's not.
	Scan(c context.Context, scanRoot *scalibrfs.ScanRoot, px *packageindex.PackageIndex) ([]*Finding, error)
}

Detector is the interface for a security detector plugin, used to scan for security findings such as vulnerabilities.

type Finding

type Finding struct {
	// Info specific to the finding. Should always be the same for the same type of finding.
	Adv *Advisory
	// Instance-specific info such as location of the vulnerable files.
	Target *TargetDetails
	// Additional free-text info.
	Extra string
	// The name of the Detectors that found this finding. Set by the core library.
	Detectors []string
}

Finding is the security finding found by a detector. It could describe things like a CVE or a CIS non-compliance. TODO(b/400910349): Move from detector into a separate package such as inventory.

func Run

func Run(ctx context.Context, c stats.Collector, detectors []Detector, scanRoot *scalibrfs.ScanRoot, index *packageindex.PackageIndex) ([]*Finding, []*plugin.Status, error)

Run runs the specified detectors and returns their findings, as well as info about whether the plugin runs completed successfully.

type Severity

type Severity struct {
	// Required severity enum. Can be used for e.g. prioritizing filed bugs.
	Severity SeverityEnum
	// Optional CVSS scores, only set for vulns with CVEs.
	CVSSV2 *CVSS
	CVSSV3 *CVSS
}

Severity of the vulnerability.

type SeverityEnum

type SeverityEnum int

SeverityEnum is an enum-based representation of the finding's severity. Some findings don't have a CVE associated so we use this enum instead to signal the urgency of the remediation.

const (
	SeverityUnspecified SeverityEnum = iota
	SeverityMinimal
	SeverityLow
	SeverityMedium
	SeverityHigh
	SeverityCritical
)

SeverityEnum values.

type TargetDetails

type TargetDetails struct {
	// The software affected by the finding. Taken from the Package extraction results.
	Package *extractor.Package
	// Location of vulnerable files not related to the package,
	// e.g. config files with misconfigurations.
	Location []string
}

TargetDetails contains instance-specific details about the security finding.

type TypeEnum

type TypeEnum int

TypeEnum describes what kind of security finding this is. For now the only type is "Vulnerability".

const (
	TypeUnknown TypeEnum = iota
	TypeVulnerability
	TypeCISFinding
)

TypeEnum values.