Vulnerability contract

This is the pinned seagull.vulnerability.v1 wire definition. A declared message describes a protocol shape; it does not prove that every producer or consumer is implemented. See contract compatibility and implementation status.

Severity

message Severity {
  enum Type {
    TYPE_UNSPECIFIED = 0;
    TYPE_CVSS_V2 = 1;
    TYPE_CVSS_V3 = 2;
    TYPE_CVSS_V4 = 3;

    // Ubuntu's own priority, in Ubuntu's own words: `negligible`, `low`,
    // `medium`, `high` or `critical`.
    TYPE_UBUNTU = 4;
  }

  Type type = 1;
  string score = 2;

  // Who assessed it — `NVD`, `CNA`, `SELF` — when the source says. Empty means
  // the database that published the advisory.
  string assessed_by = 3;
}

Event

message Event {
  oneof boundary {
    // `0` is a version that sorts before every other.
    string introduced = 1;
    string fixed = 2;
    string last_affected = 3;
    string limit = 4;
  }
}

Range

message Range {
  enum Type {
    TYPE_UNSPECIFIED = 0;

    // Ordered the way the package's own ecosystem orders its versions: dpkg
    // for Debian and Ubuntu, apk for Alpine, rpm for the RPM distributions.
    TYPE_ECOSYSTEM = 1;
    TYPE_SEMVER = 2;
  }

  Type type = 1;
  repeated Event events = 2;
}

Affected

message Affected {
  // The ecosystem as the platform names it, release included: `Debian:12`,
  // `Ubuntu:22.04:LTS`, `Alpine:v3.19`, `Rocky Linux:9`, `AlmaLinux:9`. A
  // package is compared against one release of its distribution, so the
  // release is part of the name rather than a detail of it.
  string ecosystem = 1;

  // The package as that ecosystem's advisories name it, which for most
  // distributions is the source package rather than a binary built from it.
  string name = 2;

  repeated Range ranges = 3;

  // Versions the source lists as affected. A version is affected when it lies
  // in any range or is listed here. A list is often the source's own expansion
  // of its ranges and is kept whole all the same: telling the two apart needs
  // the ecosystem's version ordering, which belongs to whoever matches.
  repeated string versions = 4;

  // Set only when the source rates this package differently from the rest of
  // the advisory.
  repeated Severity severities = 5;
}

Provenance

message Provenance {
  // The export the advisory was read from, such as `Debian`, and the version
  // of that export's index when it was read.
  string feed = 1;
  string feed_version = 2;

  string location = 3;
  google.protobuf.Timestamp fetched_at = 4;

  // The SHA-256 of the bytes as they were fetched, so what the platform holds
  // can be checked against the source for as long as the source keeps it.
  string digest = 5;

  // The format and its version as the record declared them, such as
  // `osv 1.9.0`.
  string format = 6;

  // The version of the rules the platform translated the record with. A build
  // with newer rules reads the record again rather than keeping a reading it
  // would no longer make.
  uint32 normalization = 7;
}

Advisory

message Advisory {
  uint32 schema_version = 1;

  // The database the platform read it from, such as `osv`, and the id there.
  string source = 2;
  string id = 3;

  google.protobuf.Timestamp modified = 4;
  google.protobuf.Timestamp published = 5;

  // Set when the source withdrew it. A withdrawn advisory is kept rather than
  // removed, because what was once concluded from it has to stay explicable,
  // and it is never matched again.
  google.protobuf.Timestamp withdrawn = 6;

  // The same vulnerability under other ids.
  repeated string aliases = 7;

  // The vulnerabilities this one derives from, the way a distribution's
  // advisory derives from the upstream CVEs it fixes. Not the same
  // vulnerability, and so not an alias.
  repeated string upstream = 8;

  repeated string related = 9;

  string summary = 10;
  string details = 11;

  repeated Severity severities = 12;
  repeated Affected affected = 13;

  Provenance provenance = 14;
}

FeedSync

message FeedSync {
  enum Outcome {
    OUTCOME_UNSPECIFIED = 0;

    // Every advisory the feed listed was read, or refused and counted.
    OUTCOME_COMPLETE = 1;

    // Some were read and the rest are still owed. What was read is published,
    // and what was held before is exactly as fresh as the last complete sync.
    OUTCOME_PARTIAL = 2;

    // The feed could not be read at all, and nothing held was changed.
    OUTCOME_FAILED = 3;
  }

  string source = 1;
  string feed = 2;
  string feed_version = 3;
  Outcome outcome = 4;

  // When this attempt asked, and when the platform last held everything the
  // feed listed. The second is carried forward by an attempt that did not
  // complete, so it always says how old the platform's copy of the feed is.
  google.protobuf.Timestamp checked_at = 5;
  google.protobuf.Timestamp synced_at = 6;

  // The newest change the feed itself lists: how current the feed is, as
  // distinct from how current the platform's copy of it is.
  google.protobuf.Timestamp newest_listed = 7;

  uint32 listed = 8;
  uint32 held = 9;
  uint32 published = 10;
  uint32 refused = 11;

  // Why the attempt did not complete, in the platform's own words and never
  // the feed's.
  string failure = 12;
}

Record

message Record {
  oneof record {
    Advisory advisory = 1;
    FeedSync sync = 2;
  }
}

Source evidence

Generated from proto/seagull/vulnerability/v1/advisory.proto at d2090c5. Refresh the checked-in snapshot before regenerating; a normal build does not access another repository.