security

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 4, 2026 License: MIT Imports: 2 Imported by: 0

Documentation

Overview

Package security defines semantic types for security findings — vulnerabilities in code, dependencies, and configuration — and projects them into the domain-neutral findingspec.Finding.

The model separates inherent severity (the intrinsic weakness) from residual severity (the risk that remains after verified compensating controls), so a control reduces residual risk without relabeling the underlying vulnerability. These concepts were first prototyped in github.com/grokify/govex; this package re-expresses them cleanly against the findingspec core vocabulary and does not depend on govex.

Index

Constants

View Source 
const (
	ControlFunctionPreventive = "preventive"
	ControlFunctionDetective  = "detective"
	ControlFunctionCorrective = "corrective"
)

Control functions describe how a compensating control acts on risk.

View Source 
const (
	ReducesLikelihood = "likelihood"
	ReducesImpact     = "impact"
)

Risk dimensions a control can reduce.

View Source 
const (
	ExceptionStatusRequested = "requested"
	ExceptionStatusApproved  = "approved"
	ExceptionStatusRejected  = "rejected"
	ExceptionStatusExpired   = "expired"
)

Exception statuses.

View Source 
const (
	// TypeSAST is a static application security testing finding (code analysis).
	TypeSAST = "sast"
	// TypeDAST is a dynamic application security testing finding (running app).
	TypeDAST = "dast"
	// TypeSCA is a software composition analysis finding (dependency vuln).
	TypeSCA = "sca"
	// TypeSecret is a detected secret or credential.
	TypeSecret = "secret"
	// TypeContainer is a container image scan finding.
	TypeContainer = "container"
	// TypeIaC is an infrastructure-as-code scan finding.
	TypeIaC = "iac"
	// TypeCloudConfig is a cloud posture / configuration finding (CSPM).
	TypeCloudConfig = "cloud-config"
	// TypeRuntime is a runtime host/workload finding (e.g. AWS Inspector,
	// endpoint agents).
	TypeRuntime = "runtime"
	// TypePentest is a penetration-test finding.
	TypePentest = "pentest"
)

Finding types within the security domain — the second level of the findingspec Domain+Type taxonomy. A producer or adapter sets one of these as findingspec.Finding.Type so consumers know how to read Detail.

Variables

This section is empty.

Functions

func ParseScannerSeverity 

func ParseScannerSeverity(s string) findingspec.Severity

ParseScannerSeverity maps a scanner's severity label to the canonical findingspec.Severity. It accepts the standard levels and their aliases (Critical/High/Medium/Low/Informational, "S2", etc. via findingspec), and maps any unrecognized or below-Low label — Grype's "Negligible", Inspector's "Untriaged", "Unknown", "None", or empty — to Informational, so every scanner finding lands in a canonical bucket.

func SeverityOrCVSS 

func SeverityOrCVSS(label string, cvssScore float64) findingspec.Severity

SeverityOrCVSS returns the canonical severity for a scanner label, falling back to the CVSS-derived severity when the label is unrecognized and a CVSS base score is available (score > 0).

Types

type Artifact 

type Artifact struct {
	// Image is the container image reference (e.g. "alpine:3.19",
	// "123.dkr.ecr.us-east-1.amazonaws.com/app:sha-abc").
	Image string `json:"image,omitempty"`
	// ImageDigest is the image digest (e.g. "sha256:…").
	ImageDigest string `json:"imageDigest,omitempty"`
	// OS is the operating system / distro of the image (e.g. "alpine 3.19",
	// "amazon linux 2").
	OS string `json:"os,omitempty"`
	// Layer is the image layer (diffID or layer digest) the package came from.
	Layer string `json:"layer,omitempty"`
}

Artifact is the scanned image or filesystem the vulnerable package was found in. A non-empty Image indicates a container scan (type "container") rather than a plain dependency scan (type "sca").

type CVSS 

type CVSS struct {
	// Version is the CVSS version, e.g. "3.1" or "4.0".
	Version string `json:"version,omitempty"`
	// Vector is the CVSS vector string.
	Vector string `json:"vector,omitempty"`
	// Score is the numeric base score in the range 0.0–10.0.
	Score float64 `json:"score"`
}

