Merge branch 'doc/sec-report-integration-validation' into 'master'

Add information about security report validation

See merge request gitlab-org/gitlab!77085

doc/development/integrations/secure.md

@@ -327,21 +327,43 @@ 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
+
+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"`. 
+
+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 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.
+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
+#### 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 +373,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 +422,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
@@ -443,11 +465,11 @@ The maximum number of identifiers for a vulnerability is set as 20. If a vulnera
 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.
@@ -457,7 +479,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`.
@@ -487,7 +509,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`.
@@ -518,7 +540,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
@@ -552,7 +574,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.
@@ -577,7 +599,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:
 
@@ -605,7 +627,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.
@@ -622,7 +644,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
@@ -666,16 +688,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.