diff options
Diffstat (limited to 'doc/user/application_security')
22 files changed, 455 insertions, 354 deletions
diff --git a/doc/user/application_security/api_fuzzing/index.md b/doc/user/application_security/api_fuzzing/index.md index a0f14ea59a1..be6b06a0797 100644 --- a/doc/user/application_security/api_fuzzing/index.md +++ b/doc/user/application_security/api_fuzzing/index.md @@ -12,10 +12,6 @@ parameters to unexpected values in an effort to cause unexpected behavior and er backend. This helps you discover bugs and potential security issues that other QA processes may miss. -INFO: -Try fuzz testing in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-api-fuzzing-docs). - We recommend that you use fuzz testing in addition to [GitLab Secure](../index.md)'s other security scanners and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), you can run fuzz tests as part your CI/CD workflow. @@ -572,6 +568,7 @@ profile increases as the number of tests increases. |[`FUZZAPI_PROFILE`](#api-fuzzing-profiles) | Configuration profile to use during testing. Defaults to `Quick-10`. | |[`FUZZAPI_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`FUZZAPI_OPENAPI`](#openapi-specification) | OpenAPI Specification file or URL. | +|[`FUZZAPI_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | |[`FUZZAPI_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`FUZZAPI_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`FUZZAPI_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract Postman variable values. | @@ -1293,6 +1290,41 @@ The API Fuzzing template supports launching a docker container containing an API TODO --> +### Use OpenAPI with an invalid schema + +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. + +#### Edit a non-compliant OpenAPI file + +To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include: + +| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | +| -- | -- | -- | -- | +| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | + +If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. + +#### Enable OpenAPI relaxed validation + +Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. + +API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `FUZZAPI_OPENAPI_RELAXED_VALIDATION` to any value, for example: + +```yaml + stages: + - fuzz + + include: + - template: API-Fuzzing.gitlab-ci.yml + + variables: + FUZZAPI_PROFILE: Quick-10 + FUZZAPI_TARGET_URL: http://test-deployment/ + FUZZAPI_OPENAPI: test-api-specification.json + FUZZAPI_OPENAPI_RELAXED_VALIDATION: On +``` + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/cluster_image_scanning/index.md b/doc/user/application_security/cluster_image_scanning/index.md index c3a2c179590..5f2dd626526 100644 --- a/doc/user/application_security/cluster_image_scanning/index.md +++ b/doc/user/application_security/cluster_image_scanning/index.md @@ -41,6 +41,8 @@ in your existing `.gitlab-ci.yml` file. To enable cluster image scanning in your pipeline, you need the following: +- Cluster Image Scanning runs in the `test` stage, which is available by default. If you redefine the stages + in the `.gitlab-ci.yml` file, the `test` stage is required. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) @@ -172,10 +174,10 @@ You can [configure](#customize-the-cluster-image-scanning-settings) analyzers by | CI/CD Variable | Default | Description | | ------------------------------ | ------------- | ----------- | | `CIS_KUBECONFIG` | `""` | File used to configure access to the Kubernetes cluster. See the [Kubernetes documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) for more details. | -| `CIS_CONTAINER_NAME` | `""` | Name of the container used in the Kubernetes resource you want to filter vulnerabilities for. For example, `alpine`. | -| `CIS_RESOURCE_NAME` | `""` | Name of the Kubernetes resource you want to filter vulnerabilities for. For example, `nginx`. | -| `CIS_RESOURCE_NAMESPACE` | `""` | Namespace of the Kubernetes resource you want to filter vulnerabilities for. For example, `production`. | -| `CIS_RESOURCE_KIND` | `""` | Kind of the Kubernetes resource you want to filter vulnerabilities for. For example, `deployment`. | +| `CIS_CONTAINER_NAMES` | `""` | A comma-separated list of container names used in the Kubernetes resources you want to filter vulnerabilities for. For example, `alpine,postgres`. | +| `CIS_RESOURCE_NAMES` | `""` | A comma-separated list of Kubernetes resources you want to filter vulnerabilities for. For example, `nginx,redis`. | +| `CIS_RESOURCE_NAMESPACES` | `""` | A comma-separated list of namespaces of the Kubernetes resources you want to filter vulnerabilities for. For example, `production,staging`. | +| `CIS_RESOURCE_KINDS` | `""` | A comma-separated list of the kinds of Kubernetes resources to filter vulnerabilities for. For example, `deployment,pod`. | | `CIS_CLUSTER_IDENTIFIER` | `""` | ID of the Kubernetes cluster integrated with GitLab. This is used to map vulnerabilities to the cluster so they can be filtered in the Vulnerability Report page. | | `CIS_CLUSTER_AGENT_IDENTIFIER` | `""` | ID of the Kubernetes cluster agent integrated with GitLab. This maps vulnerabilities to the agent so they can be filtered in the Vulnerability Report page. | diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index bea9284873c..5a2dd5eb54f 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -9,10 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3672) in GitLab 10.4. -INFO: -Try out Container Scanning in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-container-scanning-docs). - Your application's Docker image may itself be based on Docker images that contain known vulnerabilities. By including an extra Container Scanning job in your pipeline that scans for those vulnerabilities and displays them in a merge request, you can use GitLab to audit your Docker-based @@ -52,6 +48,7 @@ information directly in the merge request. To enable container scanning in your pipeline, you need the following: +- Container Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. - [GitLab Runner](https://docs.gitlab.com/runner/) with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. - Docker `18.09.03` or higher installed on the same computer as the runner. If you're using the @@ -62,6 +59,7 @@ To enable container scanning in your pipeline, you need the following: - If you're using a third-party container registry, you might need to provide authentication credentials through the `DOCKER_USER` and `DOCKER_PASSWORD` [configuration variables](#available-cicd-variables). For more details on how to use these variables, see [authenticate to a remote registry](#authenticate-to-a-remote-registry). +- GitLab CI/CD pipeline must include the `test` stage, which is available unless overridden with the [`stages`](../../../ci/yaml/index.md#stages) keyword. ## Configuration diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index b35c2ed79cf..89b4cdcc34d 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -7,14 +7,14 @@ type: reference, howto # Coverage-guided fuzz testing **(ULTIMATE)** -Coverage-guided fuzzing sends random inputs to an instrumented version of your application in an -effort to cause unexpected behavior. Such behavior indicates a bug that you should address. +Coverage-guided fuzz testing sends random inputs to an instrumented version of your application in +an effort to cause unexpected behavior. Such behavior indicates a bug that you should address. GitLab allows you to add coverage-guided fuzz testing to your pipelines. This helps you discover bugs and potential security issues that other QA processes may miss. We recommend that you use fuzz testing in addition to the other security scanners in [GitLab Secure](../index.md) and your own test processes. If you're using [GitLab CI/CD](../../../ci/index.md), -you can run your coverage-guided fuzz tests as part your CI/CD workflow. +you can run your coverage-guided fuzz testing as part your CI/CD workflow. ## Coverage-guided fuzz testing process @@ -30,30 +30,40 @@ The results of the coverage-guided fuzz testing are available in the CI/CD pipel ## Supported fuzzing engines and languages -GitLab supports these languages through the fuzzing engine listed for each. We currently provide a -Docker image for apps written in Go, but you can test the other languages below by providing a -Docker image with the fuzz engine to run your app. - -| Language | Fuzzing Engine | Example | -|----------|----------------|---------| -| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | -| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | -| Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | -| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | -| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | -| Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | -| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz)| [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | -| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz)| [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | -| AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/)| [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | +You can use the following fuzzing engines to test the specified languages. + +| Language | Fuzzing Engine | Example | +|---------------------------------------------|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/c-cpp-fuzzing-example) | +| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | [go-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example) | +| Swift | [libFuzzer](https://github.com/apple/swift/blob/master/docs/libFuzzerIntegration.md) | [swift-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/swift-fuzzing-example) | +| Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | [rust-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/rust-fuzzing-example) | +| Java | [Javafuzz](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/javafuzz) (recommended) | [javafuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/javafuzz-fuzzing-example) | +| Java | [JQF](https://github.com/rohanpadhye/JQF) (not preferred) | [jqf-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/java-fuzzing-example) | +| JavaScript | [`jsfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/jsfuzz) | [jsfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/jsfuzz-fuzzing-example) | +| Python | [`pythonfuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/fuzzers/pythonfuzz) | [pythonfuzz-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/pythonfuzz-fuzzing-example) | +| AFL (any language that works on top of AFL) | [AFL](https://lcamtuf.coredump.cx/afl/) | [afl-fuzzing-example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/afl-fuzzing-example) | ## Configuration -To enable fuzzing, you must -[include](../../../ci/yaml/index.md#includetemplate) -the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) -provided as part of your GitLab installation. +To enable coverage-guided fuzz testing, edit the `.gitlab-ci.yml` file: + +1. Add the `fuzz` stage to the list of stages. + +1. If your application is not written in Go, [provide a Docker image](../../../ci/yaml/index.md#image) using the matching fuzzing + engine. For example: + + ```yaml + image: python:latest + ``` + +1. [Include](../../../ci/yaml/index.md#includetemplate) the + [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml) + provided as part of your GitLab installation. -To do so, add the following to your `.gitlab-ci.yml` file: +1. Customize the `my_fuzz_target` job to meet your requirements. + +### Example extract of coverage-guided fuzzing configuration ```yaml stages: @@ -65,96 +75,62 @@ include: my_fuzz_target: extends: .fuzz_base script: - # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz> + # Build your fuzz target binary in these steps, then run it with gitlab-cov-fuzz # See our example repos for how you could do this with any of our supported languages - ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target> ``` -The included template makes available the [hidden job](../../../ci/jobs/index.md#hide-jobs) -`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzz -targets. Each fuzz target **must** have a separate job. For example, the +The `Coverage-Fuzzing` template includes the [hidden job](../../../ci/jobs/index.md#hide-jobs) +`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzzing +targets. Each fuzzing target **must** have a separate job. For example, the [go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example) -contains one job that extends `.fuzz_base` for its single fuzz target. +contains one job that extends `.fuzz_base` for its single fuzzing target. Note that the hidden job `.fuzz_base` uses several YAML keys that you must not override in your own -job. If you include these keys in your own job, you must copy their original content. These keys -are: +job. If you include these keys in your own job, you must copy their original content: - `before_script` - `artifacts` - `rules` -The `my_fuzz_target` job (the separate job for your fuzz target) does the following: +### Available CI/CD variables + +Use the following variables to configure coverage-guided fuzz testing in your CI/CD pipeline. -- Extends `.fuzz_base`. -- Compiles the fuzz target with [go-fuzz](https://github.com/dvyukov/go-fuzz). -- Runs the target with the `gitlab-cov-fuzz` command, which is available to each job that extends - `.fuzz_base`. -- Runs on a fuzz stage that usually comes after a test stage. +| CI/CD variable | Description | +|---------------------------|---------------------------------------------------------------------------------| +| `COVFUZZ_ADDITIONAL_ARGS` | Arguments passed to `gitlab-cov-fuzz`. Used to customize the behavior of the underlying fuzzing engine. Read the fuzzing engine's documentation for a complete list of arguments. | +| `COVFUZZ_BRANCH` | The branch on which long-running fuzzing jobs are to be run. On all other branches, only fuzzing regression tests are run. Default: Repository's default branch. | +| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. Default: empty. | +| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this value when using an offline environment. Default: `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | -The `gitlab-cov-fuzz` is a command-line tool that runs the instrumented application. It parses and -analyzes the exception information that the fuzzer outputs. It also downloads the [corpus](../terminology/index.md#corpus) -and crash events from previous pipelines automatically. This helps your fuzz targets build on the -progress of previous fuzzing jobs. The parsed crash events and data are written to -`gl-coverage-fuzzing-report.json`. +#### Seed corpus -### Artifacts +Files in the [seed corpus](../terminology/index.md#seed-corpus) must be updated manually. They are +not updated or overwritten by the coverage-guide fuzz testing job. + +## Output Each fuzzing step outputs these artifacts: -- `gl-coverage-fuzzing-report.json`: This file's format may change in future releases. +- `gl-coverage-fuzzing-report.json`: A report containing details of the coverage-guided fuzz testing + and its results. - `artifacts.zip`: This file contains two directories: - - `corpus`: Holds all test cases generated by the current and all previous jobs. - - `crashes`: Holds all crash events the current job encountered as well as those not fixed in + - `corpus`: Contains all test cases generated by the current and all previous jobs. + - `crashes`: Contains all crash events the current job found and those not fixed in previous jobs. -### Types of fuzzing jobs - -There are two types of jobs: - -- Fuzzing: Standard fuzzing session. You can configure a long session through a user defined - timeout. -- Regression: Run the fuzz targets through the accumulated test cases generated by previous fuzzing - sessions plus fixed crashes from previous sessions. This is usually very quick. - -Here's our current suggestion for configuring your fuzz target's timeout: - -- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (asynchronous) fuzzing - jobs. This is normally the default branch. -- Use regression or short-running fuzzing jobs for other branches or merge requests. - -This suggestion helps find new bugs on the development branch and catch old bugs in merge requests -(like unit tests). - -You can configure this by passing `--regression=false/true` to `gitlab-cov-fuzz` as the [Go example](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example/-/blob/master/.gitlab-ci.yml) -shows. Also note that `gitlab-cov-fuzz` is a wrapper, so you can pass those arguments to configure -any option available in the underlying fuzzing engine. - -### Available CI/CD variables - -| CI/CD variable | Description | -|-----------------------|--------------------------------------------------------------------------------| -| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. This is normally the default branch. | -| `COVFUZZ_SEED_CORPUS` | Path to a seed corpus directory. The default is empty. | -| `COVFUZZ_URL_PREFIX` | Path to the `gitlab-cov-fuzz` repository cloned for use with an offline environment. You should only change this when using an offline environment. The default value is `https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz/-/raw`. | - -The files in the [seed corpus](../terminology/index.md#seed-corpus) (`COVFUZZ_SEED_CORPUS`), if provided, aren't updated unless you commit new -files to your Git repository. There's usually no need to frequently update the seed corpus. As part -of the GitLab artifacts system, GitLab saves in a corpus directory the new test cases that every run -generates. In any subsequent runs, GitLab also reuses the generated corpus together with the seed -corpus. +You can download the JSON report file from the CI/CD pipelines page. For more information, see +[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). -### Reports JSON format +### Coverage-guided fuzz testing report > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in GitLab 13.3 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). -The `gitlab-cov-fuzz` tool emits a JSON report file. For more information, see the -[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). - -You can download the JSON report file from the CI pipelines page. For more information, see -[Downloading artifacts](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). +For detailed information about the `gl-coverage-fuzzing-report.json` file's format, read the +[schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/coverage-fuzzing-report-format.json). -Here's an example coverage fuzzing report: +Example coverage-guided fuzzing report: ```json-doc { @@ -183,38 +159,30 @@ Here's an example coverage fuzzing report: } ``` -### Additional configuration - -The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying fuzzing engine. You -can therefore use all the options available in that fuzzing engine. For more information on these -options, see the underlying fuzzing engine's documentation. - -### Offline environment +## Duration of coverage-guided fuzz testing -To use coverage fuzzing in an offline environment, follow these steps: +The available durations for coverage-guided fuzz testing are: 10 minutes (default) and 60 minutes. -1. Clone [`gitlab-cov-fuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz) - to a private repository that your offline GitLab instance can access. +- 10-minute duration: Recommended for the default branch. +- 60-minute duration: Recommended for the development branch and merge requests. The longer duration provides greater coverage. + In the `COVFUZZ_ADDITIONAL_ARGS` variable set the value `--regression=true`. -1. For each fuzzing step, set `COVFUZZ_URL_PREFIX` to `${NEW_URL_GITLAB_COV_FUZ}/-/raw`, where - `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the - first step. +For a complete example, read the [Go coverage-guided fuzzing example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/blob/master/.gitlab-ci.yml). -### Continuous fuzzing (long-running asynchronous fuzzing jobs) +### Continuous coverage-guided fuzz testing -It's also possible to run the fuzzing jobs longer and without blocking your main pipeline. This -configuration uses the GitLab [parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md). -The full example is available in the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing#running-go-fuzz-from-ci). -This example uses Go, but is applicable for any other supported languages. +It's also possible to run the coverage-guided fuzzing jobs longer and without blocking your main +pipeline. This configuration uses the GitLab +[parent-child pipelines](../../../ci/pipelines/parent_child_pipelines.md). -The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on a -main/development branch, and short, blocking sync fuzzing jobs on all other branches and MRs. This -is a good way to balance the needs of letting a developer's per-commit pipeline complete quickly, -and also giving the fuzzer a large amount of time to fully explore and test the app. +The suggested workflow in this scenario is to have long-running, asynchronous fuzzing jobs on the +main or development branch, and short synchronous fuzzing jobs on all other branches and MRs. This +balances the needs of completing the per-commit pipeline complete quickly, while also giving the +fuzzer a large amount of time to fully explore and test the app. Long-running fuzzing jobs are +usually necessary for the coverage-guided fuzzer to find deeper bugs in your codebase. -Long-running fuzzing jobs are usually necessary for the coverage guided fuzzer to find deeper bugs -in your latest codebase. The following is an example of what `.gitlab-ci.yml` looks like in this -workflow (for the full example, see the [repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing)): +The following is an extract of the `.gitlab-ci.yml` file for this +workflow. For the full example, see the [Go fuzzing example's repository](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example/-/tree/continuous_fuzzing): ```yaml @@ -236,7 +204,7 @@ async_fuzzing: - if: $CI_COMMIT_BRANCH == 'continuous_fuzzing' && $CI_PIPELINE_SOURCE != 'merge_request_event' ``` -This essentially creates two steps: +This creates two jobs: 1. `sync_fuzzing`: Runs all your fuzz targets for a short period of time in a blocking configuration. This finds simple bugs and allows you to be confident that your MRs aren't @@ -246,6 +214,17 @@ This essentially creates two steps: The `covfuzz-ci.yml` is the same as that in the [original synchronous example](https://gitlab.com/gitlab-org/security-products/demos/coverage-fuzzing/go-fuzzing-example#running-go-fuzz-from-ci). +## Offline environment + +To use coverage fuzzing in an offline environment: + +1. Clone [`gitlab-cov-fuzz`](https://gitlab.com/gitlab-org/security-products/analyzers/gitlab-cov-fuzz) + to a private repository that your offline GitLab instance can access. + +1. For each fuzzing step, set `COVFUZZ_URL_PREFIX` to `${NEW_URL_GITLAB_COV_FUZ}/-/raw`, where + `NEW_URL_GITLAB_COV_FUZ` is the URL of the private `gitlab-cov-fuzz` clone that you set up in the + first step. + ## Interacting with the vulnerabilities After a vulnerability is found, you can [address it](../vulnerabilities/index.md). diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 4de7a566769..aeaa93f4a85 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -16,10 +16,6 @@ Dynamic Application Security Testing (DAST) examines applications for vulnerabilities like these in deployed environments. DAST uses the open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.org/) for analysis. -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dast-docs). - After DAST creates its report, GitLab evaluates it for discovered vulnerabilities between the source and target branches. Relevant findings are noted in the merge request. @@ -57,6 +53,7 @@ results. On failure, the analyzer outputs an - [GitLab Runner](../../../ci/runners/index.md) available, with the [`docker` executor](https://docs.gitlab.com/runner/executors/docker.html). - Target application deployed. For more details, read [Deployment options](#deployment-options). +- DAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. ### Deployment options @@ -638,7 +635,7 @@ These CI/CD variables are specific to DAST. They can be used to customize the be | `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | | `DAST_WEBSITE` <sup>1</sup> | URL | The URL of the website to scan. The variable `DAST_API_OPENAPI` must be specified if this is omitted. | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12652) in GitLab 13.1. | -| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `log4j.logger.org.parosproxy.paros.network.HttpSender=DEBUG;log4j.logger.com.crawljax=DEBUG` | +| `DAST_ZAP_LOG_CONFIGURATION` | string | Set to a semicolon-separated list of additional log4j properties for the ZAP Server. Example: `logger.httpsender.name=org.parosproxy.paros.network.HttpSender;logger.httpsender.level=debug;logger.sitemap.name=org.parosproxy.paros.model.SiteMap;logger.sitemap.level=debug;` | | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | 1. Available to an on-demand DAST scan. @@ -969,6 +966,8 @@ To view running completed and scheduled on-demand DAST scans for a project, go t failed, or was canceled. - To view scheduled scans, select **Scheduled**. It shows on-demand scans that have a schedule set up. Those are _not_ included in the **All** tab. +- To view saved on-demand scan profiles, select **Scan library**. + Those are _not_ included in the **All** tab. #### Cancel an on-demand scan @@ -1036,10 +1035,8 @@ The on-demand DAST scan runs and the project's dashboard shows the results. To run a saved on-demand scan: 1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. In the **DAST Profiles** row, select **Manage**. -1. Select the **Saved Scans** tab. +1. On the left sidebar, select **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the scan's row, select **Run scan**. If the branch saved in the scan no longer exists, you must first @@ -1075,27 +1072,23 @@ To schedule a scan: To list saved on-demand scans: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. #### View details of an on-demand scan To view details of an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. #### Edit an on-demand scan To edit an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Edit**. 1. Edit the form. 1. Select **Save scan**. @@ -1104,10 +1097,8 @@ To edit an on-demand scan: To delete an on-demand scan: -1. From your project's home page, go to **Security & Compliance > Configuration**. -1. Select **Manage DAST scans**. -1. Select **Manage** in the **DAST Profiles** row. -1. Select the **Saved Scans** tab. +1. From your project's home page, go to **Security & Compliance > On-demand Scans**. +1. Select the **Scan library** tab. 1. In the saved scan's row select **More actions** (**{ellipsis_v}**), then select **Delete**. 1. Select **Delete** to confirm the deletion. @@ -1132,6 +1123,9 @@ A site profile contains the following: When an API site type is selected, a [host override](#host-override) is used to ensure the API being scanned is on the same host as the target. This is done to reduce the risk of running an active scan against the wrong API. +When configured, request headers and password fields are encrypted using [`aes-256-gcm`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) before being stored in the database. +This data can only be read and decrypted with a valid secrets file. + #### Site profile validation > - Site profile validation [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/233020) in GitLab 13.8. diff --git a/doc/user/application_security/dast_api/index.md b/doc/user/application_security/dast_api/index.md index 0db5fb2d868..f1eba505589 100644 --- a/doc/user/application_security/dast_api/index.md +++ b/doc/user/application_security/dast_api/index.md @@ -214,7 +214,7 @@ target API to test: DAST_API_PROFILE: Quick ``` -1. Provide the location of the HAR specification. You can provide the specification as a file +1. Provide the location of the HAR file. You can provide the location as a file path or URL. [URL support was introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285020) in GitLab 13.10 and later. Specify the location by adding the `DAST_API_HAR` variable: ```yaml @@ -314,7 +314,7 @@ information about the target API to test: DAST_API_PROFILE: Quick ``` -1. Provide the location of the Postman Collection specification. You can provide the specification as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: +1. Provide the location of the Postman Collection file. You can provide the location as a file or URL. Specify the location by adding the `DAST_API_POSTMAN_COLLECTION` variable: ```yaml stages: @@ -637,6 +637,7 @@ can be added, removed, and modified by creating a custom configuration. |[`DAST_API_PROFILE`](#configuration-files) | Configuration profile to use during testing. Defaults to `Quick`. | |[`DAST_API_EXCLUDE_PATHS`](#exclude-paths) | Exclude API URL paths from testing. | |[`DAST_API_OPENAPI`](#openapi-specification) | OpenAPI specification file or URL. | +|[`DAST_API_OPENAPI_RELAXED_VALIDATION`](#openapi-specification) | Relax document validation. Default is disabled. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345950) in GitLab 14.7. | |[`DAST_API_HAR`](#http-archive-har) | HTTP Archive (HAR) file. | |[`DAST_API_POSTMAN_COLLECTION`](#postman-collection) | Postman Collection file. | |[`DAST_API_POSTMAN_COLLECTION_VARIABLES`](#postman-variables) | Path to a JSON file to extract postman variable values. | @@ -1209,6 +1210,41 @@ deploy-test-target: - environment_url.txt ``` +### Use OpenAPI with an invalid schema + +There are cases where the document is autogenerated with an invalid schema or cannot be edited manually in a timely manner. In those scenarios, the API Security is able to perform a relaxed validation by setting the variable `DAST_API_OPENAPI_RELAXED_VALIDATION`. We recommend providing a fully compliant OpenAPI document to prevent unexpected behaviors. + +#### Edit a non-compliant OpenAPI file + +To detect and correct elements that don't comply with the OpenAPI specifications, we recommend using an editor. An editor commonly provides document validation, and suggestions to create a schema-compliant OpenAPI document. Suggested editors include: + +| Editor | OpenAPI 2.0 | OpenAPI 3.0.x | OpenAPI 3.1.x | +| -- | -- | -- | -- | +| [Swagger Editor](https://editor.swagger.io/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{dotted-circle}** YAML, JSON | +| [Stoplight Studio](https://stoplight.io/studio/) | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | **{check-circle}** YAML, JSON | + +If your OpenAPI document is generated manually, load your document in the editor and fix anything that is non-compliant. If your document is generated automatically, load it in your editor to identify the issues in the schema, then go to the application and perform the corrections based on the framework you are using. + +#### Enable OpenAPI relaxed validation + +Relaxed validation is meant for cases when the OpenAPI document cannot meet OpenAPI specifications, but it still has enough content to be consumed by different tools. A validation is performed but less strictly in regards to document schema. + +API Security can still try to consume an OpenAPI document that does not fully comply with OpenAPI specifications. To instruct API Security to perform a relaxed validation, set the variable `DAST_API_OPENAPI_RELAXED_VALIDATION` to any value, for example: + +```yaml + stages: + - dast + + include: + - template: DAST-API.gitlab-ci.yml + + variables: + DAST_API_PROFILE: Quick + DAST_API_TARGET_URL: http://test-deployment/ + DAST_API_OPENAPI: test-api-specification.json + DAST_API_OPENAPI_RELAXED_VALIDATION: On +``` + ## Get support or request an improvement To get support for your particular problem please use the [getting help channels](https://about.gitlab.com/get-help/). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 192d8449297..a8cc33d5545 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -7,10 +7,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning **(ULTIMATE)** -INFO: -Try out Dependency Scanning in GitLab Ultimate. -[It's free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-dependency-scanning-docs). - The Dependency Scanning feature can automatically find security vulnerabilities in your software dependencies while you're developing and testing your applications. For example, dependency scanning lets you know if your application uses an external (open source) @@ -67,6 +63,9 @@ vulnerability. ## Requirements +Dependency Scanning runs in the `test` stage, which is available by default. If you redefine the +stages in the `.gitlab-ci.yml` file, the `test` stage is required. + To run dependency scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -922,6 +921,8 @@ gemnasium-dependency_scanning: ## Warnings +We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes. + ### Python projects Extra care needs to be taken when using the [`PIP_EXTRA_INDEX_URL`](https://pipenv.pypa.io/en/latest/cli/#envvar-PIP_EXTRA_INDEX_URL) diff --git a/doc/user/application_security/iac_scanning/index.md b/doc/user/application_security/iac_scanning/index.md index c17ebc68b4d..4d5c1da3c47 100644 --- a/doc/user/application_security/iac_scanning/index.md +++ b/doc/user/application_security/iac_scanning/index.md @@ -14,6 +14,8 @@ Currently, IaC scanning supports configuration files for Terraform, Ansible, AWS ## Requirements +IaC Scanning runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. + To run IaC scanning jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -48,7 +50,7 @@ as shown in the following table: | Capability | In Free | In Ultimate | |:---------------------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure IaC Scanners](#configuration) v | **{check-circle}** | **{check-circle}** | +| [Configure IaC Scanners](#configuration) | **{check-circle}** | **{check-circle}** | | View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | | Presentation of JSON Report in Merge Request | **{dotted-circle}** | **{check-circle}** | | [Address vulnerabilities](../../application_security/vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 5500f5a10c4..f5c727a1418 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -16,10 +16,6 @@ GitLab can check your application for security vulnerabilities including: Statistics and details on vulnerabilities are included in the merge request. Providing actionable information _before_ changes are merged enables you to be proactive. -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-application-security-docs). - GitLab also provides high-level statistics of vulnerabilities across projects and groups: - The [Security Dashboard](security_dashboard/index.md) provides a @@ -119,7 +115,9 @@ rules: If you add the security scanning jobs as described in [Security scanning with Auto DevOps](#security-scanning-with-auto-devops) or [Security scanning without Auto DevOps](#security-scanning-without-auto-devops) to your `.gitlab-ci.yml` each added [security scanning tool](#security-scanning-tools) behave as described below. -For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) that rely on this scan data only show results from pipelines on the default branch. One tool might use many analyzers. +For each compatible analyzer, a job is created in the `test`, `dast` or `fuzz` stage of your pipeline and runs on the next new branch pipeline. +Features such as the [Security Dashboard](security_dashboard/index.md), [Vulnerability Report](vulnerability_report/index.md), and [Dependency List](dependency_list/index.md) +that rely on this scan data only show results from pipelines on the default branch, only if all jobs are finished, including manual ones. One tool might use many analyzers. Our language and package manager specific jobs attempt to assess which analyzer(s) they should run for your project so that you can do less configuration. @@ -172,7 +170,7 @@ From the merge request security widget, select **Expand** to unfold the widget, A pipeline's security tab lists all findings in the current branch. It includes new findings introduced by this branch and existing vulnerabilities that were already present when the branch was created. These results likely do not match the findings displayed in the Merge Request security widget as those do not include the existing vulnerabilities (with the exception of showing any existing vulnerabilities that are no longer detected in the feature branch). -For more details, see [security tab](security_dashboard/index.md#pipeline-security). +For more details, see [security tab](security_dashboard/index.md#view-vulnerabilities-in-a-pipeline). ## View security scan information in the Security Dashboard @@ -406,9 +404,9 @@ sast: You can interact with the results of the security scanning tools in several locations: - [Scan information in merge requests](#view-security-scan-information-in-merge-requests) -- [Project Security Dashboard](security_dashboard/#project-security-dashboard) -- [Security pipeline tab](security_dashboard/#pipeline-security) -- [Group Security Dashboard](security_dashboard/#group-security-dashboard) +- [Project Security Dashboard](security_dashboard/index.md) +- [Security pipeline tab](security_dashboard/index.md) +- [Group Security Dashboard](security_dashboard/index.md) - [Security Center](security_dashboard/#security-center) - [Vulnerability Report](vulnerability_report/index.md) - [Vulnerability Pages](vulnerabilities/index.md) @@ -441,6 +439,46 @@ When customizing the configuration: version contains the most recent changes, but may have significant changes between minor GitLab versions. - Only override values in the template as needed. All other values are inherited from the template. +### Enforce scan execution + +Security and compliance teams must ensure that security scans: + +- Run on a regular basis for all projects. +- Can't be disabled by developers. + +GitLab provides two methods of accomplishing this, each with advantages and disadvantages. + +- [Compliance framework pipelines](../project/settings/#compliance-pipeline-configuration) + are recommended when: + + - Scan execution enforcement is required for SAST IaC, Container Scanning, Dependency Scanning, + License Compliance, API Fuzzing, or Coverage-guided Fuzzing. + - Scan execution enforcement of SAST or Secret Detection when customization of the default scan + variables is required. + - Scan execution enforcement is required for scanners external to GitLab. + - Enforced execution is required for custom jobs other than security scans. + +- [Scan execution policies](policies/#scan-execution-policies) + are recommended when: + + - Scan execution enforcement is required for DAST. + - Scan execution enforcement is required for SAST or Secret Detection with the default scan + variables. + - Scans are required to run on a regular, scheduled cadence. + +Additional details about the differences between the two solutions are outlined below: + +| | Compliance Framework Pipelines | Scan Execution Policies | +| ------ | ------ | ------ | +| **Flexibility** | Supports anything that can be done in a CI file. | Limited to only the items for which GitLab has explicitly added support. DAST, SAST, and Secret Detection scans are supported. | +| **Usability** | Requires knowledge of CI YAML. | Follows a `rules` and `actions`-based YAML structure. | +| **Inclusion in CI pipeline** | The compliance pipeline is executed instead of the project's `gitlab-ci.yml` file. To include the project's `gitlab-ci.yml` file, use an `include` statement. Defined variables aren't allowed to be overwritten by the included project's YAML file. | Forced inclusion of a new job into the CI pipeline. DAST jobs that must be customized on a per-project basis can have project-level Site Profiles and Scan Profiles defined. To ensure separation of duties, these profiles are immutable when referenced in a scan execution policy. | +| **Schedulable** | Can be scheduled through a scheduled pipeline on the group. | Can be scheduled natively through the policy configuration itself. | +| **Separation of Duties** | Only group owners can create compliance framework labels. Only project owners can apply compliance framework labels to projects. The ability to make or approve changes to the compliance pipeline definition is limited to individuals who are explicitly given access to the project that contains the compliance pipeline. | Only project owners can define a linked security policy project. The ability to make or approve changes to security policies is limited to individuals who are explicitly given access to the security policy project. | +| **Ability to apply one standard to multiple projects** | The same compliance framework label can be applied to multiple projects inside a group. | The same security policy project can be used for multiple projects across GitLab with no requirement of being located in the same group. | + +Feedback is welcome on our vision for [unifying the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312) + ## Troubleshooting ### Secure job failing with exit code 1 @@ -609,3 +647,15 @@ such as changing `variables` or the `stage`, but they cannot be used to define s There [is an issue open to improve extendability](https://gitlab.com/gitlab-org/gitlab/-/issues/218444). Please upvote the issue to help with prioritization, and [contributions are welcomed](https://about.gitlab.com/community/contribute/). + +### Empty Vulnerability Report, Dependency List, License list pages + +If the pipeline has manual steps with a job that has the `allow_failure: false` option, and this job is not finished, +GitLab can't populate listed pages with the data from security reports. +In this case, [the Vulnerability Report](vulnerability_report/index.md), [the Dependency List](dependency_list/index.md), +and [the License list](../compliance/license_compliance/index.md#license-list) pages will be empty. +These security pages can be populated by running the jobs from the manual step of the pipeline. + +There is [an issue open to handle this scenario](https://gitlab.com/gitlab-org/gitlab/-/issues/346843). +Please upvote the issue to help with prioritization, and +[contributions are welcomed](https://about.gitlab.com/community/contribute/). diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png Binary files differdeleted file mode 100644 index d04905eda59..00000000000 --- a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_3.png +++ /dev/null diff --git a/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png Binary files differnew file mode 100644 index 00000000000..04768d2e18a --- /dev/null +++ b/doc/user/application_security/policies/img/scan_execution_policy_yaml_mode_v14_7.png diff --git a/doc/user/application_security/policies/index.md b/doc/user/application_security/policies/index.md index e6dbd96537f..11f2b91177a 100644 --- a/doc/user/application_security/policies/index.md +++ b/doc/user/application_security/policies/index.md @@ -236,20 +236,32 @@ Project owners can unlink Security Policy projects from development projects. To the steps described in [Security Policy project selection](#security-policy-project-selection), but select the trash can icon in the modal. +## Scan execution policies + +Project owners can use scan execution policies to require that security scans run on a specified +schedule or with the project pipeline. Required scans are injected into the CI pipeline as new jobs +with a long, random job name. In the unlikely event of a job name collision, the security policy job +overwrites any pre-existing job in the pipeline. + +This feature has some overlap with [compliance framework pipelines](../../project/settings/#compliance-pipeline-configuration), +as we have not [unified the user experience for these two features](https://gitlab.com/groups/gitlab-org/-/epics/7312). +For details on the similarities and differences between these features, see +[Enforce scan execution](../#enforce-scan-execution). + ### Scan Execution Policy editor NOTE: Only project Owners have the [permissions](../../permissions.md#project-members-permissions) to select Security Policy Project. -Once your policy is complete, save it by selecting **Create merge request** +Once your policy is complete, save it by selecting **Create via merge request** at the bottom of the editor. You are redirected to the merge request on the project's configured security policy project. If one does not link to your project, a security policy project is automatically created. Existing policies can also be removed from the editor interface by selecting **Delete policy** at the bottom of the editor. - + The policy editor currently only supports the YAML mode. The Rule mode is tracked in the [Allow Users to Edit Rule-mode Scan Execution Policies in the Policy UI](https://gitlab.com/groups/gitlab-org/-/epics/5363) epic. @@ -301,10 +313,10 @@ Use this schema to define `clusters` objects in the [`schedule` rule type](#sche | Field | Type | Possible values | Description | |--------------|---------------------|--------------------------|-------------| -| `containers` | `array` of `string` | | The container name to be scanned (only the first value is currently supported). | -| `resources` | `array` of `string` | | The resource name to be scanned (only the first value is currently supported). | -| `namespaces` | `array` of `string` | | The namespace to be scanned (only the first value is currently supported). | -| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind to be scanned (only the first value is currently supported). | +| `containers` | `array` of `string` | | The container name that is scanned (only the first value is currently supported). | +| `resources` | `array` of `string` | | The resource name that is scanned (only the first value is currently supported). | +| `namespaces` | `array` of `string` | | The namespace that is scanned (only the first value is currently supported). | +| `kinds` | `array` of `string` | `deployment`/`daemonset` | The resource kind that should be scanned (only the first value is currently supported). | ### `scan` action type @@ -389,7 +401,7 @@ scan_execution_policy: enabled: true rules: - type: schedule - cadence: "15 3 * * * + cadence: "15 3 * * *" clusters: production-cluster: containers: diff --git a/doc/user/application_security/sast/analyzers.md b/doc/user/application_security/sast/analyzers.md index 8c7e03f69fd..7529bf90ccf 100644 --- a/doc/user/application_security/sast/analyzers.md +++ b/doc/user/application_security/sast/analyzers.md @@ -6,8 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # SAST Analyzers **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. -> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. +> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) from GitLab Ultimate to GitLab Free in 13.3. SAST relies on underlying third party tools that are wrapped into what we call "Analyzers". An analyzer is a diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index fd05ecad8f2..de2f9af82c7 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -2,13 +2,11 @@ stage: Secure group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference, howto --- # Static Application Security Testing (SAST) **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in GitLab 10.3. -> - All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. +> All open source (OSS) analyzers were moved from GitLab Ultimate to GitLab Free in GitLab 13.3. NOTE: The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab.com/resources/whitepaper-seismic-shift-application-security/) @@ -51,6 +49,8 @@ the analyzer outputs an [exit code](../../../development/integrations/secure.md# ## Requirements +SAST runs in the `test` stage, which is available by default. If you redefine the stages in the `.gitlab-ci.yml` file, the `test` stage is required. + To run SAST jobs, by default, you need GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. @@ -168,10 +168,9 @@ To configure SAST for a project you can: ### Configure SAST manually -For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) +To enable SAST you must [include](../../../ci/yaml/index.md#includetemplate) the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml) -provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you -can copy and use the job as defined that template. +provided as a part of your GitLab installation. Add the following to your `.gitlab-ci.yml` file: @@ -269,7 +268,7 @@ versions are pulled, there are certain cases where it can be beneficial to pin an analyzer to a specific release. To do so, override the `SAST_ANALYZER_IMAGE_TAG` CI/CD variable in the job template directly. -In the example below, we pin to a specific patch version of the `spotbugs` analyzer and minor version of the `semgrep` analyzer: +In the example below, we pin to a minor version of the `semgrep` analyzer and a specific patch version of the `brakeman` analyzer: ```yaml include: @@ -277,11 +276,11 @@ include: semgrep-sast: variables: - SAST_ANALYZER_IMAGE_TAG: "2.12" + SAST_ANALYZER_IMAGE_TAG: "2.16" -spotbugs-sast: +brakeman-sast: variables: - SAST_ANALYZER_IMAGE_TAG: "2.28.1" + SAST_ANALYZER_IMAGE_TAG: "2.21.1" ``` ### Customize rulesets **(ULTIMATE)** @@ -311,9 +310,9 @@ To disable analyzer rules: 1. Set the `disabled` flag to `true` in the context of a `ruleset` section -1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: +1. In one or more `ruleset.identifier` sub sections, list the rules that you want disabled. Every `ruleset.identifier` section has: -- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. +- a `type` field, to name the predefined rule identifier that the targeted analyzer uses. - a `value` field, to name the rule to be disabled. @@ -346,7 +345,7 @@ and `sobelow` by matching the `type` and `value` of identifiers: #### Synthesize a custom configuration -To create a custom configuration, you can use passthrough chains. +To create a custom configuration, you can use passthrough chains. A passthrough is a single step in a passthrough chain. The passthrough is evaluated in a sequence to incrementally build a configuration. The configuration is then @@ -360,8 +359,8 @@ parameters: | `description` | Description about the analyzer configuration section. | | `targetdir` | The `targetdir` parameter defines the directory where the final configuration is located. If `targetdir` is empty, the analyzer uses a random directory. The maximum size of `targetdir` is 100MB. | | `validate` | If set to `true`, the target files for passthroughs (`raw`, `file` and `url`) are validated. The validation works for `yaml`, `xml`, `json` and `toml` files. The proper validator is identified based on the extension of the target file. By default, `validate` is set to `false`. | -| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | -| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | +| `interpolate` | If set to `true`, environment variable interpolation is enabled so that the configuration uses secrets/tokens. We advise using this feature with caution to not leak any secrets. By default, `interpolate` is set to `false`. | +| `timeout` | The total `timeout` for the evaluation of a passthrough chain is set to 60 seconds. If `timeout` is not set, the default timeout is 60 seconds. The timeout cannot exceed 300 seconds. | A configuration section can include one or more passthrough sections. The maximum number of passthrough sections is 20. There are several types of passthroughs: @@ -374,12 +373,12 @@ There are several types of passthroughs: | `url` | Fetch the analyzer configuration through HTTP. | If multiple passthrough sections are defined in a passthrough chain, their -position in the chain defines the order in which they are evaluated. +position in the chain defines the order in which they are evaluated. -- Passthroughs listed later in the chain sequence have a higher precedence. +- Passthroughs listed later in the chain sequence have a higher precedence. - Passthroughs with a higher precedence overwrite (default) and append data yielded by previous passthroughs. This is useful for cases where you need to - use or modify an existing configuration. + use or modify an existing configuration. Configure a passthrough these parameters: @@ -454,7 +453,7 @@ file `gosec-config.json`: ##### Passthrough chain for semgrep In the below example, we generate a custom configuration under the `/sgrules` -target directory with a total `timeout` of 60 seconds. +target directory with a total `timeout` of 60 seconds. Several passthrouh types generate a configuration for the target analyzer: @@ -463,17 +462,17 @@ Several passthrouh types generate a configuration for the target analyzer: `97f7686` from the `sast-rules` Git repostory. From the `sast-rules` Git repository, only data from the `go` subdirectory is considered. - The `sast-rules` entry has a higher precedence because it appears later in - the configuration. + the configuration. - If there is a filename collision between files in both repositories, files from the `sast` repository overwrite files from the `myrules` repository, as `sast-rules` has higher precedence. - The `raw` entry creates a file named `insecure.yml` under `/sgrules`. The - full path is `/sgrules/insecure.yml`. + full path is `/sgrules/insecure.yml`. - The `url` entry fetches a configuration made available through a URL and - stores it in the `/sgrules/gosec.yml` file. + stores it in the `/sgrules/gosec.yml` file. Afterwards, semgrep is invoked with the final configuration located under -`/sgrules`. +`/sgrules`. ```toml [semgrep] @@ -537,17 +536,17 @@ It does not explicitly store credentials in the configuration file. To reduce th ##### Configure the append mode for passthroughs To append data to previous passthroughs, use the `append` mode for the -passthrough types `file`, `url`, and `raw`. +passthrough types `file`, `url`, and `raw`. Passthroughs in `override` mode overwrite files created when preceding passthroughs in the chain find a naming collision. If `mode` is set to `append`, a passthrough appends data to the -files created by its predecessors instead of overwriting. +files created by its predecessors instead of overwriting. In the below semgrep configuration,`/sgrules/insecure.yml` assembles two passthroughs. The rules are: - `insecure` -- `secret` +- `secret` These rules add a search pattern to the analyzer and extends semgrep capabilities. @@ -1057,6 +1056,12 @@ For Maven builds, add the following to your `pom.xml` file: </properties> ``` +### SpotBugs Error: `Project couldn't be built` + +If your job is failing at the build step with the message "Project couldn't be built", it's most likely because your job is asking SpotBugs to build with a tool that isn't part of its default tools. For a list of the SpotBugs default tools, see [SpotBugs' asdf dependencies](https://gitlab.com/gitlab-org/security-products/analyzers/spotbugs/-/raw/master/config/.tool-versions). + +The solution is to use [pre-compilation](#pre-compilation). Pre-compilation ensures the images required by SpotBugs are available in the job's container. + ### Flawfinder encoding error This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature. diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index b5e54e35e58..c5761a5743f 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -1,5 +1,4 @@ --- -type: reference, howto stage: Secure group: Static Analysis info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments @@ -7,38 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Secret Detection **(FREE)** -> - [Introduced](https://about.gitlab.com/releases/2019/03/22/gitlab-11-9-released/#detect-secrets-and-credentials-in-the-repository) in GitLab 11.9. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. +> [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/222788) from GitLab Ultimate to GitLab Free in 13.3. -A recurring problem when developing applications is that developers may unintentionally commit -secrets and credentials to their remote repositories. If other people have access to the source, -or if the project is public, the sensitive information is then exposed and can be leveraged by -malicious users to gain access to resources like deployment environments. +A recurring problem when developing applications is that people may accidentally commit secrets to +their remote Git repositories. Secrets include keys, passwords, API tokens, and other sensitive +information. Anyone with access to the repository could use the secrets for malicious purposes. +Secrets exposed in this way must be treated as compromised, and be replaced, which can be costly. +It's important to prevent secrets from being committed to a Git repository. -GitLab 11.9 includes a new check called Secret Detection. It scans the content of the repository -to find API keys and other information that should not be there. +Secret Detection uses the [Gitleaks](https://github.com/zricethezav/gitleaks) tool to scan the +repository for secrets. All identified secrets are reported in the: -GitLab displays identified secrets visibly in a few places: - -- [Security Dashboard](../security_dashboard/) +- Merge request widget - Pipelines' **Security** tab -- Report in the merge request widget +- [Security Dashboard](../security_dashboard/)  -## Use cases - -- Detecting unintentional commit of secrets like keys, passwords, and API tokens. -- Performing a single or recurring scan of the full history of your repository for secrets. - -## Supported secrets +WARNING: +Secret Detection does not support scanning binary files. -Secret Detection detects a variety of common secrets by default. You can also customize the secret detection patterns using [custom rulesets](#custom-rulesets). -The [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) includes **90+ secret detection patterns**. -You can contribute "well-identifiable" secrets by follow the steps detailed in the [community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). +## Detected secrets -WARNING: -Gitleaks does not support scanning binary files. +Secret Detection uses a [default ruleset](https://gitlab.com/gitlab-org/security-products/analyzers/secrets/-/blob/master/gitleaks.toml) +containing more than 90 secret detection patterns. You can also customize the secret detection +patterns using [custom rulesets](#custom-rulesets). If you want to contribute rulesets for +"well-identifiable" secrets, follow the steps detailed in the +[community contributions guidelines](https://gitlab.com/gitlab-org/gitlab/-/issues/345453). ## Requirements @@ -376,10 +370,10 @@ For information on this, see the [general Application Security troubleshooting s ### Error: `Couldn't run the gitleaks command: exit status 2` -If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable -is set to 50 (a [project default](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone)), -the Secret Detection job fails as the clone is not deep enough to contain all of the -relevant commits. +If a pipeline is triggered from a Merge Request containing 60 commits while the `GIT_DEPTH` variable's +value is less than that, the Secret Detection job fails as the clone is not deep enough to contain all of the +relevant commits. For information on the current default value, see the +[pipeline configuration documentation](../../../ci/pipelines/settings.md#limit-the-number-of-changes-fetched-during-clone). To confirm this as the cause of the error, set the [logging level](../../application_security/secret_detection/index.md#logging-level) to `debug`, then diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png Binary files differdeleted file mode 100644 index 4d51f57a98d..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png b/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png Binary files differdeleted file mode 100644 index ad9122ee23c..00000000000 --- a/doc/user/application_security/security_dashboard/img/pipeline_security_dashboard_v14_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png Binary files differdeleted file mode 100644 index cc9f0061a31..00000000000 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard_chart_v13_11.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png b/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png Binary files differdeleted file mode 100644 index 6578c0bf4cf..00000000000 --- a/doc/user/application_security/security_dashboard/img/security_center_settings_v13_4.png +++ /dev/null diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 5afbe1ca54e..937ca33c3a1 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -7,193 +7,186 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboards and Security Center **(ULTIMATE)** -INFO: -Want to try out security scanning? -[Try GitLab Ultimate free for 30 days](https://about.gitlab.com/free-trial/index.html?glm_source=docs.gitlab.com&glm_content=u-security-dashboard-docs). +You can use Security Dashboards to view details about vulnerabilities +detected by [security scanners](../index.md#security-scanning-tools). +These details are shown in pipelines, projects, and groups. -GitLab provides a comprehensive set of features for viewing and managing vulnerabilities: +To use the Security Dashboards, you must: -- Security dashboards: An overview of the security status in your personal [Security Center](#security-center), [groups](#group-security-dashboard), and - [projects](#project-security-dashboard). -- [Vulnerability reports](../vulnerability_report/index.md): Detailed lists of all vulnerabilities for the Security Center, group, project, or - pipeline. This is where you triage and manage vulnerabilities. -- [Security Center](#security-center): A dedicated area for personalized vulnerability management. This - includes a security dashboard, vulnerability report, and settings. +- Configure at least one [security scanner](../index.md#security-scanning-tools) in a project. +- Configure jobs to use the [`reports` syntax](../../../ci/yaml/index.md#artifactsreports). +- Use [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or later. If you use the + shared runners on GitLab.com, you are using the correct version. -You can also drill down into a vulnerability and get extra information on the -[Vulnerability Page](../vulnerabilities/index.md). This view includes the project it -comes from, any related file(s), and metadata that helps you analyze the risk it poses. -You can also confirm, dismiss, or resolve a vulnerability, create an issue for it, -and in some cases, generate a merge request to fix the vulnerability. +## When Security Dashboards are updated -To benefit from these features, you must first configure one of the -[security scanners](../index.md). +The Security Dashboards show results of the most recent security scan on the +[default branch](../../project/repository/branches/default.md). +Security scans run only when the default branch updates, so +information on the Security Dashboard might not reflect newly-discovered vulnerabilities. -## Supported reports +To run a daily security scan, +[configure a scheduled pipeline](../../../ci/pipelines/schedules.md). -The security dashboard and vulnerability report displays information about vulnerabilities detected by scanners such as: +## Reduce false negatives in dependency scans -- [Container Scanning](../container_scanning/index.md) -- [Dynamic Application Security Testing](../dast/index.md) -- [Dependency Scanning](../dependency_scanning/index.md) -- [Static Application Security Testing](../sast/index.md) -- [Cluster Image Scanning](../cluster_image_scanning/index.md) -- And [others](../index.md#security-scanning-tools)! +WARNING: +False negatives occur when you resolve dependency versions during a scan, which differ from those +resolved when your project built and released in a previous pipeline. -## Prerequisites +To reduce false negatives in [dependency scans](../../../user/application_security/dependency_scanning/index.md) in scheduled pipelines, ensure you: -1. At least one project inside a group must be configured with at least one of - the [supported reports](#supported-reports). -1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/index.md#artifactsreports). -1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used. - If you're using the shared runners on GitLab.com, this is already the case. +- Include a lock file in your project. A lock file lists all transient dependencies and tracks their versions. + - Java projects can't have lock files. + - Python projects can have lock files, but GitLab Secure tools don't support them. +- Configure your project for [Continuous Delivery](../../../ci/introduction/index.md). -## Pipeline Security +## View vulnerabilities in a pipeline > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13496) in GitLab 12.3. -At the pipeline level, the Security section displays the vulnerabilities present in the branch of -the project the pipeline ran against. - - +To view vulnerabilities in a pipeline: -Visit the page for any pipeline that ran any of the [supported reports](#supported-reports). To view -the pipeline's security findings, select the **Security** tab when viewing the pipeline. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. From the list, select the pipeline you want to check for vulnerabilities. +1. Select the **Security** tab. -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish -for any reason, the security dashboard doesn't show SAST scanner output. For example, if the SAST +A pipeline consists of multiple jobs, such as SAST and DAST scans. If a job fails to finish, +the security dashboard doesn't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard doesn't show SAST results. On failure, -the analyzer outputs an -[exit code](../../../development/integrations/secure.md#exit-code). +the analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code). + +## View total number of vulnerabilities per scan + +To view the total number of vulnerabilities per scan: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select the **Status** of a branch. +1. Select the **Security** tab. -### Scan details +**Scan details** show the total number of vulnerabilities found per scan in the pipeline. + +### Download security scan outputs > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3728) in GitLab 13.10. > - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/333660) in GitLab 14.2. -The **Scan details** section lists the scans run in the pipeline and the total number of vulnerabilities -per scan. +Depending on the type of security scanner, you can download: + +- A JSON artifact that contains the security scanner [report]('https://docs.gitlab.com/ee/development/integrations/secure.html#report'). +- A CSV file that contains URLs and endpoints scanned by the security scanner. + +To download a security scan output: -You can download the JSON artifacts from each security scan. Select **Download results** then -select the JSON artifact. Additionally for the DAST scan, from the **Download results** dropdown select -**Download scanned resources** to download a CSV file containing details of the resources scanned. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select the **Status** of a branch. +1. Select the **Security** tab. +1. In **Scan details**, select **Download results**: + - To download a JSON file, select the JSON artifact. + - To download a CSV file, select **Download scanned resources**. -## Project Security Dashboard +## View vulnerabilities over time for a project > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/235558) in GitLab 13.6. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285476) in GitLab 13.10, options to zoom in on a date range, and download the vulnerabilities chart. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/285477) in GitLab 13.11, date range slider to visualize data between given dates. -A project's Security Dashboard displays a chart with the total number of vulnerabilities -over time with up to 365 days of historical data. Data is refreshed daily at 1:15am UTC. By default, -it shows statistics for all vulnerability severities. +The project Security Dashboard shows the total number of vulnerabilities +over time, with up to 365 days of historical data. Data refreshes daily at 01:15 UTC. +It shows statistics for all vulnerabilities. -To access the dashboard, from your project's home page go to **Security & Compliance > Security Dashboard**. +To view total number of vulnerabilities over time: - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Security Dashboard**. +1. Filter and search for what you need. + - To filter the chart by severity, select the legend name. + - To view a specific time frame, use the time range handles (**{scroll-handle}**). + - To view a specific area of the chart, select the left-most icon (**{marquee-selection}**) and drag + across the chart. + - To reset to the original range, select **Remove Selection** (**{redo}**). -### Filter the vulnerabilities chart +### Download the vulnerabilities chart -To filter the chart by vulnerability severity, select the corresponding legend name. +To download an SVG image of the vulnerabilities chart: -In the previous example, the chart shows statistics only for vulnerabilities of medium or unknown severity. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Security & Compliance > Security dashboard**. +1. Select **Save chart as an image** (**{download}**). -### Customize vulnerabilities chart display +## View vulnerabilities over time for a group -To customize the view of the vulnerability chart, you can select: +The group Security Dashboard gives an overview of vulnerabilities found in the default +branches of projects in a group and its subgroups. -- A specific time frame by using the time range handles (**{scroll-handle}**). -- A specific area of the chart by using the left-most icon (**{marquee-selection}**) then drag - across the chart. To reset to the original range, select **Remove Selection** (**{redo}**). +To view vulnerabilities over time for a group: -### Download a copy of the vulnerabilities chart +1. On the top bar, select **Menu > Groups** and select a group. +1. Select **Security > Security Dashboard**. +1. Hover over the chart to get more details about vulnerabilities. + - You can display the vulnerability trends over a 30, 60, or 90-day time frame (the default is 90 days). + - To view aggregated data beyond a 90-day time frame, use the + [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). + GitLab retains the data for 365 days. -To download an SVG image of the chart, select **Save chart to an image** (**{download}**). +## View project security status for a group -## Group Security Dashboard +Use the group Security Dashboard to view the security status of projects. The security status is based +on the number of detected vulnerabilities. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/6709) in GitLab 11.5. +To view project security status for a group: -The group Security Dashboard gives an overview of the vulnerabilities found in the default branches of the -projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** -after selecting your group. By default, the Security Dashboard displays all detected and confirmed -vulnerabilities. If you don't see the vulnerabilities over time graph, the likely cause is that you -have not selected a group. +1. On the top bar, select **Menu > Groups** and select a group. +1. Select **Security > Security Dashboard**. -Note that the Security Dashboard only shows projects with -[security reports](#supported-reports) -enabled in a group. +Projects are [graded](#project-vulnerability-grades) by vulnerability severity. Dismissed vulnerabilities are excluded. - +To view vulnerabilities, go to the group's [vulnerability report](../vulnerability_report/index.md). -There is a timeline chart that shows how many open -vulnerabilities your projects had at various points in time. You can display the vulnerability -trends over a 30, 60, or 90-day time frame (the default is 90 days). Hover over the chart to get -more details about the open vulnerabilities at a specific time. Aggregated data beyond 90 days can be accessed by querying our [VulnerabilitiesCountByDay GraphQL API](../../../api/graphql/reference/index.md#vulnerabilitiescountbyday). This data is retained for 365 days. - -Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: +### Project vulnerability grades | Grade | Description | -| F | One or more "critical" | -| D | One or more "high" or "unknown" | -| C | One or more "medium" | -| B | One or more "low" | -| A | Zero vulnerabilities | - -Projects with no vulnerability tests configured don't appear in the list. Additionally, dismissed -vulnerabilities are excluded. - -Navigate to the group's [vulnerability report](../vulnerability_report/index.md) to view the vulnerabilities found. +| --- | --- | +| **F** | One or more `critical` vulnerabilities | +| **D** | One or more `high` or `unknown` vulnerabilities | +| **C** | One or more `medium` vulnerabilities | +| **B** | One or more `low` vulnerabilities | +| **A** | Zero vulnerabilities | ## Security Center > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3426) in GitLab 13.4. -The Security Center is personal space where you manage vulnerabilities across all your projects. It -displays the vulnerabilities present in the default branches of all the projects you configure. It includes -the following: +The Security Center is a personal space where you view vulnerabilities across all your projects. It +shows the vulnerabilities present in the default branches of the projects. + +The Security Center includes: -- The [group security dashboard's](#group-security-dashboard) features. +- The group Security Dashboard. - A [vulnerability report](../vulnerability_report/index.md). -- A dedicated settings area to configure which projects to display. +- A settings area to configure which projects to display.  +### View the Security Center + To view the Security Center, on the top bar, select **Menu > Security**. -### Adding projects to the Security Center +### Add projects to the Security Center To add projects to the Security Center: -1. Click **Settings** in the left navigation bar or click the **Add projects** button. -1. Search for and add one or more projects using the **Search your projects** field. -1. Click the **Add projects** button. +1. On the top bar, select **Menu > Security**. +1. On the left sidebar, select **Settings**, or select **Add projects**. +1. Use the **Search your projects** text box to search for and select projects. +1. Select **Add projects**. - - -After you add projects, the security dashboard and vulnerability report display the vulnerabilities +After you add projects, the security dashboard and vulnerability report show the vulnerabilities found in those projects' default branches. -## Keep dashboards up to date - -The Security Dashboard displays results of the most recent security scan on the -[default branch](../../project/repository/branches/default.md). By default, security scans are run -only when the default branch is updated. Information on the Security Dashboard may not reflect -newly-discovered vulnerabilities. - -To ensure the information on the Security Dashboard is regularly updated, -[configure a scheduled pipeline](../../../ci/pipelines/schedules.md) to run a daily security scan. -This updates the information displayed on the Security Dashboard regardless of how often the default -branch is updated. - -WARNING: -Running Dependency Scanning from a scheduled pipeline might result in false negatives if your -project doesn't have a lock file and isn't configured for Continuous Delivery. A lock file is a file -that lists all transient dependencies and keeps track of their exact versions. The false negative -can occur because the dependency version resolved during the scan might differ from the ones -resolved when your project was built and released, in a previous pipeline. Java projects can't have -lock files. Python projects can have lock files, but GitLab Secure tools don't support them. - <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues @@ -206,4 +199,8 @@ Each scenario can be a third-level heading, e.g. `### Getting error message X`. If you have none to add when creating a doc, leave this section in place but commented out to help encourage others to add to it in the future. --> -Read more on how to [address the vulnerabilities](../vulnerabilities/index.md). +## Related topics + +- [Address the vulnerabilities](../vulnerabilities/index.md) +- [Vulnerability reports](../vulnerability_report/index.md) +- [Vulnerability Page](../vulnerabilities/index.md) diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index 7bdc8cc8479..9aa8a0cd3cd 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -37,7 +37,7 @@ A vulnerability's status can be one of the following: | Status | Description | |:----------|:------------| -| Detected | The default state for a newly discovered vulnerability. | +| Detected | The default state for a newly discovered vulnerability. Appears as "Needs triage" in the UI. | | Confirmed | A user has seen this vulnerability and confirmed it to be accurate. | | Dismissed | A user has seen this vulnerability and dismissed it because it is not accurate or otherwise not to be resolved. | | Resolved | The vulnerability has been fixed or is no longer present. | @@ -168,7 +168,7 @@ The following vulnerability scanners and their databases are regularly updated: | Secure scanning tool | Vulnerabilities database updates | |:----------------------------------------------------------------|----------------------------------| | [Container Scanning](../container_scanning/index.md) | A job runs on a daily basis to build new images with the latest vulnerability database updates from the upstream scanner. | -| [Dependency Scanning](../dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated at least once a week. See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | +| [Dependency Scanning](../dependency_scanning/index.md) | Relies on `bundler-audit` (for Ruby gems), `retire.js` (for npm packages), and `gemnasium` (the GitLab tool for all libraries). Both `bundler-audit` and `retire.js` fetch their vulnerabilities data from GitHub repositories, so vulnerabilities added to `ruby-advisory-db` and `retire.js` are immediately available. The tools themselves are updated once per month if there's a new version. The [Gemnasium DB](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is updated on a daily basis using [data from NVD, the `ruby-advisory-db` and the GitHub Security Advisory Database as data sources](https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/blob/master/SOURCES.md). See our [current measurement of time from CVE being issued to our product being updated](https://about.gitlab.com/handbook/engineering/development/performance-indicators/#cve-issue-to-update). | | [Dynamic Application Security Testing (DAST)](../dast/index.md) | The scanning engine is updated on a periodic basis. See the [version of the underlying tool `zaproxy`](https://gitlab.com/gitlab-org/security-products/dast/blob/main/Dockerfile#L1). The scanning rules are downloaded at scan runtime. | | [Static Application Security Testing (SAST)](../sast/index.md) | Relies exclusively on [the tools GitLab wraps](../sast/index.md#supported-languages-and-frameworks). The underlying analyzers are updated at least once per month if a relevant update is available. The vulnerabilities database is updated by the upstream tools. | diff --git a/doc/user/application_security/vulnerability_report/index.md b/doc/user/application_security/vulnerability_report/index.md index 3773bb59c5a..05ff5c511f9 100644 --- a/doc/user/application_security/vulnerability_report/index.md +++ b/doc/user/application_security/vulnerability_report/index.md @@ -100,7 +100,7 @@ The content of the Project filter depends on the current level: | Level | Content of the Project filter | |:---------------|:------------------------------| -| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#adding-projects-to-the-security-center). | +| Security Center | Only projects you've [added to your personal Security Center](../security_dashboard/index.md#add-projects-to-the-security-center). | | Group level | All projects in the group. | | Project level | Not applicable. | |
