// 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.package;

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

// Instruction set architectures supported by various package managers.
enum Architecture {
  // Unknown architecture.
  ARCHITECTURE_UNSPECIFIED = 0;
  // X86 architecture.
  X86 = 1;
  // X64 architecture.
  X64 = 2;
}

// This represents a particular channel of distribution for a given package.
// E.g., Debian's jessie-backports dpkg mirror.
message Distribution {
  // Required. The cpe_uri in [CPE format](https://cpe.mitre.org/specification/)
  // denoting the package manager version distributing a package.
  string cpe_uri = 1;

  // The CPU architecture for which packages in this distribution channel were
  // built.
  Architecture architecture = 2;

  // The latest available version of this package in this distribution channel.
  Version latest_version = 3;

  // A freeform string denoting the maintainer of this package.
  string maintainer = 4;

  // The distribution channel-specific homepage for this package.
  string url = 5;

  // The distribution channel-specific description of this package.
  string description = 6;
}

// An occurrence of a particular package installation found within a system's
// filesystem. E.g., glibc was found in `/var/lib/dpkg/status`.
message Location {
  // Required. The CPE URI in [CPE format](https://cpe.mitre.org/specification/)
  // denoting the package manager version distributing a package.
  string cpe_uri = 1;

  // The version installed at this location.
  Version version = 2;

  // The path from which we gathered that this package/version is installed.
  string path = 3;
}

// This represents a particular package that is distributed over various
// channels. E.g., glibc (aka libc6) is distributed by many, at various
// versions.
message Package {
  // Required. Immutable. The name of the package.
  string name = 1;

  // The various channels by which a package is distributed.
  repeated Distribution distribution = 10;
}

// Details of a package occurrence.
message Details {
  // Required. Where the package was installed.
  Installation installation = 1;
}

// This represents how a particular software package may be installed on a
// system.
message Installation {
  // Output only. The name of the installed package.
  string name = 1;

  // Required. All of the places within the filesystem versions of this package
  // have been found.
  repeated Location location = 2;
}

// Version contains structured information about the version of a package.
message Version {
  // Used to correct mistakes in the version numbering scheme.
  int32 epoch = 1;

  // Required only when version kind is NORMAL. The main part of the version
  // name.
  string name = 2;

  // The iteration of the package build from the above version.
  string revision = 3;

  // Whether this is an ordinary package version or a sentinel MIN/MAX version.
  enum VersionKind {
    // Unknown.
    VERSION_KIND_UNSPECIFIED = 0;
    // A standard package version.
    NORMAL = 1;
    // A special version representing negative infinity.
    MINIMUM = 2;
    // A special version representing positive infinity.
    MAXIMUM = 3;
  };

  // Required. Distinguishes between sentinel MIN/MAX versions and normal
  // versions.
  VersionKind kind = 4;
}