CVSS holds a Common Vulnerability Scoring System result.

func (CVSS) Severity 

func (c CVSS) Severity() findingspec.Severity

Severity maps the CVSS score to the canonical severity scale using the standard CVSS v3.x / v4.0 bands (see findingspec.SeverityFromCVSS). Scores outside 0.0–10.0 map to Informational.

CVSS v2 used a different, coarser scale; callers scoring v2 vectors should map severity explicitly rather than rely on this method.

type Control 

type Control struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// Function is preventive, detective, or corrective.
	Function string `json:"function,omitempty"`
	// Reduces lists the risk dimensions this control mitigates (likelihood,
	// impact).
	Reduces []string `json:"reduces,omitempty"`
	// ModifiedMetrics lists CVSS environmental metrics this control justifies,
	// e.g. "MAV:A".
	ModifiedMetrics []string `json:"modifiedMetrics,omitempty"`
	// Effectiveness is a coarse rating: high, medium, or low.
	Effectiveness  string     `json:"effectiveness,omitempty"`
	Verified       bool       `json:"verified,omitempty"`
	VerifiedMethod string     `json:"verifiedMethod,omitempty"`
	LastVerifiedAt *time.Time `json:"lastVerifiedAt,omitempty"`
	Owner          string     `json:"owner,omitempty"`
}

Control is a compensating control that reduces the residual risk of a vulnerability. It links the control to the risk dimensions it reduces and, optionally, the CVSS environmental metrics it justifies.

type Disclosure 

