tools/protos/metadata_file.proto

// Copyright (C) 2023 The Android Open Source Project
//
// 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 = "proto2";

package metadata_file;

// Proto definition of METADATA files of packages in AOSP codebase.
message Metadata {
  // Name of the package.
  optional string name = 1;

  // A short description (a few lines) of the package.
  // Example: "Handles location lookups, throttling, batching, etc."
  optional string description = 2;

  // Specifies additional data about third-party packages.
  optional ThirdParty third_party = 3;
}

message ThirdParty {
  // URL(s) associated with the package.
  //
  // At a minimum, all packages must specify a URL which identifies where it
  // came from, containing a type of: ARCHIVE, GIT or OTHER. Typically,
  // a package should contain only a single URL from these types.  Occasionally,
  // a package may be broken across multiple archive files for whatever reason,
  // in which case having multiple ARCHIVE URLs is okay.  However, this should
  // not be used to combine different logical packages that are versioned and
  // possibly licensed differently.
  repeated URL url = 1;

  // The package version.  In order of preference, this should contain:
  //  - If the package comes from Git or another source control system,
  //    a specific tag or revision in source control, such as "r123" or
  //    "58e27d2".  This MUST NOT be a mutable ref such as a branch name.
  //  - a released package version such as "1.0", "2.3-beta", etc.
  //  - the date the package was retrieved, formatted as "As of YYYY-MM-DD".
  optional string version = 2;

  // The date of the change in which the package was last upgraded from
  // upstream.
  // This should only identify package upgrades from upstream, not local
  // modifications. This may identify the date of either the original or
  // merged change.
  //
  // Note: this is NOT the date that this version of the package was released
  // externally.
  optional Date last_upgrade_date = 3;

  // License type that identifies how the package may be used.
  optional LicenseType license_type = 4;

  // An additional note explaining the licensing of this package.  This is most
  // commonly used with commercial license.
  optional string license_note = 5;

  // Description of local changes that have been made to the package.  This does
  // not need to (and in most cases should not) attempt to include an exhaustive
  // list of all changes, but may instead direct readers to review the local
  // commit history, a collection of patch files, a separate README.md (or
  // similar) document, etc.
  // Note: Use of this field to store IDs of advisories fixed with a backported
  // patch is deprecated, use "security.mitigated_security_patch" instead.
  optional string local_modifications = 6;

  // Security related metadata including risk category and any special
  // instructions for using the package, as determined by an ISE-TPS review.
  optional Security security = 7;

  // The type of directory this metadata represents.
  optional DirectoryType type = 8 [default = PACKAGE];

  // The homepage for the package. This will eventually replace
  // `url { type: HOMEPAGE }`
  optional string homepage = 9;

  // SBOM information of the package. It is mandatory for prebuilt packages.
  oneof sbom {
    // Reference to external SBOM document provided as URL.
    SBOMRef sbom_ref = 10;
  }

  // Identifiers for the package.
  repeated Identifier identifier = 11;
}

// URL associated with a third-party package.
message URL {
  enum Type {
    // The homepage for the package. For example, "https://bazel.io/". This URL
    // is optional, but encouraged to help disambiguate similarly named packages
    // or to get more information about the package. This is especially helpful
    // when no other URLs provide human readable resources (such as git:// or
    // sso:// URLs).
    HOMEPAGE = 1;

    // The URL of the archive containing the source code for the package, for
    // example a zip or tgz file.
    ARCHIVE = 2;

    // The URL of the upstream git repository this package is retrieved from.
    // For example:
    //  - https://github.com/git/git.git
    //  - git://git.kernel.org/pub/scm/git/git.git
    //
    // Use of a git URL requires that the package "version" value must specify a
    // specific git tag or revision.
    GIT = 3;

    // The URL of the upstream SVN repository this package is retrieved from.
    // For example:
    //  - http://llvm.org/svn/llvm-project/llvm/
    //
    // Use of an SVN URL requires that the package "version" value must specify
    // a specific SVN tag or revision.
    SVN = 4;

    // The URL of the upstream mercurial repository this package is retrieved
    // from. For example:
    //   - https://mercurial-scm.org/repo/evolve
    //
    // Use of a mercurial URL requires that the package "version" value must
    // specify a specific tag or revision.
    HG = 5;

    // The URL of the upstream darcs repository this package is retrieved
    // from. For example:
    //   - https://hub.darcs.net/hu.dwim/hu.dwim.util
    //
    // Use of a DARCS URL requires that the package "version" value must
    // specify a specific tag or revision.
    DARCS = 6;

    PIPER = 7;

    // A URL that does not fit any other type. This may also indicate that the
    // source code was received via email or some other out-of-band way. This is
    // most commonly used with commercial software received directly from the
    // vendor. In the case of email, the URL value can be used to provide
    // additional information about how it was received.
    OTHER = 8;

    // The URL identifying where the local copy of the package source code can
    // be found.
    //
    // Typically, the metadata files describing a package reside in the same
    // directory as the source code for the package. In a few rare cases where
    // they are separate, the LOCAL_SOURCE URL identifies where to find the
    // source code. This only describes where to find the local copy of the
    // source; there should always be an additional URL describing where the
    // package was retrieved from.
    //
    // Examples:
    //  - https://android.googlesource.com/platform/external/apache-http/
    LOCAL_SOURCE = 9;
  }

  // The type of resource this URL identifies.
  optional Type type = 1;

  // The actual URL value.  URLs should be absolute and start with 'http://' or
  // 'https://' (or occasionally 'git://' or 'ftp://' where appropriate).
  optional string value = 2;
}

