diff options
Diffstat (limited to 'doc/development/integrations/secure.md')
| -rw-r--r-- | doc/development/integrations/secure.md | 113 |
1 files changed, 58 insertions, 55 deletions
diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md index 43ca212bdf5..b0e1e28ba8b 100644 --- a/doc/development/integrations/secure.md +++ b/doc/development/integrations/secure.md @@ -2,14 +2,23 @@ Integrating a security scanner into GitLab consists of providing end users with a [CI job definition](../../ci/yaml/README.md#introduction) -they can add to their CI configuration files, to scan their GitLab projects. +they can add to their CI configuration files to scan their GitLab projects. +This CI job should then output its results in a GitLab-specified format. These results are then +automatically presented in various places in GitLab, such as the Pipeline view, Merge Request +widget, and Security Dashboard. + The scanning job is usually based on a [Docker image](https://docs.docker.com/) that contains the scanner and all its dependencies in a self-contained environment. -This page documents requirements and guidelines for writing CI jobs implementing a security scanner, -as well as requirements and guidelines for the Docker image itself. + +This page documents requirements and guidelines for writing CI jobs that implement a security +scanner, as well as requirements and guidelines for the Docker image. ## Job definition +This section desribes several important fields to add to the security scanner's job +definition file. Full documentation on these and other available fields can be viewed +in the [CI documentation](../../ci/yaml/README.md#image). + ### Name For consistency, scanning jobs should be named after the scanner, in lower case. @@ -26,8 +35,8 @@ containing the security scanner. ### Script The [`script`](../../ci/yaml/README.md#script) keyword -is used to specify the command that the job runs. -Because the `script` cannot be left empty, it must be set to the command that performs the scan. +is used to specify the commands to run the scanner. +Because the `script` entry can't be left empty, it must be set to the command that performs the scan. It is not possible to rely on the predefined `ENTRYPOINT` and `CMD` of the Docker image to perform the scan automatically, without passing any command. @@ -60,37 +69,34 @@ For example, here is the definition of a SAST job that generates a file named `g and uploads it as a SAST report: ```yaml -mysec_dependency_scanning: +mysec_sast_scanning: image: registry.gitlab.com/secure/mysec artifacts: reports: sast: gl-sast-report.json ``` -`gl-sast-report.json` is an example file path. See [the Output file section](#output-file) for more details. -It is processed as a SAST report because it is declared as such in the job definition. +Note that `gl-sast-report.json` is an example file path but any other file name can be used. See +[the Output file section](#output-file) for more details. It's processed as a SAST report because +it's declared under the `reports:sast` key in the job definition, not because of the file name. ### Policies -Scanning jobs should be skipped unless the corresponding feature is listed -in the `GITLAB_FEATURES` variable (comma-separated list of values). -So Dependency Scanning, Container Scanning, SAST, and DAST should be skipped -unless `GITLAB_FEATURES` contains `dependency_scanning`, `container_scanning`, `sast`, and `dast`, respectively. -See [GitLab CI/CD predefined variables](../../ci/variables/predefined_variables.md). +Certain GitLab workflows, such as [AutoDevOps](../../topics/autodevops/customize.md#disable-jobs), +define variables to indicate that given scans should be disabled. You can check for this by looking +for variables such as `DEPENDENCY_SCANNING_DISABLED`, `CONTAINER_SCANNING_DISABLED`, +`SAST_DISABLED`, and `DAST_DISABLED`. If appropriate based on the scanner type, you should then +disable running the custom scanner. -Also, scanning jobs should be skipped when the corresponding variable prefixed with `_DISABLED` is present. -See `DEPENDENCY_SCANNING_DISABLED`, `CONTAINER_SCANNING_DISABLED`, `SAST_DISABLED`, and `DAST_DISABLED` -in [Auto DevOps documentation](../../topics/autodevops/customize.md#disable-jobs). - -Finally, SAST and Dependency Scanning job definitions should use -`CI_PROJECT_REPOSITORY_LANGUAGES` (comma-separated list of values) -in order to skip the job when the language or technology is not supported. +GitLab also defines a `CI_PROJECT_REPOSITORY_LANGUAGES` variable, which provides the list of +languages in the repo. Depending on this value, your scanner may or may not do something different. Language detection currently relies on the [`linguist`](https://github.com/github/linguist) Ruby gem. See [GitLab CI/CD prefined variables](../../ci/variables/predefined_variables.md#variables-reference). -For instance, here is how to skip the Dependency Scanning job `mysec_dependency_scanning` -unless the project repository contains Java source code, -and the `dependency_scanning` feature is enabled: +#### Policy checking example + +This example shows how to skip a custom Dependency Scanning job, `mysec_dependency_scanning`, unless +the project repository contains Java source code and the `dependency_scanning` feature is enabled: ```yaml mysec_dependency_scanning: @@ -111,6 +117,8 @@ for a particular branch or when a particular set of files changes. The Docker image is a self-contained environment that combines the scanner with all the libraries and tools it depends on. +Packaging your scanner into a Docker image makes its dependencies and configuration always present, +regardless of the individual machine the scanner runs on. ### Image size @@ -144,7 +152,7 @@ It also generates text output on the standard output and standard error streams, All CI variables are passed to the scanner as environment variables. The scanned project is described by the [predefined CI variables](../../ci/variables/README.md). -#### SAST, Dependency Scanning +#### SAST and Dependency Scanning SAST and Dependency Scanning scanners must scan the files in the project directory, given by the `CI_PROJECT_DIR` variable. @@ -223,11 +231,8 @@ The DAST variant of the report JSON format is not documented at the moment. ### Version -The documentation of -[SAST](../../user/application_security/sast/index.md#reports-json-format), -[Dependency Scanning](../../user/application_security/dependency_scanning/index.md#reports-json-format), -and [Container Scanning](../../user/application_security/container_scanning/index.md#reports-json-format) -describes the Secure report format version. +This field specifies the version of the report schema you are using. Please reference individual scanner +pages for the specific versions to use. ### Vulnerabilities @@ -251,12 +256,17 @@ The `id` should not collide with any other scanner another integrator would prov #### Name, message, and description -The `name` and `message` fields contain a short description of the vulnerability, -whereas the `description` field provides more details. +The `name` and `message` fields contain a short description of the vulnerability. +The `description` field provides more details. -The `name` is context-free and contains no information on where the vulnerability has been found, +The `name` field is context-free and contains no information on where the vulnerability has been found, whereas the `message` may repeat the location. +As a visual example, this screenshot highlights where these fields are used when viewing a +vulnerability as part of a pipeline view. + + + For instance, a `message` for a vulnerability reported by Dependency Scanning gives information on the vulnerable dependency, which is redundant with the `location` field of the vulnerability. @@ -288,21 +298,17 @@ 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). -There is a proposal to remove either the `name` or the `message`, to remove ambiguities. -See [issue #36779](https://gitlab.com/gitlab-org/gitlab/issues/36779). - #### Solution -The `solution` field may contain instructions users should follow to fix the vulnerability or to mitigate the risk. -It is intended for users whereas the `remediations` objects are processed automatically by GitLab. +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 -The `identifiers` array describes the vulnerability flaw that has been detected. -An identifier object has a `type` and a `value`; -these technical fields are used to tell if two identifiers are the same. -It also has a `name` and a `url`; -these fields are used to display the identifier in the user interface. +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 +object's `name` and `url` fields to display the identifier. It is recommended to reuse the identifiers the GitLab scanners already define: @@ -316,18 +322,15 @@ It is recommended to reuse the identifiers the GitLab scanners already define: | [RHSA](https://access.redhat.com/errata/#/) | `rhsa` | RHSA-2020:0111 | | [ELSA](https://linux.oracle.com/security/) | `elsa` | ELSA-2020-0085 | -The generic identifiers listed above are defined in the [common library](https://gitlab.com/gitlab-org/security-products/analyzers/common); -this library is shared by the analyzers maintained by GitLab, -and this is where you can [contribute](https://gitlab.com/gitlab-org/security-products/analyzers/common/blob/master/issue/identifier.go) new generic identifiers. -Analyzers may also produce vendor-specific or product-specific identifiers; -these do not belong to the [common library](https://gitlab.com/gitlab-org/security-products/analyzers/common). +The generic identifiers listed above are defined in the [common library](https://gitlab.com/gitlab-org/security-products/analyzers/common), +which is shared by the analyzers that GitLab maintains. You can [contribute](https://gitlab.com/gitlab-org/security-products/analyzers/common/blob/master/issue/identifier.go) +new generic identifiers to if needed. Analyzers may also produce vendor-specific or product-specific +identifiers, which don't belong in the [common library](https://gitlab.com/gitlab-org/security-products/analyzers/common). The first item of the `identifiers` array is called the primary identifier. The primary identifier is particularly important, because it is used to -[track vulnerabilities](#tracking-merging-vulnerabilities) -as new commits are pushed to the repository. - -Identifiers are used to [merge duplicate vulnerabilities](#tracking-merging-vulnerabilities) +[track vulnerabilities](#tracking-and-merging-vulnerabilities) as new commits are pushed to the repository. +Identifiers are also used to [merge duplicate vulnerabilities](#tracking-and-merging-vulnerabilities) reported for the same commit, except for `CWE` and `WASC`. ### Location @@ -336,7 +339,7 @@ The `location` indicates where the vulnerability has been detected. The format of the location depends on the type of scanning. Internally GitLab extracts some attributes of the `location` to generate the **location fingerprint**, -which is used to [track vulnerabilities](#tracking-merging-vulnerabilities) +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. @@ -426,12 +429,12 @@ combines `file`, `start_line`, and `end_line`, so these attributes are mandatory. All other attributes are optional. -### Tracking, merging vulnerabilities +### Tracking and merging vulnerabilities Users may give feedback on a vulnerability: -- they may dismiss a vulnerability if it does not apply to their projects -- or they may create an issue for a vulnerability, if there is a possible threat +- They may dismiss a vulnerability if it doesn't apply to their projects +- They may create an issue for a vulnerability if there's a possible threat GitLab tracks vulnerabilities so that user feedback is not lost when new Git commits are pushed to the repository. |