vulnerability.proto

// Copyright 2025 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 osv;

import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

option go_package = "github.com/ossf/osv-schema/bindings/go/osvschema";

// Commit reference (DEPRECATED).
//
// In some rare cases, this may refer to a small range of commits rather than an
// exact commit (to accommodate for automated systems). In such cases, the
// semantics are as follows:
//
// - If this is referring to a commit which introduces a vulnerability, then
// *any* commits in the range is assumed to cause the vulnerability.
//
// - If this is referring to a commit which fixes a vulnerability, then *all*
// commits in the range is assumed to cause the vulnerability.
message Commit {
  option deprecated = true;
  // The repository type.
  enum RepoType {
    UNSPECIFIED = 0;
    GIT = 1;
  }

  // Required. The type of the repo.
  RepoType repo_type = 1;
  // Required. The publicly accessible URL of the repo that can be directly
  // passed to clone commands.
  string repo_url = 2;
  // Required. The commit identifier (e.g. git SHA). In some cases where the
  // exact commit fails to be determined by automation, this may be a small
  // range in the form "A:B" which means the commit range from A (exclusive) to
  // B (inclusive).
  string commit = 3;
}

// Package information and version.
message Package {
  // Required. Name of the package. Should match the name used in the package
  // ecosystem (e.g. the npm package name). For C/C++ projects integrated in
  // OSS-Fuzz, this is the name used for the integration.
  string name = 1;
  // Required. The ecosystem for this package.
  // For the complete list of valid ecosystem names, see
  // <https://ossf.github.io/osv-schema/#affectedpackage-field>.
  string ecosystem = 2;
  // Optional. The package URL for this package.
  string purl = 3;
}

// Version events.
message Event {
  // The earliest version/commit where this vulnerability
  // was introduced in.
  string introduced = 1;
  // The version/commit that this vulnerability was fixed in.
  string fixed = 2;
  // The limit to apply to the range.
  string limit = 3;
  // The last affected version.
  string last_affected = 4 [json_name="last_affected"];
}

// Affected ranges.
message Range {
  // Type of the version information.
  enum Type {
    UNSPECIFIED = 0;
    GIT = 1;
    SEMVER = 2;
    ECOSYSTEM = 3;
  }
  // Required. The type of version information.
  Type type = 1;
  // Required if type is GIT. The publicly accessible URL of the repo that can
  // be directly passed to clone commands.
  string repo = 2;
  // Required. Version event information.
  repeated Event events = 3;
  // Optional. JSON object holding additional information about the
  // vulnerability as defined by the database for which the record applies.
  google.protobuf.Struct database_specific = 4 [json_name="database_specific"];
}

// Affected versions and commits.
message Affected {
  // Optional. Package information.
  Package package = 1;
  // Required. Range information.
  repeated Range ranges = 2;
  // Optional. List of affected versions.
  repeated string versions = 3;
  // Optional. JSON object holding additional information about the
  // vulnerability as defined by the ecosystem for which the record applies.
  google.protobuf.Struct ecosystem_specific = 4 [json_name="ecosystem_specific"];
  // Optional. JSON object holding additional information about the
  // vulnerability as defined by the database for which the record applies.
  google.protobuf.Struct database_specific = 5 [json_name="database_specific"];
  // Optional. Severity of the vulnerability for this package.
  repeated Severity severity = 6;
}

message Severity {
  // Type of the severity.
  enum Type {
    UNSPECIFIED = 0;
    CVSS_V3 = 1;
    CVSS_V2 = 2;
    CVSS_V4 = 3;
    Ubuntu = 4;
  }
  // The type of this severity entry.
  Type type = 1;
  // The quantitative score.
  string score = 2;
}

message Credit {
  // The name to give credit to.
  string name = 1;
  // Contact methods (URLs).
  repeated string contact = 2;

  enum Type {
    UNSPECIFIED = 0;
    OTHER = 1;
    FINDER = 2;
    REPORTER = 3;
    ANALYST = 4;
    COORDINATOR = 5;
    REMEDIATION_DEVELOPER = 6;
    REMEDIATION_REVIEWER = 7;
    REMEDIATION_VERIFIER = 8;
    TOOL = 9;
    SPONSOR = 10;
  }
  // Optional. The type or role of the individual or entity being credited.
  Type type = 3;
}

// Reference URL.
message Reference {
  enum Type {
    // Next ID = 12.
    NONE = 0;
    ADVISORY = 2;
    ARTICLE = 6;
    DETECTION = 9;
    DISCUSSION = 8;
    EVIDENCE = 7;
    FIX = 4;
    GIT = 11;
    INTRODUCED = 10;
    PACKAGE = 5;
    REPORT = 3;
    WEB = 1;
  }

  // Required. The type of the reference.
  Type type = 1;
  // Required. The URL.
  string url = 2;
}

// A vulnerability entry.
// The protobuf representation is *NOT* stable and only used for implementing
// the JSON based API.
message Vulnerability {
  // The OSV schema version.
  string schema_version = 18 [json_name="schema_version"];
  // The `id` field is a unique identifier for the vulnerability entry. It is a
  // string of the format `<DB>-<ENTRYID>`, where `DB` names the database and
  // `ENTRYID` is in the format used by the database. For example:
  // “OSV-2020-111”, “CVE-2021-3114”, or “GHSA-vp9c-fpxx-744v”.
  string id = 1;
  // The RFC3339 timestamp indicating when this entry was published.
  google.protobuf.Timestamp published = 11;
  // The RFC3339 timestamp indicating when this entry was last modified.
  google.protobuf.Timestamp modified = 10;
  // Optional. The RFC3339 timestamp indicating when this entry is considered to
  // be withdrawn.
  google.protobuf.Timestamp withdrawn = 12;
  // Optional. IDs for the same vulnerability in other databases.
  repeated string aliases = 8;
  // Optional. List of IDs of closely related vulnerabilities, such as the same
  // problem in alternate ecosystems.
  repeated string related = 13;
  // Optional. List of IDs of upstream vulnerabilities of a vulnerability.
  repeated string upstream = 14;
  // Required. One line human readable summary for the vulnerability. It is
  // recommended to keep this under 120 characters.
  string summary = 3;
  // Required. Any additional human readable details for the vulnerability.
  string details = 4;
  // Required. Affected commit ranges and versions.
  repeated Affected affected = 17;
  // Optional. URLs to more information/advisories (including the
  // scheme e.g. "https://").
  repeated Reference references = 16;
  // Optional. JSON object holding additional information about the
  // vulnerability as defined by the database for which the record applies.
  google.protobuf.Struct database_specific = 15 [json_name="database_specific"];
  // Optional. Severity of the vulnerability.
  repeated Severity severity = 19;
  // Optional. Credits for the vulnerability.
  repeated Credit credits = 20;
}