// License type that identifies how the packages may be used.
enum LicenseType {
  BY_EXCEPTION_ONLY = 1;
  NOTICE = 2;
  PERMISSIVE = 3;
  RECIPROCAL = 4;
  RESTRICTED_IF_STATICALLY_LINKED = 5;
  RESTRICTED = 6;
  UNENCUMBERED = 7;
}

// Identifies security related metadata including risk category and any special
// instructions for using the package.
message Security {
  // Security risk category for a package, as determined by an ISE-TPS review.
  enum Category {
    CATEGORY_UNSPECIFIED = 0;

    // Package should only be used in a sandboxed environment.
    // Package should have restricted visibility.
    SANDBOXED_ONLY = 1;

    // Package should not be used to process user content. It is considered
    // safe to use to process trusted data only. Package should have restricted
    // visibility.
    TRUSTED_DATA_ONLY = 2;

    // Package is considered safe to use.
    REVIEWED_AND_SECURE = 3;
  }

  // Identifies the security risk category for the package.  This will be
  // provided by the ISE-TPS team as the result of a security review of the
  // package.
  optional Category category = 1;

  // An additional security note for the package.
  optional string note = 2;

  // Text tag to categorize the package. It's currently used by security to:
  // - to disable OSV (https://osv.dev)
  // support via the `OSV:disable` tag
  // - to attach CPE to their corresponding packages, for vulnerability
  // monitoring:
  //
  // Please do document your usecase here should you want to add one.
  repeated string tag = 3;

  // ID of advisories fixed with a mitigated patch, for example CVE-2018-1111.
  repeated string mitigated_security_patch = 4;
}

enum DirectoryType {
  UNDEFINED = 0;

  // This directory represents a package.
  PACKAGE = 1;

  // This directory is designed to organize multiple third-party PACKAGE
  // directories.
  GROUP = 2;

  // This directory contains several PACKAGE directories representing
  // different versions of the same third-party project.
  VERSIONS = 3;
}

// Represents a whole or partial calendar date, such as a birthday. The time of
// day and time zone are either specified elsewhere or are insignificant. The
// date is relative to the Gregorian Calendar. This can represent one of the
// following:
//
// * A full date, with non-zero year, month, and day values.
// * A month and day, with a zero year (for example, an anniversary).
// * A year on its own, with a zero month and a zero day.
// * A year and month, with a zero day (for example, a credit card expiration
//   date).
message Date {
  // Year of the date. Must be from 1 to 9999, or 0 to specify a date without
  // a year.
  optional int32 year = 1;
  // Month of a year. Must be from 1 to 12, or 0 to specify a year without a
  // month and day.
  optional int32 month = 2;
  // Day of a month. Must be from 1 to 31 and valid for the year and month, or 0
  // to specify a year by itself or a year and month where the day isn't
  // significant.
  optional int32 day = 3;
}

// Reference to external SBOM document and element corresponding to the package.
// See https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#66-external-document-references-field
message SBOMRef {
  // The URL that points to the SBOM document of the upstream package of this
  // third_party package.
  optional string url = 1;
  // Checksum of the SBOM document the url field points to.
  // Format: e.g. SHA1:<checksum>, or any algorithm defined in
  // https://spdx.github.io/spdx-spec/v2.3/file-information/#8.4
  optional string checksum = 2;
  // SPDXID of the upstream package/file defined in the SBOM document the url field points to.
  // Format: SPDXRef-[a-zA-Z0-9.-]+, see
  // https://spdx.github.io/spdx-spec/v2.3/package-information/#72-package-spdx-identifier-field or
  // https://spdx.github.io/spdx-spec/v2.3/file-information/#82-file-spdx-identifier-field
  optional string element_id = 3;
}

