github.com/google/osv-scalibr@v0.4.1/inventory/finding.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 inventory
    16  
    17  import (
    18  	"github.com/google/osv-scalibr/extractor"
    19  	"github.com/google/osv-scalibr/inventory/vex"
    20  
    21  	osvpb "github.com/ossf/osv-schema/bindings/go/osvschema"
    22  )
    23  
    24  // LINT.IfChange
    25  
    26  // Finding is a struct returned by Detectors that contains all security finding
    27  // related inventory types.
    28  type Finding struct {
    29  	PackageVulns    []*PackageVuln
    30  	GenericFindings []*GenericFinding
    31  }
    32  
    33  // LINT.ThenChange(/detector/detectorrunner/detectorrunner.go)
    34  
    35  // LINT.IfChange
    36  
    37  // PackageVuln is a vulnerability (e.g. a CVE) related to a package.
    38  // It follows the OSV Schema format: https://ossf.github.io/osv-schema
    39  type PackageVuln struct {
    40  	// The OSV vulnerability information.
    41  	Vulnerability *osvpb.Vulnerability
    42  
    43  	// The extracted package associated with this vuln.
    44  	Package *extractor.Package
    45  	// The plugins (e.g. Detectors, Enrichers) that found this vuln.
    46  	Plugins []string
    47  	// Signals that indicate this finding is not exploitable.
    48  	ExploitabilitySignals []*vex.FindingExploitabilitySignal
    49  }
    50  
    51  // GenericFinding is used to describe generic security findings not associated with any
    52  // specific package, e.g. weak credentials.
    53  // Note: If you need to store more structured data related to a vulnerability, consider
    54  // introducing a new vulnerability type instead of using GenericFinding.
    55  type GenericFinding struct {
    56  	// Info specific to the vuln. Should always be the same for the same type of vuln.
    57  	Adv *GenericFindingAdvisory
    58  	// Instance-specific info such as location of the vulnerable files.
    59  	Target *GenericFindingTargetDetails
    60  	// The plugins (e.g. Detectors, Enrichers) that found this vuln.
    61  	Plugins []string
    62  	// Signals that indicate this finding is not exploitable.
    63  	ExploitabilitySignals []*vex.FindingExploitabilitySignal
    64  }
    65  
    66  // GenericFindingAdvisory describes a security finding and how to remediate it. It should not
    67  // contain any information specific to the target (e.g. which files were found vulnerable).
    68  type GenericFindingAdvisory struct {
    69  	// A unique ID for the finding.
    70  	ID *AdvisoryID
    71  	// Title, short description and recommendation steps for the finding. Users should be able to rely
    72  	// on these fields to understand the vulnerability and remediate it.
    73  	// Title of the finding, e.g. "CVE-2024-1234 - RCE Vulnerability on Foo".
    74  	Title string
    75  	// Description of the finding, e.g. "Foo prior to version 1.2.3 is affected by a Remote Code
    76  	// Execution vulnerability.".
    77  	Description string
    78  	// Recommendation for how to remediate the finding, e.g. "Upgrade Foo to version 1.2.4 or
    79  	// higher.".
    80  	Recommendation string
    81  	Sev            SeverityEnum
    82  }
    83  
    84  // AdvisoryID is a unique identifier per advisory.
    85  type AdvisoryID struct {
    86  	Publisher string // e.g. "CVE".
    87  	Reference string // e.g. "CVE-2023-1234".
    88  }
    89  
    90  // SeverityEnum is an enum-based representation of the finding's severity.
    91  type SeverityEnum int
    92  
    93  // SeverityEnum values.
    94  const (
    95  	SeverityUnspecified SeverityEnum = iota
    96  	SeverityMinimal
    97  	SeverityLow
    98  	SeverityMedium
    99  	SeverityHigh
   100  	SeverityCritical
   101  )
   102  
   103  // GenericFindingTargetDetails contains instance-specific details about
   104  // the generic security finding.
   105  type GenericFindingTargetDetails struct {
   106  	// Free-text info.
   107  	Extra string
   108  }
   109  
   110  // LINT.ThenChange(/binary/proto/scan_result.proto)
   111  
   112  // PackageToAffected creates an osvpb.Affected struct from the given
   113  // Package, fixed ecosystem version, and severity.
   114  func PackageToAffected(pkg *extractor.Package, fixed string, severity *osvpb.Severity) []*osvpb.Affected {
   115  	return []*osvpb.Affected{{
   116  		Package: &osvpb.Package{
   117  			Ecosystem: pkg.Ecosystem().String(),
   118  			Name:      pkg.Name,
   119  		},
   120  		Severity: []*osvpb.Severity{severity},
   121  		Ranges: []*osvpb.Range{{
   122  			Type:   osvpb.Range_ECOSYSTEM,
   123  			Events: []*osvpb.Event{{Fixed: fixed}},
   124  		}},
   125  	}}
   126  }