type Disclosure struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`

	// Kind categorizes the disclosure.
	Kind DisclosureKind `json:"kind,omitempty"`
	// Category further classifies the disclosure within its Kind, e.g.
	// "customer", "partner", "codename" for DisclosureKindEntity.
	Category string `json:"category,omitempty"`
	// Detector is the rule or pattern that matched, e.g. a policy entity
	// rule ID or "path-local-home".
	Detector string `json:"detector,omitempty"`
	// Redacted is a masked preview of the offending text, e.g. "A*******p".
	// The raw value must not be stored here.
	Redacted string `json:"redacted,omitempty"`

	// Severity is the impact; defaults to High when unset.
	Severity findingspec.Severity `json:"severity,omitempty"`

	// Location is where the disclosure was found. For a structured document,
	// set Location.File, Location.DocFormat (e.g. "openapi", "postman"), and
	// Location.Pointer (an RFC 6901 JSON Pointer to the offending node).
	Location    *findingspec.Location    `json:"location,omitempty"`
	Remediation *findingspec.Remediation `json:"remediation,omitempty"`
	Status      findingspec.Status       `json:"status,omitempty"`
	Tags        []string                 `json:"tags,omitempty"`
	DetectedAt  *time.Time               `json:"detectedAt,omitempty"`
}

Disclosure is a security finding for unintended exposure of information that policy prohibits publishing, found in source, a config file, or a structured document such as an OpenAPI spec or Postman collection.

The offending text is never stored in full; only a redacted preview. The exact location within a structured document is carried on Location.Pointer (a JSON Pointer) together with Location.DocFormat, the same as Secret.

func (Disclosure) ToFinding 

func (d Disclosure) ToFinding() findingspec.Finding

ToFinding projects the disclosure into a domain-neutral findingspec.Finding in the security domain. Severity defaults to High when unset. The finding never carries the raw offending text — only the redacted preview and its location.

type DisclosureKind 

type DisclosureKind string

DisclosureKind categorizes the kind of unintended information exposure a Disclosure records. Unlike Secret (a credential) or Vulnerability (a weakness), a Disclosure is information that policy prohibits publishing regardless of whether it grants access to anything. 

const (
	// DisclosureKindEntity is a restricted entity reference — a customer,
	// partner, reporter name, or internal codename — that policy prohibits
	// disclosing, typically matched against a curated term list.
	DisclosureKindEntity DisclosureKind = "entity"
	// DisclosureKindLocalPath is a local filesystem or user-identity leak,
	// e.g. a username embedded in an absolute path, or an absolute local
	// path in a config file that should be relative or environment-derived.
	DisclosureKindLocalPath DisclosureKind = "local_path"
)

type Exception 

type Exception struct {
	Status     string     `json:"status,omitempty"`
	ApprovedAt *time.Time `json:"approvedAt,omitempty"`
	ApprovedBy string     `json:"approvedBy,omitempty"`
	ExpiresAt  *time.Time `json:"expiresAt,omitempty"`
	Reference  string     `json:"reference,omitempty"`
	URL        string     `json:"url,omitempty"`
}

Exception records the approval state of a risk exception for a vulnerability. SLA policy: the remediation clock runs on inherent severity until an exception is approved, after which it runs on residual severity while the approval is in effect.

func (*Exception) IsApprovedAt 

func (ex *Exception) IsApprovedAt(t time.Time) bool

IsApprovedAt reports whether the exception is approved and unexpired as of t. A nil receiver reports false.

type Exploitability 

type Exploitability string

Exploitability describes the maturity of exploitation for a vulnerability. 

const (
	ExploitabilityNone       Exploitability = "none"
	ExploitabilityPOC        Exploitability = "poc"
	ExploitabilityFunctional Exploitability = "functional"
	ExploitabilityActive     Exploitability = "active" // observed exploitation in the wild
)

type Fix 

type Fix struct {
	// State is the remediation state.
	State FixState `json:"state,omitempty"`
	// Versions are the package versions that resolve the vulnerability.
	Versions []string `json:"versions,omitempty"`
}

Fix describes how a package vulnerability is remediated.

type FixState 

type FixState string

FixState describes remediation availability for a package vulnerability. 

const (
	FixStateFixed    FixState = "fixed"
	FixStateNotFixed FixState = "not-fixed"
	FixStateWontFix  FixState = "wont-fix"
	FixStateUnknown  FixState = "unknown"
)

type Package 

type Package struct {
	// Name is the package name (e.g. "log4j-core", "openssl", "lodash").
	Name string `json:"name,omitempty"`
	// Version is the installed version.
	Version string `json:"version,omitempty"`
	// Ecosystem is the package ecosystem / type, e.g. "npm", "pypi", "gem",
	// "maven", "golang", "apk", "deb", "rpm".
	Ecosystem string `json:"ecosystem,omitempty"`
	// PURL is the package URL (purl spec), when available.
	PURL string `json:"purl,omitempty"`
	// Path is the file path where the package was found within the artifact.
	Path string `json:"path,omitempty"`
	// Arch is the package architecture (e.g. "x86_64"), for OS packages.
	Arch string `json:"arch,omitempty"`
}

Package identifies a software package (dependency or OS package) that a vulnerability affects. It is the canonical package shape that SCA and container scanners (Grype, Trivy, AWS Inspector, …) normalize into.

type Reachability 

type Reachability struct {
	// State is the reachability determination.
	State ReachabilityState `json:"state,omitempty"`
	// Symbol is the vulnerable symbol in question, e.g.
	// "golang.org/x/net/http2.processHeaders".
	Symbol string `json:"symbol,omitempty"`
	// Paths are example call chains from an application entry point to the
	// vulnerable symbol, each rendered as "entry → … → symbol".
	Paths []string `json:"paths,omitempty"`
}

Reachability captures call-graph reachability for a vulnerability — a primary prioritization signal: a reachable vulnerability is exploitable, while an unreachable one is typically noise. It is populated by analyzers that perform call-graph analysis (e.g. govulncheck); most scanners leave it nil.

func (*Reachability) IsReachable 

func (r *Reachability) IsReachable() bool

IsReachable reports whether the state is reachable. A nil receiver is not reachable.

type ReachabilityState 

type ReachabilityState string

ReachabilityState describes whether a vulnerable symbol is actually reachable from the scanned application's own code, per call-graph analysis. 

const (
	// ReachabilityReachable means the vulnerable symbol is called (in the call
	// graph) — the vulnerability is exploitable and should be prioritized.
	ReachabilityReachable ReachabilityState = "reachable"
	// ReachabilityUnreachable means the vulnerable package is present (imported
	// or required) but its vulnerable symbol is never called — usually
	// deprioritizable noise.
	ReachabilityUnreachable ReachabilityState = "unreachable"
	// ReachabilityUnknown means reachability was not determined (no call-graph
	// analysis was performed).
	ReachabilityUnknown ReachabilityState = "unknown"
)

type Secret 

type Secret struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`

	// Kind categorizes the secret.
	Kind SecretKind `json:"kind,omitempty"`
	// Detector is the rule or detector that matched, e.g. "aws-access-key-id"
	// or "stripe-secret-key".
	Detector string `json:"detector,omitempty"`
	// Provider is the service the secret belongs to, e.g. "aws", "stripe",
	// "github", when known.
	Provider string `json:"provider,omitempty"`
	// Redacted is a masked preview of the secret, e.g. "AKIA****…****1234".
	// The raw value must not be stored here.
	Redacted string `json:"redacted,omitempty"`
	// Entropy is the Shannon entropy of the match, when computed.
	Entropy float64 `json:"entropy,omitempty"`
	// Validation records whether the secret was confirmed live.
	Validation SecretValidation `json:"validation,omitempty"`

	// Severity is the impact; defaults to High when unset, since an exposed
	// live credential is typically high-impact.
	Severity findingspec.Severity `json:"severity,omitempty"`

	// Location is where the secret was found. For a structured document, set
	// Location.File, Location.DocFormat (e.g. "openapi", "postman"), and
	// Location.Pointer (an RFC 6901 JSON Pointer to the offending node).
	Location    *findingspec.Location    `json:"location,omitempty"`
	Remediation *findingspec.Remediation `json:"remediation,omitempty"`
	Status      findingspec.Status       `json:"status,omitempty"`
	DetectedAt  *time.Time               `json:"detectedAt,omitempty"`
}

