diff --git a/doc/user/application_security/sast/gitlab_advanced_sast.md b/doc/user/application_security/sast/gitlab_advanced_sast.md index 07b168f6e9ee0b75a60581cad9848b686b398fe3..bcfe692e8cde70fccd7813949b9604279986b9eb 100644 --- a/doc/user/application_security/sast/gitlab_advanced_sast.md +++ b/doc/user/application_security/sast/gitlab_advanced_sast.md @@ -44,7 +44,7 @@ For an overview of GitLab Advanced SAST and how it works, see [GitLab Advanced S For a product tour, see the [GitLab Advanced SAST product tour](https://gitlab.navattic.com/advanced-sast). -## Feature comparison +## Features | Feature | SAST | Advanced SAST | |------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| @@ -54,6 +54,103 @@ For a product tour, see the [GitLab Advanced SAST product tour](https://gitlab.n | Works with GitLab Duo Vulnerability Explanation and Vulnerability Resolution | Yes. | Yes. | | Language coverage | [More expansive](_index.md#supported-languages-and-frameworks). | [More limited](#supported-languages). | +## Getting started + +If you are new to GitLab Advanced SAST, the following steps show how to enable it for your project. + +Prerequisites: + +- Enable the standard SAST analyzer. For details, see + [SAST prerequisites](_index.md#getting-started) . +- On GitLab Self-Managed, you must also use a GitLab version that supports GitLab Advanced SAST: + - GitLab version 17.1 or later is required but you should use GitLab 17.4 or later if possible. + GitLab 17.4 includes a new code-flow view, vulnerability deduplication, and further updates to + the SAST CI/CD template. + - The SAST CI/CD templates were updated to include GitLab Advanced SAST in the following releases: + - The stable template includes GitLab Advanced SAST in GitLab 17.3 or later. + - The latest template includes GitLab Advanced SAST in GitLab 17.2 or later. Don't mix + [latest and stable templates](../detect/security_configuration.md#template-editions) in a + single project. + +To enable GitLab Advanced SAST, use the pipeline editor: + +1. In your project, select **Build** > **Pipeline editor**. +1. If no `.gitlab-ci.yml` file exists, select **Configure pipeline**, then delete the example + content. +1. In the pipeline configuration, add the appropriate CI/CD variable: + + For all supported languages except C/C++: + + ```yaml + variables: + GITLAB_ADVANCED_SAST_ENABLED: 'true' + ``` + + For C/C++: + + ```yaml + variables: + GITLAB_ADVANCED_SAST_CPP_ENABLED: 'true' + ``` + + If your configuration already has a `variables:` section, add only the variable line (for + example, `GITLAB_ADVANCED_SAST_ENABLED: 'true'`) to the existing section. Do not create a + duplicate `variables:` section. + +1. Select the **Validate** tab, then select **Validate pipeline**. + + The message **Simulation completed successfully** confirms the file is valid. +1. Select the **Edit** tab. +1. Complete the fields. +1. Select the **Start a new merge request with these changes** checkbox, then select **Commit + changes**. +1. Complete the fields according to your standard workflow, then select **Create + merge request**. +1. Review and edit the merge request according to your standard workflow, then select **Merge**. + +At this point, GitLab Advanced SAST is enabled in your pipeline. Supported source code is scanned +for vulnerabilities when a pipeline runs. The corresponding jobs appears in the `test` stage in your +pipeline. + +After completing these steps, you can: + +- Learn more about how to [understand the results](#understanding-the-results). +- Review [optimization tips](#optimization). +- Plan a [rollout to more projects](#roll-out). + +## Understanding the results + +You can review vulnerabilities in a pipeline: + +1. On the left sidebar, select **Search or go to** and find your project. +1. On the left sidebar, select **Build** > **Pipelines**. +1. Select the pipeline. +1. Select the **Security** tab. +1. Either download results, or select a vulnerability to view its details (Ultimate only), including: + - Description: Explains the cause of the vulnerability, its potential impact, and recommended remediation steps. + - Status: Indicates whether the vulnerability has been triaged or resolved. + - Severity: Categorized into six levels based on impact. + [Learn more about severity levels](../vulnerabilities/severities.md). + - Location: Shows the filename and line number where the issue was found. + Selecting the file path opens the corresponding line in the code view. + - Scanner: Identifies which analyzer detected the vulnerability. + - Identifiers: A list of references used to classify the vulnerability, such as CWE identifiers and the IDs of the rules that detected it. + +SAST vulnerabilities are named according to the primary Common Weakness Enumeration (CWE) identifier for the discovered vulnerability. +Read the description of each vulnerability finding to learn more about the specific issue that the scanner has detected. +For more information on SAST coverage, see [SAST rules](rules.md). + +## Optimization + +## Roll out + +After you are confident in the GitLab Advanced SAST results for a single project, you can extend its +implementation to additional projects. You can manually configure individual projects, using the +instructions in [Getting started](#getting-started). However, you should instead create a shared +CI/CD configuration and enforce it on the desired groups and projects. + +For more details, see [Security configuration](../detect/security_configuration.md). + ## When vulnerabilities are reported GitLab Advanced SAST uses cross-file, cross-function scanning with taint analysis to trace the flow of user input into the program. @@ -228,18 +325,6 @@ GitLab Advanced SAST can be configured using the following CI/CD variables. | `GITLAB_ADVANCED_SAST_CPP_ENABLED` | `false` | Enables GitLab Advanced SAST scanning specifically for C and C++ projects. | | `GITLAB_ADVANCED_SAST_RULE_TIMEOUT` | `30` | Timeout in seconds per rule per file. When exceeded, that analysis is skipped. | -### Requirements - -Like other GitLab SAST analyzers, the GitLab Advanced SAST analyzer requires a runner and a CI/CD pipeline; see [SAST requirements](_index.md#getting-started) for details. - -On GitLab Self-Managed, you must also use a GitLab version that supports GitLab Advanced SAST: - -- You should use GitLab 17.4 or later if possible. GitLab 17.4 includes a new code-flow view, vulnerability deduplication, and further updates to the SAST CI/CD template. -- The [SAST CI/CD templates](_index.md#stable-vs-latest-sast-templates) were updated to include GitLab Advanced SAST in the following releases: - - The stable template includes GitLab Advanced SAST in GitLab 17.3 or later. - - The latest template includes GitLab Advanced SAST in GitLab 17.2 or later. Don't mix [latest and stable templates](../detect/security_configuration.md#template-editions) in a single project. -- At a minimum, GitLab Advanced SAST requires version 17.1 or later. - ### Enable GitLab Advanced SAST scanning GitLab Advanced SAST is included in the standard GitLab SAST CI/CD template, but isn't yet enabled by default.