// Identifier for a third-party package.
// See go/tp-metadata-id.
message Identifier {
  // The type of the identifier. Either an "ecosystem" value from
  // https://ossf.github.io/osv-schema/#affectedpackage-field such as "Go",
  // "npm" or "PyPI". The "value" and "version" fields follow the same rules as
  // defined in the OSV spec.

  // Or one of:
  //  - "Git": The "value" field is the URL of the upstream git repository this
  //  package is retrieved from.
  //  For example:
  //   - https://github.com/git/git
  //   - git://git.kernel.org/pub/scm/git/git
  //
  //  Use of a git URL requires that the package "version" value must specify a
  //  specific git tag or revision. This must not be a branch name.
  //
  //  - "SVN": The "value" field is the URL of the upstream SVN repository this
  //  package is retrieved from.
  //  For example:
  //   - http://llvm.org/svn/llvm-project/llvm/
  //
  //  Use of an SVN URL requires that the package "version" value must specify
  //  a specific SVN tag or revision. This must not be a branch name.
  //
  //  - "Hg": The "value" field is the URL of the upstream mercurial repository
  //  this package is retrieved from.
  //  For example:
  //   - https://mercurial-scm.org/repo/evolve
  //
  //  Use of a mercurial URL requires that the package "version" value must
  //  specify a specific tag or revision. This must not be a branch name.
  //
  //  - "Darcs": the "value" field is the URL of the upstream darcs repository
  //  this package is retrieved from.
  //  For example:
  //   - https://hub.darcs.net/hu.dwim/hu.dwim.util
  //
  //  Use of a Darcs URL requires that the package "version" value must
  //  specify a specific tag or revision. This must not be a branch name.
  //
  //  - "Piper": The "value" field is the URL of the upstream piper location.
  //  This is primarily used when a package is being migrated into third_party
  //  from elsewhere in Piper, or when a package is being newly developed in
  //  third_party.
  //
  //  - "VCS": This is a generic fallback for an unlisted VCS system. The
  // "value" field is the URL of the repository for this VCS.
  //
  //  - "Archive": The "value" field is the URL of the archive containing the
  //  source code for the package, for example a zip or tgz file.
  //
  //  - "PrebuiltByAlphabet": This type should be used for archives of primarily
  //  Google-owned source code (may contain non-Google-owned dependencies),
  //  which has been built using production Google infrastructure, and copied
  //  into Android. The "value" field is the URL of the prebuilt artifact or
  //  the relative path of the artifact to the root of a package.
  //  Example:
  //    identifier {
  //      type: "PrebuiltByAlphabet",
  //      version: "1",
  //      value: "v1/arm84_hdpi.apk",
  //    }
  //    identifier {
  //      type: "PrebuiltByAlphabet",
  //      version: "2",
  //      value: "v2/x86_64_xhdpi.apk",
  //    }
  //
  //  - "LocalSource": The "value" field is the URL identifying where the local
  //  copy of the package source code can be found.
  //  Examples:
  //   - https://android.googlesource.com/platform/external/apache-http/
  //
  //  Typically, the metadata files describing a package reside in the same
  //  directory as the source code for the package. In a few rare cases where
  //  they are separate, the LocalSource URL identifies where to find the
  //  source code. This only describes where to find the local copy of the
  //  source; there should always be an additional URL describing where the
  //  package was retrieved from.
  //
  //  - "Other": An identifier that does not fit any other type. This may also
  //  indicate that the Source code was received via email or some other
  //  out-of-band way. This is most commonly used with commercial software
  //  received directly from the Vendor. In the case of email, the "value" field
  //  can be used to provide additional information about how it was received.
  optional string type = 1;

  // A human readable string to indicate why a third-package package does not
  // have this identifier type set.
  // Example:
  //   identifier {
  //     type: "PyPI"
  //     omission_reason: "Only on Git. Not published to PyPI."
  //   }
  optional string omission_reason = 2;

  // The value of the package identifier as defined by the "type".
  // Example:
  //  identifier {
  //    type: "PyPI"
  //    value: "django"
  //    version: "3.2.8"
  //  }
  optional string value = 3;

  // The version associated with this package as defined by the "type".
  // Example:
  //  identifier {
  //    type: "PyPI"
  //    value: "django"
  //    version: "3.2.8"
  //  }
  optional string version = 4;

  // The closest version associated with this package as defined by the "type".
  // This should only be set by automated infrastructure by applying automated
  // heuristics, such as the closest git tag or package version from a package
  // manifest file (e.g. pom.xml).
  //
  // For most identifier types, only one of `version` or `closest_version`
  // should be set (not both). The exception is source repository types such as
  // "Git", where `version` will refer to a git commit, and `closest_version`
  // refers to a git tag.
  // Example:
  //  identifier {
  //    type: "Git",
  //    value: "https://github.com/my/repo"
  //    version: "e5fa44f2b31c1fb553b6021e7360d07d5d91ff5e"
  //    closest_version: "v1.4"
  //  }
  optional string closest_version = 5;

  // When `true`, this Identifier represents the location from which the source
  // code for this package was originally obtained. This should only be set for
  // *one* Identifier in a third_party package's METADATA.

  // For external packages, this is typically for the Identifier associated
  // with the version control system or package manager that was used to
  // check out or download the code.
  optional bool primary_source = 6;
}