Secret is a security finding for a detected credential or secret — for example an API key, token, password, or private key discovered in source, a config file, or a structured document such as an OpenAPI spec or Postman collection.

The raw secret value is never stored; only a redacted preview. The exact location within a structured document is carried on Location.Pointer (a JSON Pointer) together with Location.DocFormat.

func (Secret) ToFinding 

func (s Secret) ToFinding() findingspec.Finding

ToFinding projects the secret into a domain-neutral findingspec.Finding in the security domain. Severity defaults to High when unset. The finding never carries the raw secret — only the redacted preview and its location. Redacted is copied into a copy of Location's Snippet field when Location is set and does not already carry one, so a consumer that only looks at the generic Finding still sees the redacted preview.

type SecretDetail 

type SecretDetail struct {
	Kind       SecretKind       `json:"kind,omitempty"`
	Detector   string           `json:"detector,omitempty"`
	Provider   string           `json:"provider,omitempty"`
	Redacted   string           `json:"redacted,omitempty"`
	Entropy    float64          `json:"entropy,omitempty"`
	Validation SecretValidation `json:"validation,omitempty"`
}

SecretDetail is the per-type Detail payload for a secret finding (findingspec.Finding.Type == TypeSecret). It holds the secret-specific fields not already promoted to the canonical header; it never contains the raw secret, only the redacted preview.

type SecretKind 

type SecretKind string

SecretKind categorizes a detected secret. 

const (
	SecretKindAPIKey           SecretKind = "api_key"
	SecretKindToken            SecretKind = "token"
	SecretKindPassword         SecretKind = "password"
	SecretKindPrivateKey       SecretKind = "private_key"
	SecretKindCertificate      SecretKind = "certificate"
	SecretKindConnectionString SecretKind = "connection_string"
	SecretKindGeneric          SecretKind = "generic"
)

type SecretValidation 

type SecretValidation string

SecretValidation records whether a detected secret was verified against its provider (i.e. confirmed live), when a detector supports validation. 

const (
	SecretValidationUnknown  SecretValidation = "unknown"
	SecretValidationActive   SecretValidation = "active"
	SecretValidationInactive SecretValidation = "inactive"
)

type Vulnerability 

