github.com/google/osv-scalibr@v0.4.1/inventory/vex/vex.go (about)

     1  // Copyright 2025 Google LLC
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  // Package vex stores data structures used to represent exploitability signals in SCALIBR scan results.
    16  package vex
    17  
    18  import "slices"
    19  
    20  // PackageExploitabilitySignal is used to indicate that specific vulnerabilities
    21  // are not applicable to a given package.
    22  type PackageExploitabilitySignal struct {
    23  	// The name of the plugin (e.g. Annotator) that added this signal.
    24  	Plugin string
    25  	// Reason for exclusion.
    26  	Justification Justification
    27  	// Advisory Identifier (CVE, GHSA, ...) and aliases of the vulns that are not
    28  	// applicable to this package.
    29  	VulnIdentifiers []string
    30  	// Indicates that all vulnerabilities associated with the package are irrelevant.
    31  	// VulnIdentifiers should be empty when this is set to true.
    32  	MatchesAllVulns bool
    33  }
    34  
    35  // FindingExploitabilitySignal is used to indicate that a finding is not exploitable.
    36  type FindingExploitabilitySignal struct {
    37  	// The name of the plugin (e.g. Annotator) that added this signal.
    38  	Plugin string
    39  	// Reason for exclusion.
    40  	Justification Justification
    41  }
    42  
    43  // Justification enumerates various vuln exclusion reasons.
    44  // It mirrors the format from the official VEX documentation
    45  // (https://www.cisa.gov/sites/default/files/publications/VEX_Status_Justification_Jun22.pdf)
    46  type Justification int64
    47  
    48  const (
    49  	// Unspecified indicated the exclusion reason has not been specified.
    50  	Unspecified Justification = iota
    51  	// ComponentNotPresent indicates the vulnerable component is not used in the
    52  	// affected artifact.
    53  	ComponentNotPresent
    54  	// VulnerableCodeNotPresent indicates the component is used but vulnerable
    55  	// code was removed or not included.
    56  	VulnerableCodeNotPresent
    57  	// VulnerableCodeNotInExecutePath indicates the vulnerable code is included
    58  	// but is not executed.
    59  	VulnerableCodeNotInExecutePath
    60  	// VulnerableCodeCannotBeControlledByAdversary indicates the vulnerable code
    61  	// is executed but can't be exploited due to program logic.
    62  	VulnerableCodeCannotBeControlledByAdversary
    63  	// InlineMitigationAlreadyExists indicates the vulnerable code can be
    64  	// executed but additional mitigations prevent exploitation.
    65  	InlineMitigationAlreadyExists
    66  )
    67  
    68  // FindingVEXFromPackageVEX converts package VEXes to finding VEXes if they're
    69  // applicable to a finding with the given ID.
    70  func FindingVEXFromPackageVEX(vulnID string, pkgVEXes []*PackageExploitabilitySignal) []*FindingExploitabilitySignal {
    71  	var result []*FindingExploitabilitySignal
    72  	for _, pkgVEX := range pkgVEXes {
    73  		if pkgVEX.MatchesAllVulns || slices.Contains(pkgVEX.VulnIdentifiers, vulnID) {
    74  			result = append(result, &FindingExploitabilitySignal{
    75  				Plugin:        pkgVEX.Plugin,
    76  				Justification: pkgVEX.Justification,
    77  			})
    78  		}
    79  	}
    80  	return result
    81  }