scan_result.proto

/*
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";

package scalibr;

import "google/protobuf/timestamp.proto";

option go_package = "github.com/google/scalibr/binary/proto/scan_result_go_proto";
option java_multiple_files = true;

// Proto file describing the SCALIBR scan results. Whenever this proto is
// modified make sure to regenerate the go_proto file by running
// `make protos`

// The software inventory and security findings that a scan run found.
message ScanResult {
  string version = 1;
  google.protobuf.Timestamp start_time = 2;
  google.protobuf.Timestamp end_time = 3;
  // Status of the overall scan.
  ScanStatus status = 4;
  // Status and versions of the inventory+vuln plugins that ran.
  repeated PluginStatus plugin_status = 5;
  repeated Inventory inventories = 6;
  repeated Finding findings = 7;
}

message ScanStatus {
  ScanStatusEnum status = 1;
  string failure_reason = 2;
  enum ScanStatusEnum {
    UNSPECIFIED = 0;
    SUCCEEDED = 1;
    PARTIALLY_SUCCEEDED = 2;
    FAILED = 3;
  }
}

message PluginStatus {
  string name = 1;
  int32 version = 2;
  ScanStatus status = 3;
}

// A software package or library found by an extractor.
// PURL or CPE needs to be set, maybe both.
message Inventory {
  reserved 3, 4;
  // Human-readable name of the software, to be used for things like logging.
  // For vuln matching, use the name from metadata.
  string name = 11;
  // Version of the package.
  string version = 12;
  // Source code level package identifiers.
  SourceCodeIdentifier source_code = 26;
  // Package URL of the software.
  Purl purl = 1;
  // Ecosystem - For software packages this corresponds to an OSV ecosystem
  // value, e.g. PyPI.
  string ecosystem = 27;
  // Paths or source of files related to the package.
  repeated string locations = 2;
  // The name of the Extractor that found this software. Set by the
  // core library.
  string extractor = 10;
  // The additional data found in the package.
  oneof metadata {
    PythonPackageMetadata python_metadata = 5;
    JavascriptPackageJSONMetadata javascript_metadata = 6;
    APKPackageMetadata apk_metadata = 7;
    DPKGPackageMetadata dpkg_metadata = 8;
    RPMPackageMetadata rpm_metadata = 9;
    COSPackageMetadata cos_metadata = 13;
    SPDXPackageMetadata spdx_metadata = 14;
    JavaArchiveMetadata java_archive_metadata = 15;
    JavaLockfileMetadata java_lockfile_metadata = 31;
    PACMANPackageMetadata pacman_metadata = 36;
    OSVPackageMetadata osv_metadata = 16;
    PythonRequirementsMetadata python_requirements_metadata = 21;
    ContainerdContainerMetadata containerd_container_metadata = 22;
    SNAPPackageMetadata snap_metadata = 23;
    FlatpakPackageMetadata flatpak_metadata = 24;
    MacAppsMetadata mac_apps_metadata = 34;
    ContainerdRuntimeContainerMetadata containerd_runtime_container_metadata =
        25;
    CDXPackageMetadata cdx_metadata = 30;
    WindowsOSVersion windows_os_version_metadata = 33;
  }

  repeated AnnotationEnum annotations = 28;
  enum AnnotationEnum {
    UNSPECIFIED = 0;
    TRANSITIONAL = 1;
    INSIDE_OS_PACKAGE = 2;
    INSIDE_CACHE_DIR = 3;
  }

  // Details about the layer a package was found in. This should be set only for
  // container image scanning.
  LayerDetails layer_details = 35;
}

// Additional identifiers for source code software packages (e.g. NPM).
message SourceCodeIdentifier {
  string repo = 1;
  string commit = 2;
}

// Details about the layer a package was found in.
message LayerDetails {
  int32 index = 1;
  string diff_id = 2;
  string command = 3;
  bool in_base_image = 4;
}

// Package URL, see https://github.com/package-url/purl-spec
message Purl {
  // String representation.
  string purl = 1;
  // Package type, e.g. "maven, npm, pypi".
  string type = 2;
  // Package name.
  string name = 3;
  // Package version.
  string version = 4;
  // Name prefix such as a Maven groupid, or Docker image owner.
  string namespace = 5;
  // Extra qualifying data for a package such as an OS, architecture, etc.
  repeated Qualifier qualifiers = 6;
  // Extra subpath within a package, relative to the package root.
  string subpath = 7;
}

message Qualifier {
  string key = 1;
  string value = 2;
}

// A security finding found by a detector. It could describe things like a CVE
// or a CIS non-compliance.
message Finding {
  // Info specific to the finding. Should always be the same for the same type
  // of finding.
  Advisory adv = 1;
  // Instance-specific info such as location of the vulnerable files.
  TargetDetails target = 2;
  // Additional free-text info.
  string extra = 3;
  // The name of the Detectors that found this finding. Set by the core library.
  repeated string detectors = 4;
}

message Advisory {
  // A unique ID for the finding.
  AdvisoryId id = 1;
  TypeEnum type = 2;
  string title = 3;
  string description = 4;
  // Remediation instructions, e.g. "update to latest version".
  string recommendation = 5;
  Severity sev = 6;
  enum TypeEnum {
    UNKNOWN = 0;
    VULNERABILITY = 1;
    CIS_FINDING = 2;
  }
}

// A unique identifier per advisory.
message AdvisoryId {
  string publisher = 1;  // e.g. "CVE".
  string reference = 2;  // e.g. "CVE-2023-1234".
}

message Severity {
  // Required severity enum. Can be used for e.g. prioritizing filed bugs.
  SeverityEnum severity = 1;
  // Optional CVSS scores, only set for vulns with CVEs.
  CVSS cvss_v2 = 2;
  CVSS cvss_v3 = 3;
  enum SeverityEnum {
    UNSPECIFIED = 0;
    MINIMAL = 1;
    LOW = 2;
    MEDIUM = 3;
    HIGH = 4;
    CRITICAL = 5;
  }
}

message CVSS {
  float base_score = 1;
  float temporal_score = 2;
  float environmental_score = 3;
}

message TargetDetails {
  // The software affected by the finding.
  Inventory inventory = 1;
  // Location of vulnerable files not related to the inventory,
  // e.g. config files with misconfigurations.
  repeated string location = 3;
}

// The additional data found in python packages.
message PythonPackageMetadata {
  string author = 1;
  string author_email = 2;
}

// The additional data found in npm packages.
message JavascriptPackageJSONMetadata {
  string author = 1;
  repeated string maintainers = 2;
  repeated string contributors = 3;
}

// The additional data found in APK packages.
message APKPackageMetadata {
  string package_name = 1;
  string origin_name = 2;
  string os_id = 3;
  string os_version_id = 4;
  string maintainer = 5;
  string architecture = 6;
  string license = 7;
}

// The additional data found in DPKG packages.
// Next ID: 11
message DPKGPackageMetadata {
  string package_name = 1;
  string source_name = 2;
  string source_version = 3;
  string package_version = 4;
  string os_id = 5;
  string os_version_codename = 6;
  string os_version_id = 7;
  string maintainer = 8;
  string architecture = 9;
  string status = 10;
}

// The additional data found in RPM packages.
message RPMPackageMetadata {
  string package_name = 1;
  string source_rpm = 2;
  int32 epoch = 3;
  string os_id = 4;
  string os_version_id = 5;
  string os_build_id = 6;
  string os_name = 7;
  string vendor = 8;
  string architecture = 9;
  string license = 10;
}

// The additional data found in COS packages.
message COSPackageMetadata {
  string name = 1;
  string version = 2;
  string category = 3;
  string os_version = 4;
  string os_version_id = 5;
}

// The additional data found in PACMAN packages.
message PACMANPackageMetadata {
  string package_name = 1;
  string package_version = 2;
  string os_id = 3;
  string os_version_id = 4;
  string package_description = 5;
  string package_dependencies = 6;
}

// The additional data found in SNAP packages.
message SNAPPackageMetadata {
  string name = 1;
  string version = 2;
  string grade = 3;
  string type = 4;
  repeated string architectures = 5;
  string os_id = 6;
  string os_version_codename = 7;
  string os_version_id = 8;
}

// The additional data found in Flatpak packages.
message FlatpakPackageMetadata {
  string package_name = 1;
  string package_id = 2;
  string package_version = 3;
  string release_date = 4;
  string os_name = 5;
  string os_id = 6;
  string os_version_id = 7;
  string os_build_id = 8;
  string developer = 9;
}

// The additional data found in Mac Applications.
message MacAppsMetadata {
  string bundle_display_name = 1;
  string bundle_identifier = 2;
  string bundle_short_version_string = 3;
  string bundle_executable = 4;
  string bundle_name = 5;
  string bundle_package_type = 6;
  string bundle_signature = 7;
  string bundle_version = 8;
  string product_id = 9;
  string update_url = 10;
}

// The additional data for packages extracted from SPDX files.
message SPDXPackageMetadata {
  Purl purl = 1;
  repeated string cpes = 2;
}

// The additional data for packages extracted from CDX files.
message CDXPackageMetadata {
  Purl purl = 1;
  repeated string cpes = 2;
}

// The additional data found in Java JAR packages.
message JavaArchiveMetadata {
  string artifact_id = 2;
  string group_id = 3;
  string sha1 = 4;
}

// The additional data found in Java lockfiles.
message JavaLockfileMetadata {
  string artifact_id = 1;
  string group_id = 2;
  repeated string dep_group_vals = 3;
}

// The additional data for packages extracted by an OSV extractor wrapper.
message OSVPackageMetadata {
  string purl_type = 1;
  string commit = 2;
  string ecosystem = 3;
  string compare_as = 4;
}

message PythonRequirementsMetadata {
  repeated string hash_checking_mode_values = 1;
  string version_comparator = 2;
}

message ContainerdContainerMetadata {
  string namespace_name = 1;
  string image_name = 2;
  string image_digest = 3;
  string runtime = 4;
  int32 pid = 5;
  string snapshotter = 6;
  string snapshot_key = 7;
  string lower_dir = 8;
  string upper_dir = 9;
  string work_dir = 10;
  string id = 11;
}

message ContainerdRuntimeContainerMetadata {
  string namespace_name = 1;
  string image_name = 2;
  string image_digest = 3;
  string runtime = 4;
  string id = 5;
  int32 pid = 6;
  string rootfs_path = 7;
}

message WindowsOSVersion {
  string product = 1;
  string full_version = 2;
}