diff options
Diffstat (limited to 'doc/user/application_security')
33 files changed, 605 insertions, 251 deletions
diff --git a/doc/user/application_security/configuration/index.md b/doc/user/application_security/configuration/index.md index 229a8572206..1195d07d7b7 100644 --- a/doc/user/application_security/configuration/index.md +++ b/doc/user/application_security/configuration/index.md @@ -9,28 +9,21 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20711) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.6. -## Overview +The Security Configuration page displays the configuration state of each security feature in the +current project. The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) +to determine each feature's configuration state. If a job with the expected security report artifact +exists in the pipeline, the feature is considered enabled. -The security configuration page displays the configuration state of each of the security -features and can be accessed through a project's sidebar nav. - - - -The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) to determine the configuration -state of each feature. If a job with the expected security report artifact exists in the pipeline, -the feature is considered configured. +You can only enable SAST from the Security Configuration page. Documentation links are included for +the other features. For details about configuring SAST, see [Configure SAST in the UI](../sast/index.md#configure-sast-in-the-ui). NOTE: **Note:** If the latest pipeline used [Auto DevOps](../../../topics/autodevops/index.md), -all security features will be configured by default. +all security features are configured by default. -## Limitations +## View Security Configuration -It is not yet possible to enable or disable most features using the -configuration page. However, instructions on how to enable or disable a feature -can be found through the links next to each feature on that page. +To view a project's security configuration: -If a project does not have an existing CI configuration, then the SAST feature -can be enabled by clicking on the "Enable with Merge Request" button under the -"Manage" column. Future work will expand this to editing _existing_ CI -configurations, and to other security features. +1. Go to the project's home page. +1. In the left sidebar, go to **Security & Configuration** > **Configuration**. diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 7bc8b62825c..6b7086ddc71 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -156,25 +156,25 @@ variables: Container Scanning can be [configured](#customizing-the-container-scanning-settings) using environment variables. -| Environment Variable | Description | Default | -| ------ | ------ | ------ | -| `SECURE_ANALYZERS_PREFIX` | Set the Docker registry base address from which to download the analyzer. | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | -| `KLAR_TRACE` | Set to true to enable more verbose output from klar. | `"false"` | -| `CLAIR_TRACE` | Set to true to enable more verbose output from the clair server process. | `"false"` | -| `DOCKER_USER` | Username for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_USER` | -| `DOCKER_PASSWORD` | Password for accessing a Docker registry requiring authentication. | `$CI_REGISTRY_PASSWORD` | -| `CLAIR_OUTPUT` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold will be outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | `Unknown` | -| `REGISTRY_INSECURE` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | `"false"` | -| `DOCKER_INSECURE` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | `"false"` | -| `CLAIR_VULNERABILITIES_DB_URL` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. | `clair-vulnerabilities-db` | -| `CLAIR_DB_CONNECTION_STRING` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | -| `CI_APPLICATION_REPOSITORY` | Docker repository URL for the image to be scanned. | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | -| `CI_APPLICATION_TAG` | Docker repository tag for the image to be scanned. | `$CI_COMMIT_SHA` | -| `CLAIR_DB_IMAGE` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | `arminc/clair-db:latest` | -| `CLAIR_DB_IMAGE_TAG` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | `latest` | -| `DOCKERFILE_PATH` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner will look for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | `Dockerfile` | -| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs that you want to trust. | "" | -| `SECURE_LOG_LEVEL` | The log levels available are: `fatal`, `error`, `warn`, `info`, `debug` | `info` | +| Environment Variable | Default | Description | +| -------------------- | ----------- | ------- | +| `SECURE_ANALYZERS_PREFIX` | `"registry.gitlab.com/gitlab-org/security-products/analyzers"` | Set the Docker registry base address from which to download the analyzer. | +| `KLAR_TRACE` | `"false"` | Set to true to enable more verbose output from klar. | +| `CLAIR_TRACE` | `"false"` | Set to true to enable more verbose output from the clair server process. | +| `DOCKER_USER` | `$CI_REGISTRY_USER` | Username for accessing a Docker registry requiring authentication. | +| `DOCKER_PASSWORD` | `$CI_REGISTRY_PASSWORD` | Password for accessing a Docker registry requiring authentication. | +| `CLAIR_OUTPUT` | `Unknown` | Severity level threshold. Vulnerabilities with severity level higher than or equal to this threshold are outputted. Supported levels are `Unknown`, `Negligible`, `Low`, `Medium`, `High`, `Critical` and `Defcon1`. | +| `REGISTRY_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access insecure registries (HTTP only). Should only be set to `true` when testing the image locally. | +| `DOCKER_INSECURE` | `"false"` | Allow [Klar](https://github.com/optiopay/klar) to access secure Docker registries using HTTPS with bad (or self-signed) SSL certificates. | +| `CLAIR_VULNERABILITIES_DB_URL` | `clair-vulnerabilities-db` | (**DEPRECATED - use `CLAIR_DB_CONNECTION_STRING` instead**) This variable is explicitly set in the [services section](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) of the `Container-Scanning.gitlab-ci.yml` file and defaults to `clair-vulnerabilities-db`. This value represents the address that the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) is running on and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. | +| `CLAIR_DB_CONNECTION_STRING` | `postgresql://postgres:password@clair-vulnerabilities-db:5432/postgres?sslmode=disable&statement_timeout=60000` | This variable represents the [connection string](https://www.postgresql.org/docs/9.3/libpq-connect.html#AEN39692) to the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db) database and **shouldn't be changed** unless you're running the image locally as described in the [Running the standalone Container Scanning Tool](#running-the-standalone-container-scanning-tool) section. The host value for the connection string must match the [alias](https://gitlab.com/gitlab-org/gitlab/-/blob/898c5da43504eba87b749625da50098d345b60d6/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml#L23) value of the `Container-Scanning.gitlab-ci.yml` template file, which defaults to `clair-vulnerabilities-db`. | +| `CI_APPLICATION_REPOSITORY` | `$CI_REGISTRY_IMAGE/$CI_COMMIT_REF_SLUG` | Docker repository URL for the image to be scanned. | +| `CI_APPLICATION_TAG` | `$CI_COMMIT_SHA` | Docker repository tag for the image to be scanned. | +| `CLAIR_DB_IMAGE` | `arminc/clair-db:latest` | The Docker image name and tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes, or to refer to a locally hosted vulnerabilities database for an on-premise offline installation. | +| `CLAIR_DB_IMAGE_TAG` | `latest` | (**DEPRECATED - use `CLAIR_DB_IMAGE` instead**) The Docker image tag for the [PostgreSQL server hosting the vulnerabilities definitions](https://hub.docker.com/r/arminc/clair-db). It can be useful to override this value with a specific version, for example, to provide a consistent set of vulnerabilities for integration testing purposes. | +| `DOCKERFILE_PATH` | `Dockerfile` | The path to the `Dockerfile` to be used for generating remediations. By default, the scanner looks for a file named `Dockerfile` in the root directory of the project, so this variable should only be configured if your `Dockerfile` is in a non-standard location, such as a subdirectory. See [Solutions for vulnerabilities](#solutions-for-vulnerabilities-auto-remediation) for more details. | +| `ADDITIONAL_CA_CERT_BUNDLE` | `""` | Bundle of CA certs that you want to trust. | +| `SECURE_LOG_LEVEL` | `info` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. | ### Overriding the Container Scanning template @@ -291,7 +291,7 @@ build_latest_vulnerabilities: - docker push $CI_REGISTRY/namespace/clair-vulnerabilities-db ``` -The above template will work for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. +The above template works for a GitLab Docker registry running on a local installation, however, if you're using a non-GitLab Docker registry, you'll need to change the `$CI_REGISTRY` value and the `docker login` credentials to match the details of your local registry. ## Running the standalone Container Scanning Tool diff --git a/doc/user/application_security/coverage_fuzzing/index.md b/doc/user/application_security/coverage_fuzzing/index.md index 85da7d85506..1672e9fbb25 100644 --- a/doc/user/application_security/coverage_fuzzing/index.md +++ b/doc/user/application_security/coverage_fuzzing/index.md @@ -7,8 +7,6 @@ type: reference, howto # Coverage Guided Fuzz Testing **(ULTIMATE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3226) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2 as an [Alpha feature](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). - 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. Coverage-guided fuzzing sends random inputs to an instrumented version of your application in an effort to cause unexpected @@ -16,17 +14,19 @@ behavior, such as a crash. Such behavior indicates a bug that you should address 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/README.md), -you can run your coverage guided fuzz tests as part your CI/CD workflow. You can take advantage of -Coverage Guided Fuzzing by including the CI job in your existing `.gitlab-ci.yml` file. +you can run your coverage-guided fuzz tests as part your CI/CD workflow. You can take advantage of +coverage-guided fuzzing by including the CI job in your existing `.gitlab-ci.yml` file. ## 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. +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) | | -| GoLang | [go-fuzz (libFuzzer support)](https://github.com/dvyukov/go-fuzz) | | +| Language | Fuzzing Engine | Example | +|----------|----------------|---------| +| C/C++ | [libFuzzer](https://llvm.org/docs/LibFuzzer.html) | [c-cpp-example](https://gitlab.com/gitlab-org/security-products/demos/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/go-fuzzing-example) | | Rust | [cargo-fuzz (libFuzzer support)](https://github.com/rust-fuzz/cargo-fuzz) | | ## Configuration @@ -49,6 +49,14 @@ targets. Each fuzz 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. +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: + +- `before_script` +- `artifacts` +- `rules` + The `my_fuzz_target` job (the separate job for your fuzz target) does the following: - Extends `.fuzz_base`. @@ -59,8 +67,8 @@ The `my_fuzz_target` job (the separate job for your fuzz target) does the follow 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](#glossary) -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 +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`. ### Artifacts @@ -84,7 +92,7 @@ There are two types of jobs: Here's our current suggestion for configuring your fuzz target's timeout: -- Set `COVERAGE_FUZZING_BRANCH` to the branch where you want to run long-running (async) fuzzing +- Set `COVFUZZ_BRANCH` to the branch where you want to run long-running (async) fuzzing jobs. This is `master` by default. - Use regression or short-running fuzzing jobs for other branches or merge requests. @@ -99,7 +107,54 @@ any option available in the underlying fuzzing engine. | Environment variable | Description | |---------------------------|--------------------------------------------------------------------| -| `COVERAGE_FUZZING_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | +| `COVFUZZ_BRANCH` | The branch for long-running fuzzing jobs. The default is `master`. | +| `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 (`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. + +### Reports JSON format + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/220062) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 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#downloading-artifacts). + +Here's an example coverage fuzzing report: + +```json-doc +{ + "version": "v1.0.8", + "regression": false, + "exit_code": -1, + "vulnerabilities": [ + { + "category": "coverage_fuzzing", + "message": "Heap-buffer-overflow\nREAD 1", + "description": "Heap-buffer-overflow\nREAD 1", + "severity": "Critical", + "stacktrace_snippet": "INFO: Seed: 3415817494\nINFO: Loaded 1 modules (7 inline 8-bit counters): 7 [0x10eee2470, 0x10eee2477), \nINFO: Loaded 1 PC tables (7 PCs): 7 [0x10eee2478,0x10eee24e8), \nINFO: 5 files found in corpus\nINFO: -max_len is not provided; libFuzzer will not generate inputs larger than 4096 bytes\nINFO: seed corpus: files: 5 min: 1b max: 4b total: 14b rss: 26Mb\n#6\tINITED cov: 7 ft: 7 corp: 5/14b exec/s: 0 rss: 26Mb\n=================================================================\n==43405==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x602000001573 at pc 0x00010eea205a bp 0x7ffee0d5e090 sp 0x7ffee0d5e088\nREAD of size 1 at 0x602000001573 thread T0\n #0 0x10eea2059 in FuzzMe(unsigned char const*, unsigned long) fuzz_me.cc:9\n #1 0x10eea20ba in LLVMFuzzerTestOneInput fuzz_me.cc:13\n #2 0x10eebe020 in fuzzer::Fuzzer::ExecuteCallback(unsigned char const*, unsigned long) FuzzerLoop.cpp:556\n #3 0x10eebd765 in fuzzer::Fuzzer::RunOne(unsigned char const*, unsigned long, bool, fuzzer::InputInfo*, bool*) FuzzerLoop.cpp:470\n #4 0x10eebf966 in fuzzer::Fuzzer::MutateAndTestOne() FuzzerLoop.cpp:698\n #5 0x10eec0665 in fuzzer::Fuzzer::Loop(std::__1::vector\u003cfuzzer::SizedFile, fuzzer::fuzzer_allocator\u003cfuzzer::SizedFile\u003e \u003e\u0026) FuzzerLoop.cpp:830\n #6 0x10eead0cd in fuzzer::FuzzerDriver(int*, char***, int (*)(unsigned char const*, unsigned long)) FuzzerDriver.cpp:829\n #7 0x10eedaf82 in main FuzzerMain.cpp:19\n #8 0x7fff684fecc8 in start+0x0 (libdyld.dylib:x86_64+0x1acc8)\n\n0x602000001573 is located 0 bytes to the right of 3-byte region [0x602000001570,0x602000001573)\nallocated by thread T0 here:\n #0 0x10ef92cfd in wrap__Znam+0x7d (libclang_rt.asan_osx_dynamic.dylib:x86_64+0x50cfd)\n #1 0x10eebdf31 in fuzzer::Fuzzer::ExecuteCallback(unsigned char const*, unsigned long) FuzzerLoop.cpp:541\n #2 0x10eebd765 in fuzzer::Fuzzer::RunOne(unsigned char const*, unsigned long, bool, fuzzer::InputInfo*, bool*) FuzzerLoop.cpp:470\n #3 0x10eebf966 in fuzzer::Fuzzer::MutateAndTestOne() FuzzerLoop.cpp:698\n #4 0x10eec0665 in fuzzer::Fuzzer::Loop(std::__1::vector\u003cfuzzer::SizedFile, fuzzer::fuzzer_allocator\u003cfuzzer::SizedFile\u003e \u003e\u0026) FuzzerLoop.cpp:830\n #5 0x10eead0cd in fuzzer::FuzzerDriver(int*, char***, int (*)(unsigned char const*, unsigned long)) FuzzerDriver.cpp:829\n #6 0x10eedaf82 in main FuzzerMain.cpp:19\n #7 0x7fff684fecc8 in start+0x0 (libdyld.dylib:x86_64+0x1acc8)\n\nSUMMARY: AddressSanitizer: heap-buffer-overflow fuzz_me.cc:9 in FuzzMe(unsigned char const*, unsigned long)\nShadow bytes around the buggy address:\n 0x1c0400000250: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000260: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000270: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000280: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n 0x1c0400000290: fa fa fd fa fa fa fd fa fa fa fd fa fa fa fd fa\n=\u003e0x1c04000002a0: fa fa fd fa fa fa fd fa fa fa fd fa fa fa[03]fa\n 0x1c04000002b0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002c0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002d0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002e0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\n 0x1c04000002f0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa\nShadow byte legend (one shadow byte represents 8 application bytes):\n Addressable: 00\n Partially addressable: 01 02 03 04 05 06 07 \n Heap left redzone: fa\n Freed heap region: fd\n Stack left redzone: f1\n Stack mid redzone: f2\n Stack right redzone: f3\n Stack after return: f5\n Stack use after scope: f8\n Global redzone: f9\n Global init order: f6\n Poisoned by user: f7\n Container overflow: fc\n Array cookie: ac\n Intra object redzone: bb\n ASan internal: fe\n Left alloca redzone: ca\n Right alloca redzone: cb\n Shadow gap: cc\n==43405==ABORTING\nMS: 1 EraseBytes-; base unit: de3a753d4f1def197604865d76dba888d6aefc71\n0x46,0x55,0x5a,\nFUZ\nartifact_prefix='./crashes/'; Test unit written to ./crashes/crash-0eb8e4ed029b774d80f2b66408203801cb982a60\nBase64: RlVa\nstat::number_of_executed_units: 122\nstat::average_exec_per_sec: 0\nstat::new_units_added: 0\nstat::slowest_unit_time_sec: 0\nstat::peak_rss_mb: 28", + "scanner": { + "id": "libFuzzer", + "name": "libFuzzer" + }, + "location": { + "crash_address": "0x602000001573", + "crash_state": "FuzzMe\nstart\nstart+0x0\n\n", + "crash_type": "Heap-buffer-overflow\nREAD 1" + }, + "tool": "libFuzzer" + } + ] +} +``` ### Additional Configuration @@ -107,6 +162,17 @@ The `gitlab-cov-fuzz` command passes all arguments it receives to the underlying 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 + +To use coverage fuzzing in an offline environment, follow these steps: + +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. + ### Glossary - Seed corpus: The set of test cases given as initial input to the fuzz target. This usually speeds diff --git a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png Binary files differindex 8a733c27be1..045221d713c 100644 --- a/doc/user/application_security/dast/img/dast_on_demand_v13_2.png +++ b/doc/user/application_security/dast/img/dast_on_demand_v13_2.png diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index d68928d858b..b2020d48d38 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -48,16 +48,16 @@ uses the popular open source tool [OWASP Zed Attack Proxy](https://www.zaproxy.o to perform an analysis on your running web application. By default, DAST executes [ZAP Baseline Scan](https://www.zaproxy.org/docs/docker/baseline-scan/) -and performs passive scanning only. It won't actively attack your application. +and performs passive scanning only. It doesn't actively attack your application. However, DAST can be [configured](#full-scan) to also perform an *active scan*: attack your application and produce a more extensive security report. It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). NOTE: **Note:** A pipeline may consist of multiple jobs, including SAST and DAST scanning. If any -job fails to finish for any reason, the security dashboard won't show DAST scanner +job fails to finish for any reason, the security dashboard doesn't show DAST scanner output. For example, if the DAST job finishes but the SAST job fails, the security -dashboard won't show DAST results. The analyzer will output an +dashboard doesn't show DAST results. The analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code) on failure. ## Use cases @@ -112,7 +112,7 @@ always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) is used to run the tests on the specified URL and scan it for possible vulnerabilities. -By default, the DAST template will use the latest major version of the DAST Docker +By default, the DAST template uses the latest major version of the DAST Docker image. Using the `DAST_VERSION` variable, you can choose how DAST updates: - Automatically update DAST with new features and fixes by pinning to a major version (such as `1`). @@ -163,7 +163,7 @@ headers whose values you want masked. For details on how to mask headers, see It's also possible to authenticate the user before performing the DAST checks. -Create masked variables to pass the credentials that DAST will use. +Create masked variables to pass the credentials that DAST uses. To create masked variables for the username and password, see [Create a custom variable in the UI](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). Note that the key of the username variable must be `DAST_USERNAME` and the key of the password variable must be `DAST_PASSWORD`. @@ -182,7 +182,7 @@ variables: DAST_AUTH_EXCLUDE_URLS: http://example.com/sign-out,http://example.com/sign-out-2 # optional, URLs to skip during the authenticated scan; comma-separated, no spaces in between ``` -The results will be saved as a +The results are saved as a [DAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest DAST artifact available. @@ -227,10 +227,10 @@ variables: Since ZAP full scan actively attacks the target application, DAST sends a ping to the target (normally defined in `DAST_WEBSITE` or `environment_url.txt`) beforehand. -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan will - proceed unless the response to the ping includes a `Gitlab-DAST-Permission` +- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `false` or unset, the scan + proceeds unless the response to the ping includes a `Gitlab-DAST-Permission` header with a value of `deny`. -- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan will exit +- If `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` is `true`, the scan exits unless the response to the ping includes a `Gitlab-DAST-Permission` header with a value of `allow`. @@ -434,7 +434,7 @@ variables: ``` Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline -configuration, the last mention of the variable will take precedence. +configuration, the last mention of the variable takes precedence. ### Available variables @@ -445,24 +445,24 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia | `SECURE_ANALYZERS_PREFIX` | URL | Set the Docker registry base address from which to download the analyzer. | | `DAST_WEBSITE` | URL | The URL of the website to scan. `DAST_API_SPECIFICATION` must be specified if this is omitted. | | `DAST_API_SPECIFICATION` | URL or string | The API specification to import. The specification can be hosted at a URL, or the name of a file present in the `/zap/wrk` directory. `DAST_WEBSITE` must be specified if this is omitted. | -| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` will be submitted with the login form to create an authenticated scan. Not supported for API scans. | +| `DAST_AUTH_URL` | URL | The URL of the page containing the sign-in HTML form on the target website. `DAST_USERNAME` and `DAST_PASSWORD` are submitted with the login form to create an authenticated scan. Not supported for API scans. | | `DAST_USERNAME` | string | The username to authenticate to in the website. | | `DAST_PASSWORD` | string | The password to authenticate to in the website. | | `DAST_USERNAME_FIELD` | string | The name of username field at the sign-in HTML form. | | `DAST_PASSWORD_FIELD` | string | The name of password field at the sign-in HTML form. | -| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (introduced in GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | +| `DAST_MASK_HTTP_HEADERS` | string | Comma-separated list of request and response headers to be masked (GitLab 13.1). Must contain **all** headers to be masked. Refer to [list of headers that are masked by default](#hide-sensitive-information). | | `DAST_AUTH_EXCLUDE_URLS` | URLs | The URLs to skip during the authenticated scan; comma-separated, no spaces in between. Not supported for API scans. | | `DAST_FULL_SCAN_ENABLED` | boolean | Set to `true` to run a [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of a [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Default: `false` | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | boolean | Set to `true` to require [domain validation](#domain-validation) when running DAST full scans. Not supported for API scans. Default: `false` | | `DAST_AUTO_UPDATE_ADDONS` | boolean | ZAP add-ons are pinned to specific versions in the DAST Docker image. Set to `true` to download the latest versions when the scan starts. Default: `false` | | `DAST_API_HOST_OVERRIDE` | string | Used to override domains defined in API specification files. Example: `example.com:8080` | | `DAST_EXCLUDE_RULES` | string | Set to a comma-separated list of Vulnerability Rule IDs to exclude them from running during the scan. Rule IDs are numbers and can be found from the DAST log or on the [ZAP project](https://github.com/zaproxy/zaproxy/blob/develop/docs/scanners.md). For example, `HTTP Parameter Override` has a rule ID of `10026`. **Note:** In earlier versions of GitLab the excluded rules were executed but alerts they generated were supressed. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/118641) in GitLab 12.10. | -| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers will be added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | +| `DAST_REQUEST_HEADERS` | string | Set to a comma-separated list of request header names and values. Headers are added to every request made by DAST. For example, `Cache-control: no-cache,User-Agent: DAST/1.0` | | `DAST_DEBUG` | boolean | Enable debug message output. Default: `false` | | `DAST_SPIDER_MINS` | number | The maximum duration of the spider scan in minutes. Set to `0` for unlimited. Default: One minute, or unlimited when the scan is a full scan. | -| `DAST_HTML_REPORT` | string | The file name of the HTML report written at the end of a scan. | -| `DAST_MARKDOWN_REPORT` | string | The file name of the Markdown report written at the end of a scan. | -| `DAST_XML_REPORT` | string | The file name of the XML report written at the end of a scan. | +| `DAST_HTML_REPORT` | string | The filename of the HTML report written at the end of a scan. | +| `DAST_MARKDOWN_REPORT` | string | The filename of the Markdown report written at the end of a scan. | +| `DAST_XML_REPORT` | string | The filename of the XML report written at the end of a scan. | | `DAST_INCLUDE_ALPHA_VULNERABILITIES` | boolean | Set to `true` to include alpha passive and active scan rules. Default: `false` | | `DAST_USE_AJAX_SPIDER` | boolean | Set to `true` to use the AJAX spider in addition to the traditional spider, useful for crawling sites that require JavaScript. Default: `false` | | `DAST_ZAP_CLI_OPTIONS` | string | ZAP server command-line options. For example, `-Xmx3072m` would set the Java maximum memory allocation pool size. | @@ -472,7 +472,7 @@ DAST can be [configured](#customizing-the-dast-settings) using environment varia Not all DAST configuration is available via environment variables. To find out all possible options, run the following configuration. -Available command-line options will be printed to the job log: +Available command-line options are printed to the job log: ```yaml include: @@ -526,7 +526,7 @@ A DAST job has two executing processes: - A series of scripts that start, control and stop the ZAP server. Debug mode of the scripts can be enabled by using the `DAST_DEBUG` environment variable. This can help when troubleshooting the job, -and will output statements indicating what percentage of the scan is complete. +and outputs statements indicating what percentage of the scan is complete. For details on using variables, see [Overriding the DAST template](#customizing-the-dast-settings). Debug mode of the ZAP server can be enabled using the `DAST_ZAP_LOG_CONFIGURATION` environment variable. @@ -603,24 +603,76 @@ Alternatively, you can use the variable `SECURE_ANALYZERS_PREFIX` to override th ## On-Demand Scans > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.2. -> - It's deployed behind a feature flag, disabled by default. -> - It's disabled on GitLab.com. +> - [Improved](https://gitlab.com/gitlab-org/gitlab/-/issues/218465) in GitLab 13.3. +> - It's deployed behind a feature flag, enabled by default. +> - It's enabled on GitLab.com. > - It's able to be enabled or disabled per-project. > - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-on-demand-scans). -Passive DAST scans may be run on demand against a target website, outside the DevOps lifecycle. These scans will -always be associated with the default or `master` branch of your project and the results can be seen in the project dashboard. +You can run a passive DAST scan against a target website, outside the DevOps lifecycle. These scans +are always associated with the default branch of your project and the results are available in the +project dashboard. + +### Site profile + +An on-demand scan requires a site profile, which includes a profile name and target URL. The profile +name allows you to describe the site to be scanned. The target URL specifies the URL against which +the DAST scan is run. + +### Run an on-demand scan + +NOTE: **Note:** +You must have permission to run an on-demand DAST scan against a protected branch. +The default branch is automatically protected. For more details, see [Pipeline security on protected branches](../../../ci/pipelines/index.md#pipeline-security-on-protected-branches). + +Running an on-demand scan requires an existing site profile. If a site profile for the target URL +doesn't exist, first [create a site profile](#create-a-site-profile). An on-demand DAST scan has +a fixed timeout of 60 seconds. + +- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. +- Click **Create new DAST scan**. +- Select a site profile from the profiles dropdown. +- Click **Run scan**. + +#### Create a site profile - +- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. +- Click **Create new DAST scan**. +- Click **New Site Profile**. +- Type in a unique **Profile name** and **Target URL** then click **Save profile**. -### Enable or disable On-Demand Scans +#### Delete a site profile + +- Navigate to your project's home page, then click **On-demand Scans** in the left sidebar. +- Click **Create new DAST scan**. +- Click **Delete** in the matching site profile's row. + +### Enable or disable On-demand Scans and site profiles + +On-demand Scans with site profiles is enabled by default. You can disable On-demand Scans +instance-wide, or disable it for specific projects if you prefer. DAST site profiles are not +available if the On-demand Scans feature is disabled. + +Use of On-demand Scans with site profiles requires **both** the following feature flags enabled: + +- security_on_demand_scans_feature_flag +- security_on_demand_scans_site_profiles_feature_flag -On-Demand Scans is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. [GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it for your instance. On-Demand Scans can be enabled or disabled per-project +can disable or enable the feature flags. + +#### Enable or disable On-demand Scans + +To disable On-demand Scans: + +```ruby +# Instance-wide +Feature.disable(:security_on_demand_scans_feature_flag) +# or by project +Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +``` -To enable it: +To enable On-demand Scans: ```ruby # Instance-wide @@ -629,13 +681,29 @@ Feature.enable(:security_on_demand_scans_feature_flag) Feature.enable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) ``` -To disable it: +#### Enable or disable site profiles + +The Site Profiles feature is enabled instance-wide by default. You can disable it instance-wide, or disable it +for specific projects if you prefer. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable or enable the feature flag. + +To disable Site Profiles: ```ruby # Instance-wide -Feature.disable(:security_on_demand_scans_feature_flag) +Feature.disable(:security_on_demand_scans_site_profiles_feature_flag) # or by project -Feature.disable(:security_on_demand_scans_feature_flag, Project.find(<project id>)) +Feature.disable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) +``` + +To enable Site Profiles: + +```ruby +# Instance-wide +Feature.enable(:security_on_demand_scans_site_profiles_feature_flag) +# or by project +Feature.enable(:security_on_demand_scans_site_profiles_feature_flag, Project.find(<project id>)) ``` ## Reports @@ -719,7 +787,7 @@ For more information about the vulnerabilities database update, check the ## Optimizing DAST -By default, DAST will download all artifacts defined by previous jobs in the pipeline. If +By default, DAST downloads all artifacts defined by previous jobs in the pipeline. If your DAST job does not rely on `environment_url.txt` to define the URL under test or any other files created in previous jobs, we recommend you don't download artifacts. To avoid downloading artifacts, add the following to your `gitlab-ci.yml` file: diff --git a/doc/user/application_security/dependency_scanning/analyzers.md b/doc/user/application_security/dependency_scanning/analyzers.md index ca2b212ffc3..d41f9441464 100644 --- a/doc/user/application_security/dependency_scanning/analyzers.md +++ b/doc/user/application_security/dependency_scanning/analyzers.md @@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Dependency Scanning Analyzers **(ULTIMATE)** -Dependency Scanning relies on underlying third party tools that are wrapped into +Dependency Scanning relies on underlying third-party tools that are wrapped into what we call "Analyzers". An analyzer is a [dedicated project](https://gitlab.com/gitlab-org/security-products/analyzers) that wraps a particular tool to: @@ -26,7 +26,7 @@ Dependency Scanning supports the following official analyzers: - [`gemnasium-python`](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python) - [`retire.js`](https://gitlab.com/gitlab-org/security-products/analyzers/retire.js) -The analyzers are published as Docker images that Dependency Scanning will use +The analyzers are published as Docker images, which Dependency Scanning uses to launch dedicated containers for each analysis. Dependency Scanning is pre-configured with a set of **default images** that are @@ -70,12 +70,12 @@ variables: DS_DEFAULT_ANALYZERS: "bundler-audit,gemnasium" ``` -`bundler-audit` runs first. When merging the reports, Dependency Scanning will -remove the duplicates and will keep the `bundler-audit` entries. +`bundler-audit` runs first. When merging the reports, Dependency Scanning +removes the duplicates and keeps the `bundler-audit` entries. ### Disabling default analyzers -Setting `DS_DEFAULT_ANALYZERS` to an empty string will disable all the official +Setting `DS_DEFAULT_ANALYZERS` to an empty string disables all the official default analyzers. In `.gitlab-ci.yml` define: ```yaml @@ -158,8 +158,8 @@ The following table lists the data available for each official analyzer. | Credits | ✓ | 𐄂 | 𐄂 | - ✓ => we have that data -- ⚠ => we have that data but it's partially reliable, or we need to extract that data from unstructured content -- 𐄂 => we don't have that data or it would need to develop specific or inefficient/unreliable logic to obtain it. +- ⚠ => we have that data, but it's partially reliable, or we need to extract that data from unstructured content +- 𐄂 => we don't have that data, or it would need to develop specific or inefficient/unreliable logic to obtain it. -The values provided by these tools are heterogeneous so they are sometimes +The values provided by these tools are heterogeneous, so they are sometimes normalized into common values (e.g., `severity`, `confidence`, etc). diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 57b4fae3230..6b14f93735b 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -9,9 +9,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5105) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.7. -Dependency Scanning helps to automatically find security vulnerabilities in your dependencies +Dependency Scanning helps to find security vulnerabilities in your dependencies automatically while you're developing and testing your applications, such as when your -application is using an external (open source) library which is known to be vulnerable. +application is using an external (open source) library that is known to be vulnerable. ## Overview @@ -60,6 +60,7 @@ The following languages and dependency managers are supported: | Language (package managers) | Supported files | Scan tool(s) | |----------------------------- | --------------- | ------------ | +| C# .NET ([NuGet](https://www.nuget.org/) 4.9+) | [`packages.lock.json`](https://docs.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files#enabling-lock-file) | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | Java ([Gradle](https://gradle.org/), [Maven](https://maven.apache.org/)) | `build.gradle`, `build.gradle.kts`, `pom.xml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | | JavaScript ([npm](https://www.npmjs.com/), [yarn](https://classic.yarnpkg.com/en/)) | `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [Retire.js](https://retirejs.github.io/retire.js/) | | Go ([Golang](https://golang.org/)) | `go.sum` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | @@ -84,7 +85,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) To enable Dependency Scanning for GitLab 11.9 and later, you must [include](../../../ci/yaml/README.md#includetemplate) the [`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml) -that's provided as a part of your GitLab installation. +that is 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. @@ -95,9 +96,9 @@ include: - template: Dependency-Scanning.gitlab-ci.yml ``` -The included template will create Dependency Scanning jobs in your CI/CD -pipeline and scan your project's source code for possible vulnerabilities. -The results will be saved as a +The included template creates Dependency Scanning jobs in your CI/CD +pipeline and scans your project's source code for possible vulnerabilities. +The results are saved as a [Dependency Scanning report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportsdependency_scanning-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest Dependency Scanning artifact available. @@ -117,7 +118,7 @@ variables: ``` Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline -configuration, the last mention of the variable will take precedence. +configuration, the last mention of the variable takes precedence. ### Overriding Dependency Scanning jobs @@ -155,7 +156,7 @@ The following variables allow configuration of global dependency scanning settin | `DS_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | | `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certs to trust. | | `DS_EXCLUDED_PATHS` | Exclude vulnerabilities from output based on the paths. A comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. Default: `"spec, test, tests, tmp"` | -| `SECURE_LOG_LEVEL` | Default log level is `info`, you can set it to any of the following strings: `fatal`, `error`, `warn`, `info`, `debug`. | +| `SECURE_LOG_LEVEL` | Set the minimum logging level. Messages of this logging level or higher are output. From highest to lowest severity, the logging levels are: `fatal`, `error`, `warn`, `info`, `debug`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. Default: `info` | #### Configuring Docker-in-Docker orchestrator @@ -186,10 +187,10 @@ The following variables are used for configuring specific analyzers (used for a | `DS_PIP_VERSION` | `gemnasium-python` | | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the Docker image is used. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12811) in GitLab 12.7) | | `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12412) in GitLab 12.2) | | `DS_PYTHON_VERSION` | `retire.js` | | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12296) in GitLab 12.1)| -| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle will use the Java version specified by this value. | -| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that will be passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | -| `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that will be passed to `gradle` by the analyzer. | -| `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer will pass to `sbt`. | +| `DS_JAVA_VERSION` | `gemnasium-maven` | `11` | Version of Java. Available versions: `8`, `11`, `13`, `14`. Maven and Gradle use the Java version specified by this value. | +| `MAVEN_CLI_OPTS` | `gemnasium-maven` | `"-DskipTests --batch-mode"` | List of command line arguments that are passed to `maven` by the analyzer. See an example for [using private repositories](../index.md#using-private-maven-repos). | +| `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. | +| `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. | | `BUNDLER_AUDIT_UPDATE_DISABLED` | `bundler-audit` | `"false"` | Disable automatic updates for the `bundler-audit` analyzer. Useful if you're running Dependency Scanning in an offline, air-gapped environment.| | `BUNDLER_AUDIT_ADVISORY_DB_URL` | `bundler-audit` | `https://github.com/rubysec/ruby-advisory-db` | URL of the advisory database used by bundler-audit. | | `BUNDLER_AUDIT_ADVISORY_DB_REF_NAME` | `bundler-audit` | `master` | Git ref for the advisory database specified by `BUNDLER_AUDIT_ADVISORY_DB_URL`. | @@ -310,7 +311,7 @@ Here's an example Dependency Scanning report: "category": "dependency_scanning", "name": "Authentication bypass via incorrect DOM traversal and canonicalization", "message": "Authentication bypass via incorrect DOM traversal and canonicalization in saml2-js", - "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment therefore has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.", + "description": "Some XML DOM traversal and canonicalization APIs may be inconsistent in handling of comments within XML nodes. Incorrect use of these APIs by some SAML libraries results in incorrect parsing of the inner text of XML nodes such that any inner text after the comment is lost prior to cryptographically signing the SAML message. Text after the comment, therefore, has no impact on the signature on the SAML message.\r\n\r\nA remote attacker can modify SAML content for a SAML service provider without invalidating the cryptographic signature, which may allow attackers to bypass primary authentication for the affected SAML service provider.", "severity": "Unknown", "solution": "Upgrade to fixed version.\r\n", "scanner": { @@ -390,7 +391,9 @@ Here are the requirements for using Dependency Scanning in an offline environmen - Keep Docker-In-Docker disabled (default). - GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). - Docker Container Registry with locally available copies of Dependency Scanning [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. -- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/) +- Host an offline Git copy of the [gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/). + This is required because, in an offline environment, the Gemnasium analyzer can't fetch the latest + advisories from the online repository. - _Only if scanning Ruby projects_: Host an offline Git copy of the [advisory database](https://github.com/rubysec/ruby-advisory-db). - _Only if scanning npm/yarn projects_: Host an offline copy of the [retire.js](https://github.com/RetireJS/retire.js/) [node](https://github.com/RetireJS/retire.js/blob/master/repository/npmrepository.json) and [js](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json) advisory databases. @@ -428,8 +431,10 @@ For details on saving and transporting Docker images as a file, see Docker's doc ### Set Dependency Scanning CI job variables to use local Dependency Scanning analyzers -Add the following configuration to your `.gitlab-ci.yml` file. You must replace -`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry: +Add the following configuration to your `.gitlab-ci.yml` file. You must change the value of +`SECURE_ANALYZERS_PREFIX` to refer to your local Docker container registry. You must also change the +value of `GEMNASIUM_DB_REMOTE_URL` to the location of your offline Git copy of the +[gemnasium-db advisory database](https://gitlab.com/gitlab-org/security-products/gemnasium-db/): ```yaml include: diff --git a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png b/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png Binary files differindex 385236d08f2..cb8911b14b1 100644 --- a/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png +++ b/doc/user/application_security/img/adding_a_dismissal_reason_v13_0.png diff --git a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png b/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png Binary files differindex 866ad74d42c..19d47712f9e 100644 --- a/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png +++ b/doc/user/application_security/img/interacting_with_vulnerability_v13_0.png diff --git a/doc/user/application_security/img/vulnerability-check_v13_0.png b/doc/user/application_security/img/vulnerability-check_v13_0.png Binary files differindex 536fc4f10f7..9f0bd0f759b 100644 --- a/doc/user/application_security/img/vulnerability-check_v13_0.png +++ b/doc/user/application_security/img/vulnerability-check_v13_0.png diff --git a/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png b/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png Binary files differnew file mode 100644 index 00000000000..10d9effb811 --- /dev/null +++ b/doc/user/application_security/img/vulnerability_related_issues_add_button_v13_2.png diff --git a/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif Binary files differnew file mode 100644 index 00000000000..22acba5fe1e --- /dev/null +++ b/doc/user/application_security/img/vulnerability_related_issues_remove_v13_2.gif diff --git a/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif b/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif Binary files differnew file mode 100644 index 00000000000..562ffe7e329 --- /dev/null +++ b/doc/user/application_security/img/vulnerability_related_issues_text_box_tags_v13_2.gif diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 3aca4c59423..c003b512808 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -45,6 +45,12 @@ To add Container Scanning, follow the steps listed in the [Container Scanning do To further configure any of the other scanners, refer to each scanner's documentation. +### SAST configuration + +You can set up and configure Static Application Security Testing +(SAST) for your project, without opening a text editor. For more details, +see [configure SAST in the UI](sast/index.md#configure-sast-in-the-ui). + ### Override the default registry base address By default, GitLab security scanners use `registry.gitlab.com/gitlab-org/security-products/analyzers` as the @@ -61,9 +67,10 @@ GitLab uses the following tools to scan and report known vulnerabilities found i | [Dependency List](dependency_list/index.md) **(ULTIMATE)** | View your project's dependencies and their known vulnerabilities. | | [Dependency Scanning](dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | -| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | +| [Secret Detection](secret_detection/index.md) **(ULTIMATE)** | Analyze Git history for leaked secrets. | | [Security Dashboard](security_dashboard/index.md) **(ULTIMATE)** | View vulnerabilities in all your projects and groups. | -| [Static Application Security Testing (SAST)](sast/index.md) **(ULTIMATE)** | Analyze source code for known vulnerabilities. | +| [Static Application Security Testing (SAST)](sast/index.md) | Analyze source code for known vulnerabilities. | +| [Coverage fuzzing](coverage_fuzzing/index.md) **(ULTIMATE)** | Find unknown bugs and vulnerabilities with coverage-guided fuzzing. | ## Security Scanning with Auto DevOps @@ -118,6 +125,8 @@ information with several options: ### View details of a DAST vulnerability +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/36332) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1. + Vulnerabilities detected by DAST occur in the live web application. Rectification of these types of vulnerabilities requires specific information. DAST provides the information required to investigate and rectify the underlying cause. @@ -242,6 +251,36 @@ Click this button to create a merge request to apply the solution onto the sourc  +### Managing related issues for a vulnerability + +Issues can be linked to a vulnerability using the related issues block on the vulnerability page. +The relationship is uni-directional. The vulnerability page shows related issues, but the issue page +doesn't show the vulnerability it's related to. An issue can only be related to one vulnerability at +a time. Issues can be linked across groups and projects. + +#### Adding a related issue + +You can link an issue by clicking the **{plus}** button in the **Related Issues** block. + + + +A text box appears that lets you type an issue number or paste an issue link. You can enter multiple +issues at once. Pressing the space bar after each issue number or link converts them to tags that +you can remove by clicking the **{close}** icon to the tag's right. Typing `#` followed by a number +shows an autocomplete menu. Click an issue in the menu to add it as a tag. When you're finished +entering issues, click the **Add** button to link the issues to the vulnerability. Alternatively, +click **Cancel** to exit without linking any issues. + + + +### Removing a related issue + +Click the **{close}** icon to right of an issue to remove it as a related issue. Note that this only +removes it as a related issue of the vulnerability; it doesn't modify or remove the issue itself. +You can link it to the vulnerability again if desired. + + + ## Security approvals in merge requests > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9928) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.2. @@ -272,7 +311,7 @@ To enable Security Approvals, a [project approval rule](../project/merge_request must be created with the case-sensitive name `Vulnerability-Check`. This approval group must be set with the number of approvals required greater than zero. You must have Maintainer or Owner [permissions](../permissions.md#project-members-permissions) to manage approval rules. -1. Navigate to your project's **{settings}** **Settings > General** and expand **Merge request approvals**. +1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name** to `Vulnerability-Check` (case sensitive). @@ -282,14 +321,15 @@ Once this group is added to your project, the approval rule is enabled for all m Any code changes cause the approvals required to reset. -An approval is required when a security report: +An approval is required when the latest security report in a merge request: -- Contains a new vulnerability of `high`, `critical`, or `unknown` severity, regardless of dismissal. +- Contains a vulnerability of `high`, `critical`, or `unknown` severity that is not present in the + target branch. Note that approval is still required for dismissed vulnerabilities. - Is not generated during pipeline execution. -An approval is optional when a security report: +An approval is optional when the security report: -- Contains no new vulnerabilities. +- Contains no new vulnerabilities when compared to the target branch. - Contains only new vulnerabilities of `low` or `medium` severity. ## Enabling License Approvals within a project diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md index 9a2f8768fc0..a5cf93f9448 100644 --- a/doc/user/application_security/offline_deployments/index.md +++ b/doc/user/application_security/offline_deployments/index.md @@ -91,3 +91,126 @@ above. You can find more information at each of the pages below: - [DAST offline directions](../dast/index.md#running-dast-in-an-offline-environment) - [License Compliance offline directions](../../compliance/license_compliance/index.md#running-license-compliance-in-an-offline-environment) - [Dependency Scanning offline directions](../dependency_scanning/index.md#running-dependency-scanning-in-an-offline-environment) + +## Loading Docker images onto your offline host + +To use many GitLab features, including +[security scans](../index.md#working-in-an-offline-environment) +and [Auto DevOps](../../../topics/autodevops/index.md), the GitLab Runner must be able to fetch the +relevant Docker images. + +The process for making these images available without direct access to the public internet +involves downloading the images then packaging and transferring them to the offline host. Here's an +example of such a transfer: + +1. Download Docker images from public internet. +1. Package Docker images as tar archives. +1. Transfer images to offline environment. +1. Load transferred images into offline Docker registry. + +### Using the official GitLab template + +GitLab provides a [vendored template](../../../ci/yaml/README.md#includetemplate) +to ease this process. + +This template should be used in a new, empty project, with a `gitlab-ci.yml` file containing: + +```yaml +include: + - template: Secure-Binaries.gitlab-ci.yml +``` + +The pipeline downloads the Docker images needed for the Security Scanners and saves them as +[job artifacts](../../../ci/pipelines/job_artifacts.md) or pushes them to the [Container Registry](../../packages/container_registry/index.md) +of the project where the pipeline is executed. These archives can be transferred to another location +and [loaded](https://docs.docker.com/engine/reference/commandline/load/) in a Docker daemon. +This method requires a GitLab Runner with access to both `gitlab.com` (including +`registry.gitlab.com`) and the local offline instance. This runner must run in +[privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode) +to be able to use the `docker` command inside the jobs. This runner can be installed in a DMZ or on +a bastion, and used only for this specific project. + +#### Scheduling the updates + +By default, this project's pipeline will run only once, when the `.gitlab-ci.yml` is added to the +repo. To update the GitLab security scanners and signatures, it's necessary to run this pipeline +regularly. GitLab provides a way to [schedule pipelines](../../../ci/pipelines/schedules.md). For +example, you can set this up to download and store the Docker images every week. + +Some images can be updated more frequently than others. For example, the [vulnerability database](https://hub.docker.com/r/arminc/clair-db/tags) +for Container Scanning is updated daily. To update this single image, create a new Scheduled +Pipeline that runs daily and set `SECURE_BINARIES_ANALYZERS` to `clair-vulnerabilities-db`. Only +this job will be triggered, and the image will be updated daily and made available in the project +registry. + +#### Using the secure bundle created + +The project using the `Secure-Binaries.gitlab-ci.yml` template should now host all the required +images and resources needed to run GitLab Security features. + +Next, you must tell the offline instance to use these resources instead of the default ones on +GitLab.com. To do so, set the environment variable `SECURE_ANALYZERS_PREFIX` with the URL of the +project [container registry](../../packages/container_registry/index.md). + +You can set this variable in the projects' `.gitlab-ci.yml`, or +in the GitLab UI at the project or group level. See the [GitLab CI/CD environment variables page](../../../ci/variables/README.md#custom-environment-variables) +for more information. + +#### Variables + +The following table shows which variables you can use with the `Secure-Binaries.gitlab-ci.yml` +template: + +| VARIABLE | Description | Default value | +|-------------------------------------------|-----------------------------------------------|-----------------------------------| +| `SECURE_BINARIES_ANALYZERS` | Comma-separated list of analyzers to download | `"bandit, brakeman, gosec, and so on..."` | +| `SECURE_BINARIES_DOWNLOAD_IMAGES` | Used to disable jobs | `"true"` | +| `SECURE_BINARIES_PUSH_IMAGES` | Push files to the project registry | `"true"` | +| `SECURE_BINARIES_SAVE_ARTIFACTS` | Also save image archives as artifacts | `"false"` | +| `SECURE_BINARIES_ANALYZER_VERSION` | Default analyzer version (Docker tag) | `"2"` | + +### Alternate way without the official template + +If it's not possible to follow the above method, the images can be transferred manually instead: + +#### Example image packager script + +```shell +#!/bin/bash +set -ux + +# Specify needed analyzer images +analyzers=${SAST_ANALYZERS:-"bandit eslint gosec"} +gitlab=registry.gitlab.com/gitlab-org/security-products/analyzers/ + +for i in "${analyzers[@]}" +do + tarname="${i}_2.tar" + docker pull $gitlab$i:2 + docker save $gitlab$i:2 -o ./analyzers/${tarname} + chmod +r ./analyzers/${tarname} +done +``` + +#### Example image loader script + +This example loads the images from a bastion host to an offline host. In certain configurations, +physical media may be needed for such a transfer: + +```shell +#!/bin/bash +set -ux + +# Specify needed analyzer images +analyzers=${SAST_ANALYZERS:-"bandit eslint gosec"} +registry=$GITLAB_HOST:4567 + +for i in "${analyzers[@]}" +do + tarname="${i}_2.tar" + scp ./analyzers/${tarname} ${GITLAB_HOST}:~/${tarname} + ssh $GITLAB_HOST "sudo docker load -i ${tarname}" + ssh $GITLAB_HOST "sudo docker tag $(sudo docker images | grep $i | awk '{print $3}') ${registry}/analyzers/${i}:2" + ssh $GITLAB_HOST "sudo docker push ${registry}/analyzers/${i}:2" +done +``` diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 70d4b513cf9..fd331020719 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference, howto --- -# Static Application Security Testing (SAST) **(ULTIMATE)** +# Static Application Security Testing (SAST) > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3775) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.3. @@ -14,19 +14,11 @@ The whitepaper ["A Seismic Shift in Application Security"](https://about.gitlab. explains how **4 of the top 6 attacks were application based**. Download it to learn how to protect your organization. -## Overview - If you're using [GitLab CI/CD](../../../ci/README.md), you can analyze your source code for known -vulnerabilities using Static Application Security Testing (SAST). - -You can take advantage of SAST by doing one of the following: - -- [Including the SAST template](#configuration) in your existing `.gitlab-ci.yml` file. -- Implicitly using [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) provided by - [Auto DevOps](../../../topics/autodevops/index.md). +vulnerabilities using Static Application Security Testing (SAST). GitLab checks the SAST report and +compares the found vulnerabilities between the source and target branches. -GitLab checks the SAST report, compares the found vulnerabilities between the -source and target branches, and shows the information right on the merge request. +Details of the vulnerabilities found are included in the merge request. **(ULTIMATE)**  @@ -40,7 +32,7 @@ The results are sorted by the priority of the vulnerability: 1. Everything else NOTE: **Note:** -A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard won't show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard won't show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. +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 job finishes but the DAST job fails, the security dashboard doesn't show SAST results. The analyzer outputs an [exit code](../../../development/integrations/secure.md#exit-code) on failure. ## Use cases @@ -51,15 +43,15 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j ## Requirements -To run SAST jobs, by default, you need GitLab Runner with the +To run SAST jobs, by default, you need a GitLab Runner with the [`docker`](https://docs.gitlab.com/runner/executors/docker.html) or [`kubernetes`](https://docs.gitlab.com/runner/install/kubernetes.html) executor. If you're using the shared Runners on GitLab.com, this is enabled by default. -Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for SAST](#enabling-docker-in-docker). +Beginning with GitLab 13.0, Docker privileged mode is necessary only if you've [enabled Docker-in-Docker for SAST](#enabling-docker-in-docker-ultimate). CAUTION: **Caution:** -Our SAST jobs currently expect a Linux container type. Windows containers are not yet supported. +Our SAST jobs require a Linux container type. Windows containers are not yet supported. CAUTION: **Caution:** If you use your own Runners, make sure the Docker version installed @@ -69,27 +61,27 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae The following table shows which languages, package managers and frameworks are supported and which tools are used. -| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | -|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------|------------------------------| -| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0 | -| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0 | -| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11.9 | -| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1 | -| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7 | -| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10 | -| Go | [Gosec](https://github.com/securego/gosec) | 10.7 | -| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT) | -| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1 | -| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT) | -| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8, moved to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | -| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6 | -| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1 | -| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8 | -| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3 | -| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5 | -| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3, moved to [GitLab Core](https://about.gitlab.com/pricing/) in 13.1 | -| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven) | -| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, merged with ESLint in 13.2 | +| Language (package managers) / framework | Scan tool | Introduced in GitLab Version | +|--------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| .NET Core | [Security Code Scan](https://security-code-scan.github.io) | 11.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| .NET Framework | [Security Code Scan](https://security-code-scan.github.io) | 13.0, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Any | [Gitleaks](https://github.com/zricethezav/gitleaks) and [TruffleHog](https://github.com/dxa4481/truffleHog) | 11., [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Apex (Salesforce) | [PMD](https://pmd.github.io/pmd/index.html) | 12.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| C/C++ | [Flawfinder](https://github.com/david-a-wheeler/flawfinder) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Elixir (Phoenix) | [Sobelow](https://github.com/nccgroup/sobelow) | 11.10, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Go | [Gosec](https://github.com/securego/gosec) | 10.7, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Groovy ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.3 (Gradle) & 11.9 (Ant, Maven, SBT), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Helm Charts | [Kubesec](https://github.com/controlplaneio/kubesec) | 13.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Java ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 10.6 (Maven), 10.8 (Gradle) & 11.9 (Ant, SBT), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| JavaScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.8, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | +| Kubernetes manifests | [Kubesec](https://github.com/controlplaneio/kubesec) | 12.6, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Node.js | [NodeJsScan](https://github.com/ajinabraham/NodeJsScan) | 11.1, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| PHP | [phpcs-security-audit](https://github.com/FloeDesignTechnologies/phpcs-security-audit) | 10.8, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| Python ([pip](https://pip.pypa.io/en/stable/)) | [bandit](https://github.com/PyCQA/bandit) | 10.3, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| React | [ESLint react plugin](https://github.com/yannickcr/eslint-plugin-react) | 12.5, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.2 | +| Ruby on Rails | [brakeman](https://brakemanscanner.org) | 10.3, [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.1 | +| Scala ([Ant](https://ant.apache.org/), [Gradle](https://gradle.org/), [Maven](https://maven.apache.org/) and [SBT](https://www.scala-sbt.org/)) | [SpotBugs](https://spotbugs.github.io/) with the [find-sec-bugs](https://find-sec-bugs.github.io/) plugin | 11.0 (SBT) & 11.9 (Ant, Gradle, Maven), [moved](https://gitlab.com/groups/gitlab-org/-/epics/2098) to [GitLab Core](https://about.gitlab.com/pricing/) in 13.3 | +| TypeScript | [ESLint security plugin](https://github.com/nodesecurity/eslint-plugin-security) | 11.9, [merged](https://gitlab.com/gitlab-org/gitlab/-/issues/36059) with ESLint in 13.2 | NOTE: **Note:** The Java analyzers can also be used for variants like the @@ -98,11 +90,11 @@ The Java analyzers can also be used for variants like the ### Making SAST analyzers available to all GitLab tiers -All open source (OSS) analyzers are in the process of being reviewed and potentially moved to the GitLab Core tier. Progress can be +All open source (OSS) analyzers have been moved to the GitLab Core tier. Progress can be tracked in the corresponding [epic](https://gitlab.com/groups/gitlab-org/-/epics/2098). -Please note that support for [Docker-in-Docker](#enabling-docker-in-docker) +Please note that support for [Docker-in-Docker](#enabling-docker-in-docker-ultimate) will not be extended to the GitLab Core tier. #### Summary of features per tier @@ -110,14 +102,14 @@ will not be extended to the GitLab Core tier. Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: -| Capability | In Core | In Ultimate | -|:--------------------------------------------------------------------------|:--------------------|:-------------------| -| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | -| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | -| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | -| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | -| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities) | **{dotted-circle}** | **{check-circle}** | -| [Access to Security Dashboard](#security-dashboard) | **{dotted-circle}** | **{check-circle}** | +| Capability | In Core | In Ultimate | +|:-----------------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure SAST Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize SAST Settings](#customizing-the-sast-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](#reports-json-format) | **{check-circle}** | **{check-circle}** | +| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| [Interaction with Vulnerabilities](#interacting-with-the-vulnerabilities-ultimate) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](#security-dashboard-ultimate) | **{dotted-circle}** | **{check-circle}** | ## Contribute your scanner @@ -125,9 +117,14 @@ The [Security Scanner Integration](../../../development/integrations/secure.md) ## Configuration -NOTE: **Note:** -You don't have to configure SAST manually as shown in this section if you're using [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) -provided by [Auto DevOps](../../../topics/autodevops/index.md). +To configure SAST for a project you can: + +- Use [Auto SAST](../../../topics/autodevops/stages.md#auto-sast-ultimate) provided by + [Auto DevOps](../../../topics/autodevops/index.md). +- [Configure SAST manually](#configure-sast-manually). +- [Configure SAST using the UI](#configure-sast-in-the-ui) (introduced in GitLab 13.3). + +### Configure SAST manually For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/README.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) @@ -141,14 +138,29 @@ include: - template: SAST.gitlab-ci.yml ``` -The included template will create SAST jobs in your CI/CD pipeline and scan +The included template creates SAST jobs in your CI/CD pipeline and scans your project's source code for possible vulnerabilities. -The results will be saved as a +The results are saved as a [SAST report artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportssast-ultimate) that you can later download and analyze. Due to implementation limitations, we always take the latest SAST artifact available. +### Configure SAST in the UI + +> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3659) in GitLab Ultimate 13.3. + +For a project that does not have a `.gitlab-ci.yml` file, you can enable SAST with a basic +configuration using the **SAST Configuration** page: + +1. From the project's home page, go to **Security & Configuration** > **Configuration** in the + left sidebar. +1. Click **Enable via Merge Request** on the Static Application Security Testing (SAST) row. +1. Enter the appropriate SAST details into the fields on the page. See [Available variables](#available-variables) + for a description of these variables. +1. Click **Create Merge Request**. +1. Review and merge the merge request. + ### Customizing the SAST settings The SAST settings can be changed through [environment variables](#available-variables) @@ -203,12 +215,12 @@ you can use the `MAVEN_CLI_OPTS` environment variable. Read more on [how to use private Maven repositories](../index.md#using-private-maven-repos). -### Enabling Docker-in-Docker +### Enabling Docker-in-Docker **(ULTIMATE)** If needed, you can enable Docker-in-Docker to restore the SAST behavior that existed prior to GitLab 13.0. Follow these steps to do so: -1. Configure GitLab Runner with Docker-inDocker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). +1. Configure a GitLab Runner with Docker-in-Docker in [privileged mode](https://docs.gitlab.com/runner/executors/docker.html#use-docker-in-docker-with-privileged-mode). 1. Set the variable `SAST_DISABLE_DIND` set to `false`: ```yaml @@ -289,14 +301,16 @@ See [Analyzer settings](#analyzer-settings) for the complete list of available o SAST can be [configured](#customizing-the-sast-settings) using environment variables. -#### Logging Level +#### Logging level -You can control the verbosity of logs by setting the `SECURE_LOG_LEVEL` env var. The default is set to `info`, you can set it to any of the following levels: +To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. + +From highest to lowest severity, the logging levels are: - `fatal` - `error` - `warn` -- `info` +- `info` (default) - `debug` #### Custom Certificate Authority @@ -308,12 +322,12 @@ of CA certs that you want to trust within the SAST environment. The following are Docker image-related variables. -| Environment variable | Description | -|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | -| `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | -| `SAST_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker). This variable is `true` by default. | +| Environment variable | Description | +|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------| +| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the default images (proxy). Read more about [customizing analyzers](analyzers.md). | +| `SAST_ANALYZER_IMAGE_TAG` | **DEPRECATED:** Override the Docker tag of the default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_DEFAULT_ANALYZERS` | Override the names of default images. Read more about [customizing analyzers](analyzers.md). | +| `SAST_DISABLE_DIND` | Disable Docker-in-Docker and run analyzers [individually](#enabling-docker-in-docker-ultimate). This variable is `true` by default. | #### Vulnerability filters @@ -322,9 +336,9 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre | Environment variable | Default value | Description | |-------------------------------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `SAST_EXCLUDED_PATHS` | `spec, test, tests, tmp` | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories will also match patterns. | -| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | +| `SEARCH_MAX_DEPTH` | 4 | Maximum number of directories traversed when searching for source code files. | +| `SAST_BANDIT_EXCLUDED_PATHS` | | Comma-separated list of paths to exclude from scan. Uses Python's [`fnmatch` syntax](https://docs.python.org/2/library/fnmatch.html); For example: `'*/tests/*, */venv/*'` | | `SAST_BRAKEMAN_LEVEL` | 1 | Ignore Brakeman vulnerabilities under given confidence level. Integer, 1=Low 3=High. | -| `SAST_DISABLE_BABEL` | `false` | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | | `SAST_FLAWFINDER_LEVEL` | 1 | Ignore Flawfinder vulnerabilities under given risk level. Integer, 0=No risk, 5=High risk. | | `SAST_GITLEAKS_ENTROPY_LEVEL` | 8.0 | Minimum entropy for secret detection. Float, 0.0 = low, 8.0 = high. | | `SAST_GOSEC_LEVEL` | 0 | Ignore Gosec vulnerabilities under given confidence level. Integer, 0=Undefined, 1=Low, 2=Medium, 3=High. | @@ -334,40 +348,40 @@ Some analyzers make it possible to filter out vulnerabilities under a given thre #### Docker-in-Docker orchestrator -The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker). +The following variables configure the Docker-in-Docker orchestrator, and therefore are only used when the Docker-in-Docker mode is [enabled](#enabling-docker-in-docker-ultimate). -| Environment variable | Default value | Description | -|------------------------------------------|---------------|-------------| -| `SAST_ANALYZER_IMAGES` | | Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | -| `SAST_PULL_ANALYZER_IMAGES` | 1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | -| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | -| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`.| +| Environment variable | Default value | Description | +|------------------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SAST_ANALYZER_IMAGES` | | Comma-separated list of custom images. Default images are still enabled. Read more about [customizing analyzers](analyzers.md). | +| `SAST_PULL_ANALYZER_IMAGES` | 1 | Pull the images from the Docker registry (set to 0 to disable). Read more about [customizing analyzers](analyzers.md). | +| `SAST_DOCKER_CLIENT_NEGOTIATION_TIMEOUT` | 2m | Time limit for Docker client negotiation. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | +| `SAST_PULL_ANALYZER_IMAGE_TIMEOUT` | 5m | Time limit when pulling the image of an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | +| `SAST_RUN_ANALYZER_TIMEOUT` | 20m | Time limit when running an analyzer. Timeouts are parsed using Go's [`ParseDuration`](https://golang.org/pkg/time/#ParseDuration). Valid time units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, `h`. For example, `300ms`, `1.5h` or `2h45m`. | #### Analyzer settings Some analyzers can be customized with environment variables. -| Environment variable | Analyzer | Description | -|---------------------------------------|----------------------|-------------| -| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | -| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` will use to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | -| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | -| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | -| `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | -| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | -| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | -| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | -| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | -| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | -| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | -| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | -| `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | -| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | -| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | -| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | -| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | -| `SEARCH_MAX_DEPTH` | any | Maximum number of directories traversed when searching for source code files. Default: `4`. | +| Environment variable | Analyzer | Description | +|---------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `SCAN_KUBERNETES_MANIFESTS` | Kubesec | Set to `"true"` to scan Kubernetes manifests. | +| `KUBESEC_HELM_CHARTS_PATH` | Kubesec | Optional path to Helm charts that `helm` will use to generate a Kubernetes manifest that `kubesec` will scan. If dependencies are defined, `helm dependency build` should be ran in a `before_script` to fetch the necessary dependencies. | +| `KUBESEC_HELM_OPTIONS` | Kubesec | Additional arguments for the `helm` executable. | +| `COMPILE` | SpotBugs | Set to `false` to disable project compilation and dependency fetching. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/195252) in GitLab 13.1. | +| `ANT_HOME` | SpotBugs | The `ANT_HOME` environment variable. | +| `ANT_PATH` | SpotBugs | Path to the `ant` executable. | +| `GRADLE_PATH` | SpotBugs | Path to the `gradle` executable. | +| `JAVA_OPTS` | SpotBugs | Additional arguments for the `java` executable. | +| `JAVA_PATH` | SpotBugs | Path to the `java` executable. | +| `SAST_JAVA_VERSION` | SpotBugs | Which Java version to use. Supported versions are `8` and `11`. Defaults to `8`. | +| `MAVEN_CLI_OPTS` | SpotBugs | Additional arguments for the `mvn` or `mvnw` executable. | +| `MAVEN_PATH` | SpotBugs | Path to the `mvn` executable. | +| `MAVEN_REPO_PATH` | SpotBugs | Path to the Maven local repository (shortcut for the `maven.repo.local` property). | +| `SBT_PATH` | SpotBugs | Path to the `sbt` executable. | +| `FAIL_NEVER` | SpotBugs | Set to `1` to ignore compilation failure. | +| `SAST_GOSEC_CONFIG` | Gosec | Path to configuration for Gosec (optional). | +| `PHPCS_SECURITY_AUDIT_PHP_EXTENSIONS` | phpcs-security-audit | Comma separated list of additional PHP Extensions. | +| `SAST_DISABLE_BABEL` | NodeJsScan | Disable Babel processing for the NodeJsScan scanner. Set to `true` to disable Babel processing. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33065) in GitLab 13.2. | #### Custom environment variables @@ -387,6 +401,9 @@ analyzer containers: `DOCKER_`, `CI`, `GITLAB_`, `FF_`, `HOME`, `PWD`, `OLDPWD`, The SAST 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/sast-report-format.json). +The JSON report file can be downloaded from the CI pipelines page, for more +information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md). + Here's an example SAST report: ```json-doc @@ -466,13 +483,13 @@ Here's an example SAST report: Learn more about [Secret Detection](../secret_detection). -## Security Dashboard +## Security Dashboard **(ULTIMATE)** The Security Dashboard is a good place to get an overview of all the security vulnerabilities in your groups, projects and pipelines. Read more about the [Security Dashboard](../security_dashboard/index.md). -## Interacting with the vulnerabilities +## Interacting with the vulnerabilities **(ULTIMATE)** Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). @@ -498,8 +515,9 @@ run successfully. For more information, see [Offline environments](../offline_de To use SAST in an offline environment, you need: - To keep Docker-In-Docker disabled (default). -- GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). -- Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- A GitLab Runner with the [`docker` or `kubernetes` executor](#requirements). +- A Docker Container Registry with locally available copies of SAST [analyzer](https://gitlab.com/gitlab-org/security-products/analyzers) images. +- Configure certificate checking of packages (optional). NOTE: **Note:** GitLab Runner has a [default `pull policy` of `always`](https://docs.gitlab.com/runner/executors/docker.html#using-the-always-pull-policy), @@ -556,6 +574,13 @@ variables: The SAST job should now use local copies of the SAST analyzers to scan your code and generate security reports without requiring internet access. +### Configure certificate checking of packages + +If a SAST job invokes a package manager, you must configure its certificate verification. In an +offline environment, certificate verification with an external source isn't possible. Either use a +self-signed certificate or disable certificate verification. Refer to the package manager's +documentation for instructions. + ## Troubleshooting ### `Error response from daemon: error processing tar file: docker-tar: relocation error` diff --git a/doc/user/application_security/secret_detection/index.md b/doc/user/application_security/secret_detection/index.md index ea635212c5d..7daf2f3308b 100644 --- a/doc/user/application_security/secret_detection/index.md +++ b/doc/user/application_security/secret_detection/index.md @@ -19,7 +19,7 @@ malicious users to gain access to resources like deployment environments. 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. -GitLab displays identified secrets as part of the SAST reports visibly in a few places: +GitLab displays identified secrets visibly in a few places: - [Security Dashboard](../security_dashboard/) - Pipelines' **Security** tab @@ -46,6 +46,25 @@ CAUTION: **Caution:** If you use your own Runners, make sure the Docker version installed is **not** `19.03.0`. See [troubleshooting information](../sast#error-response-from-daemon-error-processing-tar-file-docker-tar-relocation-error) for details. +### Making Secret Detection available to all GitLab tiers + +To make Secret Detection available to as many customers as possible, we have enabled it for all GitLab tiers. +However not all features are available on every tier. See the breakdown below for more details. + +#### Summary of features per tier + +Different features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), +as shown in the following table: + +| Capability | In Core | In Ultimate | +|:--------------------------------------------------------------------------|:--------------------|:-------------------| +| [Configure Secret Detection Scanners](#configuration) | **{check-circle}** | **{check-circle}** | +| [Customize Secret Detection Settings](#customizing-settings) | **{check-circle}** | **{check-circle}** | +| View [JSON Report](../sast/index.md#reports-json-format) | **{check-circle}** | **{check-circle}** | +| [Presentation of JSON Report in Merge Request](#overview) | **{dotted-circle}** | **{check-circle}** | +| [Interaction with Vulnerabilities](../vulnerabilities/index.md) | **{dotted-circle}** | **{check-circle}** | +| [Access to Security Dashboard](../security_dashboard/index.md) | **{dotted-circle}** | **{check-circle}** | + ## Configuration NOTE: **Note:** @@ -145,16 +164,19 @@ Secret Detection can be customized by defining available variables: |-------------------------|---------------|-------------| | `SECRET_DETECTION_COMMIT_FROM` | - | The commit a Gitleaks scan starts at. | | `SECRET_DETECTION_COMMIT_TO` | - | The commit a Gitleaks scan ends at. | +| `SECRET_DETECTION_EXCLUDED_PATHS` | "" | Exclude vulnerabilities from output based on the paths. This is a comma-separated list of patterns. Patterns can be globs, or file or folder paths (for example, `doc,spec` ). Parent directories will also match patterns. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/225273) in GitLab 13.3. | | `SECRET_DETECTION_HISTORIC_SCAN` | false | Flag to enable a historic Gitleaks scan. | -### Logging Level +### Logging level + +To control the verbosity of logs set the `SECURE_LOG_LEVEL` environment variable. Messages of this logging level or higher are output. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10880) in GitLab 13.1. -You can control the verbosity of logs by setting the `SECURE_LOG_LEVEL` env var. The default is set to `info`, you can set it to any of the following levels: +From highest to lowest severity, the logging levels are: - `fatal` - `error` - `warn` -- `info` +- `info` (default) - `debug` ## Full History Secret Scan diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png Binary files differindex d98fb71ae37..8fab4e39175 100644 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_export_csv_v13_1.png diff --git a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png Binary files differdeleted file mode 100644 index d6cfc2de980..00000000000 --- a/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_2_noNav.png +++ /dev/null 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 differnew file mode 100644 index 00000000000..4d51f57a98d --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_security_dashboard_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png Binary files differnew file mode 100644 index 00000000000..7b9a48b8738 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/group_vulnerability_report_v13_3.png diff --git a/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif b/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif Binary files differnew file mode 100644 index 00000000000..29e7168b6ea --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/pipeline_security_v13_3.gif diff --git a/doc/user/application_security/security_dashboard/img/standalone_vulnerability_page_v13_1.png b/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png Binary files differindex 9cf95b197fe..9cf95b197fe 100644 --- a/doc/user/application_security/security_dashboard/img/standalone_vulnerability_page_v13_1.png +++ b/doc/user/application_security/security_dashboard/img/vulnerability_page_v13_1.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index 9a13d143d1f..b8fcc513cb1 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -8,24 +8,24 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Security Dashboard **(ULTIMATE)** The Security Dashboard is a good place to get an overview of all the security -vulnerabilities in your groups, projects and pipelines. +vulnerabilities in your groups, projects, and pipelines. -You can also drill down into a vulnerability and get extra information, see which -project it comes from, the file it's in, and various metadata to help you analyze -the risk. You can also take actions on vulnerabilities by creating an issue for them, -or by dismissing them. +You can also drill down into a vulnerability and get extra information. This includes the project it +comes from, any related file(s), and metadata that helps you analyze the risk it poses. You can also +dismiss a vulnerability or create an issue for it. To benefit from the Security Dashboard you must first configure one of the -[security reports](../index.md). +[security scanners](../index.md). ## Supported reports -The Security Dashboard supports the following reports: +The Security Dashboard displays vulnerabilities detected by scanners such as: - [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) +- And others! ## Requirements @@ -43,10 +43,13 @@ To use the instance, group, project, or pipeline security dashboard: At the pipeline level, the Security section displays the vulnerabilities present in the branch of the project the pipeline was run against. -Visit the page for any pipeline which has run any of the [supported reports](#supported-reports). Click the **Security** tab to view the Security findings. -  +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. + + + NOTE: **Note:** A pipeline consists of multiple jobs, including SAST and DAST scanning. If any job fails to finish for any reason, the security dashboard will not show SAST scanner output. For example, if the SAST job finishes but the DAST job fails, the security dashboard will not show SAST results. The analyzer will output an [exit code](../../../development/integrations/secure.md#exit-code) on failure. @@ -56,7 +59,8 @@ A pipeline consists of multiple jobs, including SAST and DAST scanning. If any j At the project level, the Security Dashboard displays the vulnerabilities merged into your project's [default branch](../../project/repository/branches/index.md#default-branch). Access it by navigating -to **Security & Compliance > Security Dashboard**. +to **Security & Compliance > Security Dashboard**. By default, the Security Dashboard displays all +detected and confirmed vulnerabilities. The Security Dashboard first displays the total number of vulnerabilities by severity (for example, Critical, High, Medium, Low). Below this, a table displays each vulnerability's status, severity, @@ -67,7 +71,7 @@ You can filter the vulnerabilities by: - Status - Severity -- Report type +- Scanner You can also dismiss vulnerabilities in the table: @@ -82,31 +86,21 @@ You can also dismiss vulnerabilities in the table: The group Security Dashboard gives an overview of the vulnerabilities in the default branches of the projects in a group and its subgroups. Access it by navigating to **Security > Security Dashboard** -for your group. +for your group. By default, the Security Dashboard displays all detected and confirmed +vulnerabilities. NOTE: **Note:** The Security Dashboard only shows projects with [security reports](#supported-reports) enabled in a group. - - -You can filter which vulnerabilities the Security Dashboard displays by: - -- Status -- Severity -- Report type -- Project - -A table lists the vulnerabilities, sorted by severity. The table shows each vulnerability's status, -severity, and description. Clicking a vulnerability takes you to its [Vulnerability Details](../vulnerabilities) -page to view more information about that vulnerability. + -Next to the list is a timeline chart that shows how many open +There is a timeline chart that shows how many open vulnerabilities your projects had at various points in time. You can filter among 30, 60, and 90 days, with the default being 90. Hover over the chart to get more details about the open vulnerabilities at a specific time. -Below the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: +Next to the timeline chart is a list of projects, grouped and sorted by the severity of the vulnerability found: - F: 1 or more "critical" - D: 1 or more "high" or "unknown" @@ -117,7 +111,7 @@ Below the timeline chart is a list of projects, grouped and sorted by the severi Projects with no vulnerability tests configured will not appear in the list. Additionally, dismissed vulnerabilities are not included either. -Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +Navigate to the group's [Vulnerability Report](#vulnerability-list) to view the vulnerabilities found. ## Instance Security Dashboard @@ -195,10 +189,21 @@ to configure daily security scans. Each dashboard's vulnerability list contains vulnerabilities from the latest scans that were merged into the default branch. -Click any vulnerability in the table to see more information on that vulnerability. To create an -issue associated with the vulnerability, click the **Create Issue** button. - + + +You can filter which vulnerabilities the Security Dashboard displays by: + +- Status +- Severity +- Scanner +- Project + +Clicking any vulnerability in the table takes you to its +[Vulnerability Details](../vulnerabilities) page to see more information on that vulnerability. +To create an issue associated with the vulnerability, click the **Create Issue** button. + + Once you create the issue, the vulnerability list contains a link to the issue and an icon whose color indicates the issue's status (green for open issues, blue for closed issues). @@ -216,3 +221,5 @@ questions that you know someone might ask. 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 [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md index a6738677454..c916cdbfe7c 100644 --- a/doc/user/application_security/threat_monitoring/index.md +++ b/doc/user/application_security/threat_monitoring/index.md @@ -99,6 +99,11 @@ deployment platform. Changes performed outside of this tab are reflected upon refresh. Enforcement status changes are deployed directly to a deployment namespace of the selected environment. +By default, the network policy list contains predefined policies in a +disabled state. Once enabled,a predefined policy deploys to the +selected environment's deployment platform and you can manage it like +the regular policies. + NOTE: **Note:** If you're using [Auto DevOps](../../../topics/autodevops/index.md) and change a policy in this section, your `auto-deploy-values.yaml` file diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differdeleted file mode 100644 index 2063762d3eb..00000000000 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_dropdown_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_v13_1.png Binary files differdeleted file mode 100644 index ee4e97bcafe..00000000000 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_merge_request_button_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png b/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png Binary files differdeleted file mode 100644 index e0e0fdb6f6e..00000000000 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_v13_1.png +++ /dev/null diff --git a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_download_patch_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png Binary files differindex b925c342a11..b925c342a11 100644 --- a/doc/user/application_security/vulnerabilities/img/standalone_vulnerability_page_download_patch_button_v13_1.png +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_download_patch_button_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png Binary files differnew file mode 100644 index 00000000000..05ca74c3d5c --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_dropdown_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png Binary files differnew file mode 100644 index 00000000000..a3034a7db04 --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_merge_request_button_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png b/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png Binary files differnew file mode 100644 index 00000000000..30a7195e1ab --- /dev/null +++ b/doc/user/application_security/vulnerabilities/img/vulnerability_page_v13_1.png diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md index d5cce6434d8..ffec4bf336d 100644 --- a/doc/user/application_security/vulnerabilities/index.md +++ b/doc/user/application_security/vulnerabilities/index.md @@ -5,16 +5,16 @@ group: Threat Insights 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/#designated-technical-writers --- -# Standalone Vulnerability pages +# Vulnerability Pages > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13561) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.0. Each security vulnerability in the [Security Dashboard](../security_dashboard/index.md#project-security-dashboard) has its own standalone page. - + -On the standalone vulnerability page, you can interact with the vulnerability in +On the vulnerability page, you can interact with the vulnerability in several different ways: - [Change the Vulnerability Status](#changing-vulnerability-status) - You can change the @@ -57,7 +57,7 @@ generates for you. GitLab supports the following scanners: When an automatic solution is available, the button in the header will show "Resolve with merge request": - + Selecting the button will create a merge request with the automatic solution. @@ -66,8 +66,8 @@ Selecting the button will create a merge request with the automatic solution. To manually apply the patch that was generated by GitLab for a vulnerability, select the dropdown arrow on the "Resolve with merge request" button, then select the "Download patch to resolve" option: - + This will change the button text to "Download patch to resolve". Click on it to download the patch: - + |
