diff --git a/grafeas/v1/grafeas.proto b/grafeas/v1/grafeas.proto index 21ea46f1..80a94127 100644 --- a/grafeas/v1/grafeas.proto +++ b/grafeas/v1/grafeas.proto @@ -171,8 +171,10 @@ message Occurrence { // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`. string name = 1; - // Required. Immutable. The resource for which the occurrence applies. - Resource resource = 2; + // Required. Immutable. A URI that represents the resource for which the + // occurrence applies. For example, + // `https://gcr.io/project/image@sha256:123abc` for a Docker image. + string resource_uri = 2; // Required. Immutable. The analysis note associated with this occurrence, in // the form of `projects/[PROVIDER_ID]/notes/[NOTE_ID]`. This field can be @@ -211,24 +213,6 @@ message Occurrence { // Describes an attestation of an artifact. grafeas.v1.AttestationOccurrence attestation = 14; } - - // next_id = 15; -} - -// An entity that can have metadata. For example, a Docker image. -message Resource { - // The name of the resource. For example, the name of a Docker image - - // "Debian". - string name = 1; - - // Required. The unique URI of the resource. For example, - // `https://gcr.io/project/image@sha256:foo` for a Docker image. - string uri = 2; - - // The hash of the resource content. For example, the Docker digest. - grafeas.v1.Hash content_hash = 3; - - // next_id = 4; } // A type of analysis that can be done for a resource. @@ -281,8 +265,6 @@ message Note { // A note describing an attestation role. grafeas.v1.AttestationNote attestation = 16; } - - // next_id = 17; } // Request to get an occurrence. @@ -307,8 +289,6 @@ message ListOccurrencesRequest { // Token to provide to skip to a particular spot in the list. string page_token = 4; - - // next_id = 7; } // Response for listing occurrences. diff --git a/grafeas/v1/image.proto b/grafeas/v1/image.proto index cd2f65b0..9ac162ce 100644 --- a/grafeas/v1/image.proto +++ b/grafeas/v1/image.proto @@ -48,10 +48,10 @@ message Fingerprint { } // Basis describes the base image portion (Note) of the DockerImage -// relationship. Linked occurrences are derived from this or an -// equivalent image via: +// relationship. Linked occurrences are derived from this or an equivalent image +// via: // FROM -// Or an equivalent reference, e.g. a tag of the resource_url. +// Or an equivalent reference, e.g., a tag of the resource_url. message ImageNote { // Required. Immutable. The resource_url for the resource representing the // basis of associated occurrence images. @@ -61,16 +61,10 @@ message ImageNote { Fingerprint fingerprint = 2; } -// Details of an image occurrence. +// Details of the derived image portion of the DockerImage relationship. This +// image would be produced from a Dockerfile with FROM . message ImageOccurrence { - // Required. Immutable. The child image derived from the base image. - Derived derived_image = 1; -} - -// Derived describes the derived image portion (Occurrence) of the DockerImage -// relationship. This image would be produced from a Dockerfile with FROM -// . -message Derived { // Required. The fingerprint of the derived image. Fingerprint fingerprint = 1; diff --git a/grafeas/v1/package.proto b/grafeas/v1/package.proto index 72e005df..b04686d9 100644 --- a/grafeas/v1/package.proto +++ b/grafeas/v1/package.proto @@ -80,15 +80,8 @@ message PackageNote { repeated Distribution distribution = 10; } -// Details of a package occurrence. +// Details on how a particular software package was installed on a system. message PackageOccurrence { - // 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; diff --git a/grafeas/v1/provenance.proto b/grafeas/v1/provenance.proto index 937f8a2d..533c835c 100644 --- a/grafeas/v1/provenance.proto +++ b/grafeas/v1/provenance.proto @@ -67,8 +67,6 @@ message BuildProvenance { // Version string of the builder at the time this build was executed. string builder_version = 13; - - // next_id = 14 } // Source describes the location of the source used for the build. diff --git a/grafeas/v1/vulnerability.proto b/grafeas/v1/vulnerability.proto index 9f012f91..f6543a8f 100644 --- a/grafeas/v1/vulnerability.proto +++ b/grafeas/v1/vulnerability.proto @@ -25,7 +25,7 @@ option java_multiple_files = true; option java_package = "io.grafeas.v1"; option objc_class_prefix = "GRA"; -// Note provider-assigned severity/impact ranking. +// Note provider assigned severity/impact ranking. enum Severity { // Unknown. SEVERITY_UNSPECIFIED = 0; @@ -41,57 +41,60 @@ enum Severity { CRITICAL = 5; } -// Vulnerability provides metadata about a security vulnerability in a Note. +// A security vulnerability that can be found in resources. message VulnerabilityNote { - // The CVSS score for this vulnerability. + // The CVSS score of this vulnerability. CVSS score is on a scale of 0 - 10 + // where 0 indicates low severity and 10 indicates high severity. float cvss_score = 1; - // Note provider assigned impact of the vulnerability. + // The note provider assigned severity of this vulnerability. Severity severity = 2; - // All information about the package to specifically identify this - // vulnerability. One entry per (version range and cpe_uri) the package - // vulnerability has manifested in. + // Details of all known distros and packages affected by this vulnerability. repeated Detail details = 3; - // Identifies all appearances of this vulnerability in the package for a - // specific distro/location. For example: glibc in - // cpe:/o:debian:debian_linux:8 for versions 2.1 - 2.2 + // A detail for a distro and package affected by this vulnerability and its + // associated fix (if one is available). message Detail { - // Required. The CPE URI in - // [cpe format](https://cpe.mitre.org/specification/) in which the - // vulnerability manifests. Examples include distro or storage location for - // vulnerable jar. - string cpe_uri = 1; + // The distro assigned severity of this vulnerability. + string severity_name = 1; - // Required. The name of the package where the vulnerability was found. - string package = 2; + // A vendor-specific description of this vulnerability. + string description = 2; - // The min version of the package in which the vulnerability exists. - grafeas.v1.Version min_affected_version = 3; + // The type of package; whether native or non native (e.g., ruby gems, + // node.js packages, etc.). + string package_type = 3; - // The max version of the package in which the vulnerability exists. - grafeas.v1.Version max_affected_version = 4; + // Required. The [CPE URI](https://cpe.mitre.org/specification/) this + // vulnerability affects. + string affected_cpe_uri = 4; - // The severity (eg: distro assigned severity) for this vulnerability. - string severity_name = 5; + // Required. The package this vulnerability affects. + string affected_package = 5; - // A vendor-specific description of this note. - string description = 6; + // Required. The minimum version of the package this vulnerability affects. + grafeas.v1.Version min_affected_version = 6; - // The fix for this specific package version. - VulnerabilityLocation fixed_location = 7; + // The [CPE URI](https://cpe.mitre.org/specification/) this vulnerability + // was fixed in. It is possible for this to be different from the + // affected_cpe_uri. + string fixed_cpe_uri = 7; - // The type of package; whether native or non native(ruby gems, node.js - // packages etc). - string package_type = 8; + // The package this vulnerability was fixed in. It is possible for this to + // be different from the affected_package. + string fixed_package = 8; + + // Required. The version of the package this vulnerability was fixed in. + // Setting this to VersionKind.MAXIMUM means no fix is yet available. + grafeas.v1.Version fixed_version = 9; // Whether this detail is obsolete. Occurrences are expected not to point to // obsolete details. - bool is_obsolete = 9; + bool is_obsolete = 10; } - // The full description of the CVSSv3. + // The full description of the CVSSv3 for this vulnerability. CVSSv3 cvss_v3 = 4; // Windows details get their own format because the information format and @@ -101,47 +104,43 @@ message VulnerabilityNote { repeated WindowsDetail windows_details = 5; message WindowsDetail { - // Required. The CPE URI in - // [cpe format](https://cpe.mitre.org/specification/) in which the - // vulnerability manifests. Examples include distro or storage location for - // vulnerable jar. + // Required. The [CPE URI](https://cpe.mitre.org/specification/) this + // vulnerability affects. string cpe_uri = 1; - // Required. The name of the vulnerability. + // Required. The name of this vulnerability. string name = 2; - // The description of the vulnerability. + // The description of this vulnerability. string description = 3; // Required. The names of the KBs which have hotfixes to mitigate this // vulnerability. Note that there may be multiple hotfixes (and thus // multiple KBs) that mitigate a given vulnerability. Currently any listed - // kb's presence is considered a fix. + // KBs presence is considered a fix. repeated KnowledgeBase fixing_kbs = 4; message KnowledgeBase { - // The KB name (generally of the form KB[0-9]+ i.e. KB123456). + // The KB name (generally of the form KB[0-9]+ (e.g., KB123456)). string name = 1; - // A link to the KB in the Windows update catalog - - // https://www.catalog.update.microsoft.com/ + // A link to the KB in the [Windows update catalog] + // (https://www.catalog.update.microsoft.com/). string url = 2; } } - - // Next free ID is 6. } -// Details of a vulnerability Occurrence. +// An occurrence of a severity vulnerability on a resource. message VulnerabilityOccurrence { - // The type of package; whether native or non native(ruby gems, node.js - // packages etc) + // The type of package; whether native or non native (e.g., ruby gems, node.js + // packages, etc.). string type = 1; - // Output only. The note provider assigned Severity of the vulnerability. + // Output only. The note provider assigned severity of this vulnerability. Severity severity = 2; // Output only. The CVSS score of this vulnerability. CVSS score is on a - // scale of 0-10 where 0 indicates low severity and 10 indicates high + // scale of 0 - 10 where 0 indicates low severity and 10 indicates high // severity. float cvss_score = 3; @@ -149,6 +148,37 @@ message VulnerabilityOccurrence { // within the associated resource. repeated PackageIssue package_issue = 4; + // A detail for a distro and package this vulnerability occurrence was found + // in and its associated fix (if one is available). + message PackageIssue { + // Required. The [CPE URI](https://cpe.mitre.org/specification/) this + // vulnerability was found in. + string affected_cpe_uri = 1; + + // Required. The package this vulnerability was found in. + string affected_package = 2; + + // Required. The minimum version of the package this vulnerability exists + // in. + grafeas.v1.Version min_affected_version = 3; + + // The [CPE URI](https://cpe.mitre.org/specification/) this vulnerability + // was fixed in. It is possible for this to be different from the + // affected_cpe_uri. + string fixed_cpe_uri = 4; + + // The package this vulnerability was fixed in. It is possible for this to + // be different from the affected_package. + string fixed_package = 5; + + // Required. The version of the package this vulnerability was fixed in. + // Setting this to VersionKind.MAXIMUM means no fix is yet available. + grafeas.v1.Version fixed_version = 6; + + // Output only. Whether a fix is available for this package. + bool fix_available = 7; + } + // Output only. A one sentence description of this vulnerability. string short_description = 5; @@ -158,55 +188,12 @@ message VulnerabilityOccurrence { // Output only. URLs related to this vulnerability. repeated grafeas.v1.RelatedUrl related_urls = 7; - // The distro assigned severity for this vulnerability when it is - // available, and note provider assigned severity when distro has not yet - // assigned a severity for this vulnerability. + // The distro assigned severity for this vulnerability when it is available, + // and note provider assigned severity when distro has not yet assigned a + // severity for this vulnerability. Severity effective_severity = 8; - // Output only. True if at least one of the affected packages - // has a fix available. + // Output only. Whether at least one of the affected packages has a fix + // available. bool fix_available = 9; } - -// This message wraps a package, version and cpe_uri affected by a vulnerability -// and its associated fix (if one is available). -message PackageIssue { - // Required. The CPE URI in [cpe format](https://cpe.mitre.org/specification/) - // format. Examples include distro or storage location for vulnerable jar. - string affected_cpe_uri = 1; - - // Required. The package being described. - string affected_package = 2; - - // Required. The affected version of the vulnerability. - grafeas.v1.Version affected_version = 3; - - // The CPE URI in [cpe format](https://cpe.mitre.org/specification/) - // format. Examples include distro or storage location for vulnerable jar. - // It is possible for fixed_cpe_uri to be different from affected_cpe_uri. - string fixed_cpe_uri = 4; - - // The package in which fix is available. It is possible for fixed_package - // to be different from affected_package. - string fixed_package = 5; - - // Required. The fixed version of the vulnerability. Setting this to - // Version.MAXIMUM implies no fix is available. - grafeas.v1.Version fixed_version = 6; - - // Required. True if at a fix is available for this package. - bool fix_available = 7; -} - -// The location of the vulnerability. -message VulnerabilityLocation { - // Required. The CPE URI in [cpe format](https://cpe.mitre.org/specification/) - // format. Examples include distro or storage location for vulnerable jar. - string cpe_uri = 1; - - // Required. The package being described. - string package = 2; - - // Required. The version of the package being described. - grafeas.v1.Version version = 3; -}