summaryrefslogtreecommitdiff
path: root/doc/development/integrations/secure.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/development/integrations/secure.md')
-rw-r--r--doc/development/integrations/secure.md78
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.