type Vulnerability struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`

	// Type is the security finding class, e.g. TypeSCA, TypeSAST, TypeContainer,
	// or TypeRuntime. It flows to findingspec.Finding.Type. Optional.
	Type string `json:"type,omitempty"`

	// Classification identifiers.
	CVEs []string `json:"cves,omitempty"`
	CWEs []string `json:"cwes,omitempty"`
	CVSS *CVSS    `json:"cvss,omitempty"`

	// Severity is the inherent severity of the weakness. ResidualSeverity is
	// the severity that remains after verified compensating controls; it is
	// only meaningful once an exception is approved and in effect.
	Severity         findingspec.Severity `json:"severity"`
	ResidualSeverity findingspec.Severity `json:"residualSeverity,omitempty"`

	// Exposure.
	Exploitability Exploitability `json:"exploitability,omitempty"`
	// Reachable is the coarse boolean reachability signal, for scanners that
	// only report yes/no. When Reachability is also set, its state supersedes
	// this field.
	Reachable *bool `json:"reachable,omitempty"`
	// Reachability is the detailed call-graph reachability — state, vulnerable
	// symbol, and example call paths — from analyzers like govulncheck. It is a
	// primary prioritization signal.
	Reachability *Reachability `json:"reachability,omitempty"`

	// Package / artifact context (SCA and container scans). Package identifies
	// the affected dependency or OS package; Fix its remediation; Artifact the
	// image it was found in (a non-empty Artifact.Image implies a container
	// scan, type "container", vs a plain dependency scan, type "sca").
	Package  *Package  `json:"package,omitempty"`
	Fix      *Fix      `json:"fix,omitempty"`
	Artifact *Artifact `json:"artifact,omitempty"`

	// Residual-risk model.
	Controls  []Control  `json:"controls,omitempty"`
	Exception *Exception `json:"exception,omitempty"`

	// Provenance.
	Component   string                   `json:"component,omitempty"`
	Location    *findingspec.Location    `json:"location,omitempty"`
	References  []findingspec.Reference  `json:"references,omitempty"`
	Remediation *findingspec.Remediation `json:"remediation,omitempty"`

	Status     findingspec.Status `json:"status,omitempty"`
	Tags       []string           `json:"tags,omitempty"`
	DetectedAt *time.Time         `json:"detectedAt,omitempty"`
}

Vulnerability is a semantic security finding: a weakness in code, a dependency, or configuration. It records inherent severity and, separately, residual severity after verified compensating controls.

func (Vulnerability) EffectiveSeverity 

func (v Vulnerability) EffectiveSeverity(t time.Time) findingspec.Severity

EffectiveSeverity returns the severity in effect as of t: the residual severity while an exception is approved and unexpired (and a residual severity is set), otherwise the inherent severity.

func (Vulnerability) ToFinding 

func (v Vulnerability) ToFinding() findingspec.Finding

ToFinding projects the vulnerability into a domain-neutral findingspec.Finding in the security domain. The finding's Severity is the inherent severity; residual detail is preserved on the security type.

type VulnerabilityDetail 

type VulnerabilityDetail struct {
	CVEs             []string             `json:"cves,omitempty"`
	CWEs             []string             `json:"cwes,omitempty"`
	CVSS             *CVSS                `json:"cvss,omitempty"`
	Exploitability   Exploitability       `json:"exploitability,omitempty"`
	Reachable        *bool                `json:"reachable,omitempty"`
	Reachability     *Reachability        `json:"reachability,omitempty"`
	Package          *Package             `json:"package,omitempty"`
	Fix              *Fix                 `json:"fix,omitempty"`
	Artifact         *Artifact            `json:"artifact,omitempty"`
	ResidualSeverity findingspec.Severity `json:"residualSeverity,omitempty"`
	Controls         []Control            `json:"controls,omitempty"`
	Exception        *Exception           `json:"exception,omitempty"`
	Component        string               `json:"component,omitempty"`
}

VulnerabilityDetail is the per-type Detail payload for a vulnerability finding (findingspec.Finding.Type of sca/sast/container/runtime/…). It holds the vulnerability-specific fields not already promoted to the canonical header.

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.