tools/protos/metadata_file.proto - platform/build - Git at Google

 // 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;
   }

 }

 // 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;
 }
	// 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;
	}

	}

	// 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;
	}