diff options
Diffstat (limited to 'doc/development/integrations/secure.md')
| -rw-r--r-- | doc/development/integrations/secure.md | 78 |
1 files changed, 43 insertions, 35 deletions
diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 356e731aa87..147d379cec7 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -327,21 +327,42 @@ You can find the schemas for these scanners here: - [Coverage Fuzzing](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json) - [Secret Detection](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/secret-detection-report-format.json) -### Version +### Enable report validation -This field specifies the version of the [Security Report Schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas) you are using. Please refer to the [releases](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases) of the schemas for the specific versions to use. +In GitLab 14.10 and later, report validation against the schemas is enabled. To enable report validation for versions earlier than 14.10, +set [`VALIDATE_SCHEMA`](../../user/application_security/#enable-security-report-validation) to +`"true"`. -### Vulnerabilities +Reports that don't pass validation are not ingested by GitLab, and an error message +displays on the corresponding pipeline. + +You should ensure that reports generated by the scanner pass validation against the schema version +declared in your reports. GitLab uses the +[`json_schemer`](https://www.rubydoc.info/gems/json_schemer) gem to perform validation. + +Ongoing improvements to report validation is tracked [in this epic](https://gitlab.com/groups/gitlab-org/-/epics/6968). + +### Report Fields + +#### Version + +This field specifies which [Security Report Schemas](https://gitlab.com/gitlab-org/security-products/security-report-schemas) version you are using. For information about the versions to use, see [releases](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/releases). + +In GitLab 14.10 and later, GitLab validates your report against the version of the schema specified by this value. +The versions supported by GitLab can be found in +[`gitlab/ee/lib/ee/gitlab/ci/parsers/security/validators/schemas`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/ee/lib/ee/gitlab/ci/parsers/security/validators/schemas). + +#### Vulnerabilities The `vulnerabilities` field of the report is an array of vulnerability objects. -#### ID +##### ID The `id` field is the unique identifier of the vulnerability. It is used to reference a fixed vulnerability from a [remediation objects](#remediations). We recommend that you generate a UUID and use it as the `id` field's value. -#### Category +##### Category The value of the `category` field matches the report type: @@ -351,12 +372,12 @@ The value of the `category` field matches the report type: - `sast` - `dast` -#### Scanner +##### Scanner The `scanner` field is an object that embeds a human-readable `name` and a technical `id`. The `id` should not collide with any other scanner another integrator would provide. -#### Name, message, and description +##### Name, message, and description The `name` and `message` fields contain a short description of the vulnerability. The `description` field provides more details. @@ -400,13 +421,13 @@ It should not repeat the other fields of the vulnerability object. In particular, the `description` should not repeat the `location` (what is affected) or the `solution` (how to mitigate the risk). -#### Solution +##### Solution You can use the `solution` field to instruct users how to fix the identified vulnerability or to mitigate the risk. End-users interact with this field, whereas GitLab automatically processes the `remediations` objects. -#### Identifiers +##### Identifiers The `identifiers` array describes the detected vulnerability. An identifier object's `type` and `value` fields are used to tell if two identifiers are the same. The user interface uses the @@ -440,15 +461,14 @@ Not all vulnerabilities have CVEs, and a CVE can be identified multiple times. A isn't a stable identifier and you shouldn't assume it as such when tracking vulnerabilities. The maximum number of identifiers for a vulnerability is set as 20. If a vulnerability has more than 20 identifiers, -the system saves only the first 20 of them. Note that vulnerabilities in the [Pipeline -Security](../../user/application_security/security_dashboard/#pipeline-security) +the system saves only the first 20 of them. Note that vulnerabilities in the [Pipeline Security](../../user/application_security/security_dashboard/#view-vulnerabilities-in-a-pipeline) tab do not enforce this limit and all identifiers present in the report artifact are displayed. -### Details +#### Details The `details` field is an object that supports many different content elements that are displayed when viewing vulnerability information. An example of the various data elements can be seen in the [security-reports repository](https://gitlab.com/gitlab-examples/security/security-reports/-/tree/master/samples/details-example). -### Location +#### Location The `location` indicates where the vulnerability has been detected. The format of the location depends on the type of scanning. @@ -458,7 +478,7 @@ which is used to track vulnerabilities as new commits are pushed to the repository. The attributes used to generate the location fingerprint also depend on the type of scanning. -#### Dependency Scanning +##### Dependency Scanning The `location` of a Dependency Scanning vulnerability is composed of a `dependency` and a `file`. The `dependency` object describes the affected `package` and the dependency `version`. @@ -488,7 +508,7 @@ combines the `file` and the package `name`, so these attributes are mandatory. All other attributes are optional. -#### Container Scanning +##### Container Scanning Similar to Dependency Scanning, the `location` of a Container Scanning vulnerability has a `dependency` and a `file`. @@ -519,7 +539,7 @@ so these attributes are mandatory. The `image` is also mandatory. All other attributes are optional. -#### Cluster Image Scanning +##### Cluster Image Scanning The `location` of a `cluster_image_scanning` vulnerability has a `dependency` field. It also has an `operating_system` field. For example, here is the `location` object for a vulnerability @@ -553,7 +573,7 @@ as well as the package `name`, so these fields are required. The `image` field i The `cluster_id` and `agent_id` are mutually exclusive, and one of them must be present. All other fields are optional. -#### SAST +##### SAST The `location` of a SAST vulnerability must have a `file` and a `start_line` field, giving the path of the affected file, and the affected line number, respectively. @@ -578,7 +598,7 @@ combines `file`, `start_line`, and `end_line`, so these attributes are mandatory. All other attributes are optional. -### Tracking and merging vulnerabilities +#### Tracking and merging vulnerabilities Users may give feedback on a vulnerability: @@ -606,7 +626,7 @@ and at least one [identifier](#identifiers). Two identifiers are the same if the CWE and WASC identifiers are not considered because they describe categories of vulnerability flaws, but not specific security flaws. -#### Severity and confidence +##### Severity and confidence The `severity` field describes how much the vulnerability impacts the software, whereas the `confidence` field describes how reliable the assessment of the vulnerability is. @@ -623,7 +643,7 @@ Valid values are: `Ignore`, `Unknown`, `Experimental`, `Low`, `Medium`, `High`, and needs to be investigated. We have [provided a chart](../../user/application_security/sast/analyzers.md#analyzers-data) of the available SAST Analyzers and what data is currently available. -### Remediations +#### Remediations The `remediations` field of the report is an array of remediation objects. Each remediation describes a patch that can be applied to @@ -667,28 +687,16 @@ Here is an example of a report that contains remediations. } ``` -#### Summary +##### Summary The `summary` field is an overview of how the vulnerabilities can be fixed. This field is required. -#### Fixed vulnerabilities +##### Fixed vulnerabilities The `fixes` field is an array of objects that reference the vulnerabilities fixed by the remediation. `fixes[].id` contains a fixed vulnerability's [unique identifier](#id). This field is required. -#### Diff +##### Diff The `diff` field is a base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). This field is required. - -## Limitations - -### Container Scanning - -Container Scanning currently has these limitations: - -- Although the Security Dashboard can display scan results from multiple images, if multiple - vulnerabilities have the same fingerprint, only the first instance of that vulnerability is - displayed. We're working on removing this limitation. You can follow our progress on the issue - [Change location fingerprint for Container Scanning](https://gitlab.com/gitlab-org/gitlab/-/issues/215466). -- Different scanners may each report the same vulnerability, resulting in duplicate findings. |