// Copyright 2018 The Grafeas Authors. All rights reserved.
//
// 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 grafeas.v1beta1.vulnerability;

import "google/protobuf/timestamp.proto";
import "google/devtools/containeranalysis/v1beta1/common/common.proto";
import "google/devtools/containeranalysis/v1beta1/cvss/cvss.proto";
import "google/devtools/containeranalysis/v1beta1/package/package.proto";

option go_package = "cloud.google.com/go/containeranalysis/apiv1beta1/containeranalysispb;containeranalysispb";
option java_multiple_files = true;
option java_package = "io.grafeas.v1beta1.vulnerability";
option objc_class_prefix = "GRA";

// Note provider-assigned severity/impact ranking.
enum Severity {
  // Unknown.
  SEVERITY_UNSPECIFIED = 0;
  // Minimal severity.
  MINIMAL = 1;
  // Low severity.
  LOW = 2;
  // Medium severity.
  MEDIUM = 3;
  // High severity.
  HIGH = 4;
  // Critical severity.
  CRITICAL = 5;
}

// Vulnerability provides metadata about a security vulnerability in a Note.
message Vulnerability {
  // The CVSS score for this vulnerability.
  float cvss_score = 1;

  // Note provider assigned impact of the vulnerability.
  Severity severity = 2;

  // All information about the package to specifically identify this
  // vulnerability. One entry per (version range and cpe_uri) the package
  // vulnerability has manifested in.
  repeated Detail details = 3;

  // Identifies all appearances of this vulnerability in the package for a
  // specific distro/location. For example: glibc in
  // cpe:/o:debian:debian_linux:8 for versions 2.1 - 2.2
  message Detail {
    // Required. The CPE URI in
    // [cpe format](https://cpe.mitre.org/specification/) in which the
    // vulnerability manifests. Examples include distro or storage location for
    // vulnerable jar.
    string cpe_uri = 1;

    // Required. The name of the package where the vulnerability was found.
    string package = 2;

    // The min version of the package in which the vulnerability exists.
    grafeas.v1beta1.package.Version min_affected_version = 3;

    // The max version of the package in which the vulnerability exists.
    grafeas.v1beta1.package.Version max_affected_version = 4;

    // The severity (eg: distro assigned severity) for this vulnerability.
    string severity_name = 5;

    // A vendor-specific description of this note.
    string description = 6;

    // The fix for this specific package version.
    VulnerabilityLocation fixed_location = 7;

    // The type of package; whether native or non native(ruby gems, node.js
    // packages etc).
    string package_type = 8;

    // Whether this detail is obsolete. Occurrences are expected not to point to
    // obsolete details.
    bool is_obsolete = 9;

    // The time this information was last changed at the source. This is an
    // upstream timestamp from the underlying information source - e.g. Ubuntu
    // security tracker.
    google.protobuf.Timestamp source_update_time = 10;
  }

  // The full description of the CVSSv3.
  CVSSv3 cvss_v3 = 4;

  // Windows details get their own format because the information format and
  // model don't match a normal detail. Specifically Windows updates are done as
  // patches, thus Windows vulnerabilities really are a missing package, rather
  // than a package being at an incorrect version.
  repeated WindowsDetail windows_details = 5;

  message WindowsDetail {
    // Required. The CPE URI in
    // [cpe format](https://cpe.mitre.org/specification/) in which the
    // vulnerability manifests. Examples include distro or storage location for
    // vulnerable jar.
    string cpe_uri = 1;

    // Required. The name of the vulnerability.
    string name = 2;

    // The description of the vulnerability.
    string description = 3;

    // Required. The names of the KBs which have hotfixes to mitigate this
    // vulnerability. Note that there may be multiple hotfixes (and thus
    // multiple KBs) that mitigate a given vulnerability. Currently any listed
    // kb's presence is considered a fix.
    repeated KnowledgeBase fixing_kbs = 4;

    message KnowledgeBase {
      // The KB name (generally of the form KB[0-9]+ i.e. KB123456).
      string name = 1;
      // A link to the KB in the Windows update catalog -
      // https://www.catalog.update.microsoft.com/
      string url = 2;
    }
  }

  // The time this information was last changed at the source. This is an
  // upstream timestamp from the underlying information source - e.g. Ubuntu
  // security tracker.
  google.protobuf.Timestamp source_update_time = 6;

  // Next free ID is 7.
}

// Details of a vulnerability Occurrence.
message Details {
  // The type of package; whether native or non native(ruby gems, node.js
  // packages etc)
  string type = 1;

  // Output only. The note provider assigned Severity of the vulnerability.
  Severity severity = 2;

  // Output only. The CVSS score of this vulnerability. CVSS score is on a
  // scale of 0-10 where 0 indicates low severity and 10 indicates high
  // severity.
  float cvss_score = 3;

  // Required. The set of affected locations and their fixes (if available)
  // within the associated resource.
  repeated PackageIssue package_issue = 4;

  // Output only. A one sentence description of this vulnerability.
  string short_description = 5;

  // Output only. A detailed description of this vulnerability.
  string long_description = 6;

  // Output only. URLs related to this vulnerability.
  repeated grafeas.v1beta1.RelatedUrl related_urls = 7;

  // The distro assigned severity for this vulnerability when it is
  // available, and note provider assigned severity when distro has not yet
  // assigned a severity for this vulnerability.
  Severity effective_severity = 8;
}

// This message wraps a location affected by a vulnerability and its
// associated fix (if one is available).
message PackageIssue {
  // Required. The location of the vulnerability.
  VulnerabilityLocation affected_location = 1;

  // The location of the available fix for vulnerability.
  VulnerabilityLocation fixed_location = 2;

  // Deprecated, use Details.effective_severity instead
  // The severity (e.g., distro assigned severity) for this vulnerability.
  string severity_name = 3;
}

// The location of the vulnerability.
message VulnerabilityLocation {
  // Required. The CPE URI in [cpe format](https://cpe.mitre.org/specification/)
  // format. Examples include distro or storage location for vulnerable jar.
  string cpe_uri = 1;

  // Required. The package being described.
  string package = 2;

  // Required. The version of the package being described.
  grafeas.v1beta1.package.Version version = 3;
}