+
+
createComponent(IssuesDashboardApp),
});
diff --git a/app/assets/stylesheets/framework/typography.scss b/app/assets/stylesheets/framework/typography.scss
index 391ce83009e..60b127fc22b 100644
--- a/app/assets/stylesheets/framework/typography.scss
+++ b/app/assets/stylesheets/framework/typography.scss
@@ -489,14 +489,81 @@
list-style-type: none;
position: relative;
min-height: 22px;
- padding-inline-start: 28px;
+ padding-inline-start: 32px;
margin-inline-start: 0 !important;
> p > input.task-list-item-checkbox,
> input.task-list-item-checkbox {
position: absolute;
inset-inline-start: $gl-padding-8;
- inset-block-start: 5px;
+ inset-block-start: 3px;
+ }
+ }
+ }
+
+ ul[data-type=taskList] input[type=checkbox],
+ ul.task-list .task-list-item-checkbox {
+ all: unset;
+ @apply gl-w-5 gl-h-5 gl-cursor-pointer gl-box-border gl-rounded-base focus-visible:gl-focus;
+ background-color: var(--gl-control-background-color-default);
+ border: 1px solid var(--gl-control-border-color-default);
+
+ // Ensure size of the target for pointer inputs is at least 24 pixels to satisfy WCAG 2.5.8.
+ &::before {
+ content: '';
+ margin-top: calc(-#{$gl-spacing-scale-2} - 1px);
+ margin-left: calc(-#{$gl-spacing-scale-2} - 1px);
+ @apply gl-absolute gl-z-1 gl-w-6 gl-h-6 gl-bg-transparent;
+ }
+
+ &:not(:disabled):hover {
+ border-color: var(--gl-control-border-color-hover);
+ }
+
+ &:not(:disabled):focus {
+ @apply gl-focus;
+ border-color: var(--gl-control-border-color-focus);
+ }
+
+ &:checked {
+ background-color: var(--gl-control-background-color-selected-default);
+ border-color: var(--gl-control-border-color-selected-default);
+
+ &::after {
+ content: '';
+ @apply gl-absolute gl-z-2 gl-w-5 gl-h-5 gl-mt-[-1px] gl-ml-[-1px] gl-rounded-base;
+ mask: url("#{$gl-icon-check}") center center no-repeat;
+ background-color: var(--gl-control-indicator-color-selected);
+ }
+
+ @media (forced-colors: active) {
+ background-color: LinkText; // stylelint-disable-line scale-unlimited/declaration-strict-value
+ border-color: LinkText; // stylelint-disable-line scale-unlimited/declaration-strict-value
+ }
+ }
+
+ &:not(:disabled):checked:hover {
+ background-color: var(--gl-control-background-color-selected-hover);
+ border-color: var(--gl-control-border-color-selected-hover);
+ }
+
+ &:not(:disabled):checked:focus {
+ background-color: var(--gl-control-background-color-selected-focus);
+ border-color: var(--gl-control-border-color-selected-focus);
+ }
+
+ &:disabled {
+ background-color: var(--gl-control-background-color-disabled);
+ border-color: var(--gl-control-border-color-disabled);
+ @apply gl-cursor-not-allowed gl-text-disabled;
+ }
+
+ &:disabled:checked {
+ background-color: var(--gl-control-background-color-disabled);
+ border-color: var(--gl-control-border-color-disabled);
+
+ &::after {
+ background-color: var(--gl-control-indicator-color-disabled);
}
}
}
diff --git a/app/helpers/issues_helper.rb b/app/helpers/issues_helper.rb
index 70780102b6d..265e6005115 100644
--- a/app/helpers/issues_helper.rb
+++ b/app/helpers/issues_helper.rb
@@ -225,7 +225,8 @@ module IssuesHelper
is_public_visibility_restricted:
Gitlab::CurrentSettings.restricted_visibility_levels&.include?(Gitlab::VisibilityLevel::PUBLIC).to_s,
is_signed_in: current_user.present?.to_s,
- rss_path: url_for(safe_params.merge(rss_url_options))
+ rss_path: url_for(safe_params.merge(rss_url_options)),
+ is_status_feature_enabled_on_instance: Feature.enabled?(:work_item_status_feature_flag, :instance).to_s
}
end
diff --git a/db/migrate/20250617210028_remove_validate_epic_work_items_sync_worker_job_instances.rb b/db/migrate/20250617210028_remove_validate_epic_work_items_sync_worker_job_instances.rb
new file mode 100644
index 00000000000..e2176697e58
--- /dev/null
+++ b/db/migrate/20250617210028_remove_validate_epic_work_items_sync_worker_job_instances.rb
@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# See https://docs.gitlab.com/ee/development/migration_style_guide.html
+# for more information on how to write migrations for GitLab.
+
+class RemoveValidateEpicWorkItemsSyncWorkerJobInstances < Gitlab::Database::Migration[2.3]
+ DEPRECATED_JOB_CLASS = %w[
+ ValidateEpicWorkItemSyncWorker
+ ]
+ disable_ddl_transaction!
+ milestone '18.2'
+
+ def up
+ sidekiq_remove_jobs(job_klasses: DEPRECATED_JOB_CLASS)
+ end
+
+ def down; end
+end
diff --git a/db/schema_migrations/20250617210028 b/db/schema_migrations/20250617210028
new file mode 100644
index 00000000000..8c95b8c8e7a
--- /dev/null
+++ b/db/schema_migrations/20250617210028
@@ -0,0 +1 @@
+b6a20c3d430adab4ffc8f216accb11b23a56fa6e9f0a95e320beaf0ca8caa6f5
\ No newline at end of file
diff --git a/doc/development/integrations/secure.md b/doc/development/integrations/secure.md
index 6b090f0c64d..cff03d2b768 100644
--- a/doc/development/integrations/secure.md
+++ b/doc/development/integrations/secure.md
@@ -296,7 +296,7 @@ help integrators set its fields.
The format is extensively described in the documentation of
[SAST](../../user/application_security/sast/_index.md#download-a-sast-report),
[DAST](../../user/application_security/dast/browser/_index.md),
-[Dependency Scanning](../../user/application_security/dependency_scanning/_index.md#output),
+[Dependency Scanning](../../user/application_security/dependency_scanning/_index.md#understanding-the-results),
and [Container Scanning](../../user/application_security/container_scanning/_index.md#reports-json-format)
You can find the schemas for these scanners here:
diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md
index 20db2f1bfa9..aaf8bbc47df 100644
--- a/doc/development/integrations/secure_partner_integration.md
+++ b/doc/development/integrations/secure_partner_integration.md
@@ -87,7 +87,7 @@ and complete an integration with the Secure stage.
- Your report artifact must be in one of our supported formats.
For more information, see the [documentation on reports](secure.md#report).
- Documentation for [SAST output](../../user/application_security/sast/_index.md#download-a-sast-report).
- - Documentation for [Dependency Scanning reports](../../user/application_security/dependency_scanning/_index.md#output).
+ - Documentation for [Dependency Scanning reports](../../user/application_security/dependency_scanning/_index.md#understanding-the-results).
- Documentation for [Container Scanning reports](../../user/application_security/container_scanning/_index.md#reports-json-format).
- See this [example secure job definition that also defines the artifact created](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Container-Scanning.gitlab-ci.yml).
- If you need a new kind of scan or report, [create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new#)
diff --git a/doc/user/application_security/continuous_vulnerability_scanning/_index.md b/doc/user/application_security/continuous_vulnerability_scanning/_index.md
index e08fd010ebb..8635103f311 100644
--- a/doc/user/application_security/continuous_vulnerability_scanning/_index.md
+++ b/doc/user/application_security/continuous_vulnerability_scanning/_index.md
@@ -75,7 +75,7 @@ GitLab offers security analyzers that can generate a report compatible with GitL
- [Container Scanning](../container_scanning/_index.md#getting-started)
- [Container Scanning For Registry](../container_scanning/_index.md#container-scanning-for-registry)
-- [Dependency Scanning](../dependency_scanning/_index.md#configuration)
+- [Dependency Scanning](../dependency_scanning/_index.md#getting-started)
- [Dependency Scanning CI/CD Component](https://gitlab.com/explore/catalog/components/dependency-scanning) (experimental)
## Checking new vulnerabilities
diff --git a/doc/user/application_security/dependency_scanning/_index.md b/doc/user/application_security/dependency_scanning/_index.md
index d94f03e7a5a..3179ec15d3e 100644
--- a/doc/user/application_security/dependency_scanning/_index.md
+++ b/doc/user/application_security/dependency_scanning/_index.md
@@ -93,6 +93,225 @@ Dependency Scanning does not support runtime installation of compilers and inter
-
For other interactive reading and how-to demos, see [Get Started With GitLab Application Security Playlist](https://www.youtube.com/playlist?list=PL05JrBw4t0KrUrjDoefSkgZLx5aJYFaF9)
+## Getting started
+
+To get started with Dependency Scanning the following steps show how to enable Dependency Scanning for your project.
+
+Prerequisites:
+
+- The `test` stage is required in the `.gitlab-ci.yml` file.
+- With self-managed runners 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 SaaS runners on GitLab.com, this is enabled by default.
+
+To enable the analyzer, either:
+
+- Enable [Auto DevOps](../../../topics/autodevops/_index.md), which includes dependency scanning.
+- Use a preconfigured merge request.
+- Create a [scan execution policy](../policies/scan_execution_policies.md) that enforces dependency
+ scanning.
+- Edit the `.gitlab-ci.yml` file manually.
+- [Use CI/CD components](#use-cicd-components)
+
+### Use a preconfigured merge request
+
+This method automatically prepares a merge request that includes the Dependency Scanning template
+in the `.gitlab-ci.yml` file. You then merge the merge request to enable Dependency Scanning.
+
+{{< alert type="note" >}}
+
+This method works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration file.
+If you have a complex GitLab configuration file it might not be parsed successfully, and an error
+might occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manually) method instead.
+
+{{< /alert >}}
+
+To enable Dependency Scanning:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Secure > Security configuration**.
+1. In the **Dependency Scanning** row, select **Configure with a merge request**.
+1. Select **Create merge request**.
+1. Review the merge request, then select **Merge**.
+
+Pipelines now include a Dependency Scanning job.
+
+### Edit the `.gitlab-ci.yml` file manually
+
+This method requires you to manually edit the existing `.gitlab-ci.yml` file. Use this method if
+your GitLab CI/CD configuration file is complex.
+
+To enable Dependency Scanning:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Build > Pipeline editor**.
+1. If no `.gitlab-ci.yml` file exists, select **Configure pipeline**, then delete the example
+ content.
+1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file. If an `include` line
+ already exists, add only the `template` line below it.
+
+ ```yaml
+ include:
+ - template: Jobs/Dependency-Scanning.gitlab-ci.yml
+ ```
+
+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. Do not use the default branch for the **Branch** field.
+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**.
+
+Pipelines now include a Dependency Scanning job.
+
+### Use CI/CD components
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454143) in GitLab 17.0. This feature is an [experiment](../../../policy/development_stages_support.md).
+- The dependency scanning CI/CD component only supports Android projects.
+
+{{< /history >}}
+
+Use [CI/CD components](../../../ci/components/_index.md) to perform Dependency Scanning of your
+application. For instructions, see the respective component's README file.
+
+#### Available CI/CD components
+
+See
+
+After completing these steps, you can:
+
+- Learn more about how to [understand the results](#understanding-the-results).
+- Plan a [roll out](#roll-out) to more projects.
+
+## 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. Select a vulnerability to view its details, including:
+ - Status: Indicates whether the vulnerability has been triaged or resolved.
+ - Description: Explains the cause of the vulnerability, its potential impact, and recommended remediation steps.
+ - Severity: Categorized into six levels based on impact.
+ [Learn more about severity levels](../vulnerabilities/severities.md).
+ - CVSS score: Provides a numeric value that maps to severity.
+ - EPSS: Shows the likelihood of a vulnerability being exploited in the wild.
+ - Has Known Exploit (KEV): Indicates that a given vulnerability has been exploited.
+ - Project: Highlights the project where the vulnerability was identified.
+ - Report type / Scanner: Explains the output type and scanner used to generate the output.
+ - Reachable: Provides an indication whether the vulnerable dependency is used in code.
+ - Scanner: Identifies which analyzer detected the vulnerability.
+ - Location: Names the file where the vulnerable dependency is located.
+ - Links: Evidence of the vulnerability being cataloged in various advisory databases.
+ - Identifiers: A list of references used to classify the vulnerability, such as CVE identifiers.
+
+Dependency Scanning produces the following output:
+
+- **Dependency scanning report**: Contains details of all vulnerabilities detected in dependencies.
+- **CycloneDX Software Bill of Materials**: Software Bill of Materials (SBOM) for each supported
+ lock or build file detected.
+
+### Dependency scanning report
+
+Dependency scanning outputs a report containing details of all vulnerabilities. The report is
+processed internally and the results are shown in the UI. The report is also output as an artifact
+of the dependency scanning job, named `gl-dependency-scanning-report.json`.
+
+For more details of the dependency scanning report, see the
+[Dependency scanning report schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json).
+
+### CycloneDX Software Bill of Materials
+
+Dependency Scanning outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM)
+for each supported lock or build file it detects.
+
+The CycloneDX SBOMs are:
+
+- Named `gl-sbom--.cdx.json`.
+- Available as job artifacts of the dependency scanning job.
+- Saved in the same directory as the detected lock or build files.
+
+For example, if your project has the following structure:
+
+```plaintext
+.
+├── ruby-project/
+│ └── Gemfile.lock
+├── ruby-project-2/
+│ └── Gemfile.lock
+├── php-project/
+│ └── composer.lock
+└── go-project/
+ └── go.sum
+```
+
+Then the Gemnasium scanner generates the following CycloneDX SBOMs:
+
+```plaintext
+.
+├── ruby-project/
+│ ├── Gemfile.lock
+│ └── gl-sbom-gem-bundler.cdx.json
+├── ruby-project-2/
+│ ├── Gemfile.lock
+│ └── gl-sbom-gem-bundler.cdx.json
+├── php-project/
+│ ├── composer.lock
+│ └── gl-sbom-packagist-composer.cdx.json
+└── go-project/
+ ├── go.sum
+ └── gl-sbom-go-go.cdx.json
+```
+
+#### Merging multiple CycloneDX SBOMs
+
+You can use a CI/CD job to merge the multiple CycloneDX SBOMs into a single SBOM. GitLab uses
+[CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store) to store
+implementation-specific details in the metadata of each CycloneDX SBOM, such as the location of
+build and lock files. If multiple CycloneDX SBOMs are merged together, this information is removed
+from the resulting merged file.
+
+For example, the following `.gitlab-ci.yml` extract demonstrates how the Cyclone SBOM files can be
+merged, and the resulting file validated.
+
+```yaml
+stages:
+ - test
+ - merge-cyclonedx-sboms
+
+include:
+ - template: Jobs/Dependency-Scanning.gitlab-ci.yml
+
+merge cyclonedx sboms:
+ stage: merge-cyclonedx-sboms
+ image:
+ name: cyclonedx/cyclonedx-cli:0.25.1
+ entrypoint: [""]
+ script:
+ - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
+ # optional: validate the merged sbom
+ - cyclonedx validate --input-version v1_4 --input-file gl-sbom-all.cdx.json
+ artifacts:
+ paths:
+ - gl-sbom-all.cdx.json
+```
+
+## Roll out
+
+After you are confident in the Dependency Scanning results for a single project, you can extend its implementation to additional projects:
+
+- Use [enforced scan execution](../detect/security_configuration.md#create-a-shared-configuration) to apply Dependency Scannign settings across groups.
+- If you have unique requirements, Dependency Scanning with SBOM can be run in [offline environments](../offline_deployments/_index.md).
+
## Supported languages and package managers
The following languages and dependency managers are supported by Dependency Scanning:
@@ -339,6 +558,413 @@ The following languages and dependency managers are supported by Dependency Scan
+### Running jobs in merge request pipelines
+
+See [Use security scanning tools with merge request pipelines](../detect/security_configuration.md#use-security-scanning-tools-with-merge-request-pipelines)
+
+### Customizing analyzer behavior
+
+To customize Dependency Scanning, use [CI/CD variables](#available-cicd-variables).
+
+{{< alert type="warning" >}}
+
+Test all customization of GitLab analyzers in a merge request before merging these changes to the
+default branch. Failure to do so can give unexpected results, including a large number of false
+positives.
+
+{{< /alert >}}
+
+### Overriding dependency scanning jobs
+
+To override a job definition (for example, to change properties like `variables` or `dependencies`),
+declare a new job with the same name as the one to override. Place this new job after the template
+inclusion and specify any additional keys under it. For example, this disables `DS_REMEDIATE` for
+the `gemnasium` analyzer:
+
+```yaml
+include:
+ - template: Jobs/Dependency-Scanning.gitlab-ci.yml
+
+gemnasium-dependency_scanning:
+ variables:
+ DS_REMEDIATE: "false"
+```
+
+To override the `dependencies: []` attribute, add an override job as described previously, targeting this attribute:
+
+```yaml
+include:
+ - template: Jobs/Dependency-Scanning.gitlab-ci.yml
+
+gemnasium-dependency_scanning:
+ dependencies: ["build"]
+```
+
+### Available CI/CD variables
+
+You can use CI/CD variables to [customize](#customizing-analyzer-behavior) dependency scanning behavior.
+
+#### Global analyzer settings
+
+The following variables allow configuration of global dependency scanning settings.
+
+| CI/CD variables | Description |
+| ----------------------------|------------ |
+| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certificates to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. For more details, see [Custom TLS certificate authority](#custom-tls-certificate-authority). |
+| `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Analyzers](#analyzers). |
+| `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. This is a pre-filter which is applied before the scan is executed. Default: `"spec, test, tests, tmp"`. |
+| `DS_IMAGE_SUFFIX` | Suffix added to the image name. (GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796`). Automatically set to `"-fips"` when FIPS mode is enabled. |
+| `DS_MAX_DEPTH` | Defines how many directory levels deep that the analyzer should search for supported files to scan. A value of `-1` scans all directories regardless of depth. Default: `2`. |
+| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). |
+
+#### Analyzer-specific settings
+
+The following variables configure the behavior of specific dependency scanning analyzers.
+
+| CI/CD variable | Analyzer | Default | Description |
+|--------------------------------------|--------------------|------------------------------|-------------|
+| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. |
+| `GEMNASIUM_DB_UPDATE_DISABLED` | `gemnasium` | `"false"` | Disable automatic updates for the `gemnasium-db` advisory database. For usage see [Access to the GitLab Advisory Database](#access-to-the-gitlab-advisory-database). |
+| `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the GitLab Advisory Database. |
+| `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. |
+| `GEMNASIUM_IGNORED_SCOPES` | `gemnasium` | | Comma-separated list of Maven dependency scopes to ignore. For more details, see the [Maven dependency scope documentation](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Scope) |
+| `DS_REMEDIATE` | `gemnasium` | `"true"`, `"false"` in FIPS mode | Enable automatic remediation of vulnerable dependencies. Not supported in FIPS mode. |
+| `DS_REMEDIATE_TIMEOUT` | `gemnasium` | `5m` | Timeout for auto-remediation. |
+| `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries (libraries which are not managed by a package manager). This functionality requires a JavaScript lockfile to be present in a commit, otherwise Dependency Scanning is not executed and vendored files are not scanned. Dependency scanning uses the [Retire.js](https://github.com/RetireJS/retire.js) scanner to detect a limited set of vulnerabilities. For details of which vulnerabilities are detected, see the [Retire.js repository](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json). |
+| `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only projects using Composer, Maven, npm, pnpm, Pipenv or Poetry are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. |
+| `GOOS` | `gemnasium` | `"linux"` | The operating system for which to compile Go code. |
+| `GOARCH` | `gemnasium` | `"amd64"` | The architecture of the processor for which to compile Go code. |
+| `GOFLAGS` | `gemnasium` | | The flags passed to the `go build` tool. |
+| `GOPRIVATE` | `gemnasium` | | A list of glob patterns and prefixes to be fetched from source. For more information, see the Go private modules [documentation](https://go.dev/ref/mod#private-modules). |
+| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`, `21`. |
+| `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](#authenticate-with-a-private-maven-repository). |
+| `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. |
+| `GRADLE_PLUGIN_INIT_PATH` | `gemnasium-maven` | `"gemnasium-init.gradle"` | Specifies the path to the Gradle initialization script. The init script must include `allprojects { apply plugin: 'project-report' }` to ensure compatibility. |
+| `DS_GRADLE_RESOLUTION_POLICY` | `gemnasium-maven` | `"failed"` | Controls Gradle dependency resolution strictness. Accepts `"none"` to allow partial results, or `"failed"` to fail the scan when any dependencies fail to resolve. |
+| `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. |
+| `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. |
+| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. **Warning**: Read [the following security consideration](#python-projects) when using this environment variable. |
+| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. This is a filename and not a path. When this environment variable is set only the specified file is scanned. |
+| `PIPENV_PYPI_MIRROR` | `gemnasium-python` | | If set, overrides the PyPi index used by Pipenv with a [mirror](https://github.com/pypa/pipenv/blob/v2022.1.8/pipenv/environments.py#L263). |
+| `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. |
+| `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. |
+
+#### Other variables
+
+The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they do work. This is a large list, many of which we may be unaware of, and as such is not documented.
+
+For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs,
+set it as a [CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/_index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file)
+file like this:
+
+```yaml
+variables:
+ HTTPS_PROXY: "https://squid-proxy:3128"
+```
+
+{{< alert type="note" >}}
+
+Gradle projects require [an additional variable](#using-a-proxy-with-gradle-projects) setup to use a proxy.
+
+{{< /alert >}}
+
+Alternatively we may use it in specific jobs, like Dependency Scanning:
+
+```yaml
+dependency_scanning:
+ variables:
+ HTTPS_PROXY: $HTTPS_PROXY
+```
+
+As we have not tested all variables you may find some do work and others do not.
+If one does not work and you need it we suggest
+[submitting a feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed&issue[title]=Docs%20feedback%20-%20feature%20proposal:%20Write%20your%20title)
+or contributing to the code to enable it to be used.
+
+### Custom TLS certificate authority
+
+Dependency Scanning allows for use of custom TLS certificates for SSL/TLS connections instead of the
+default shipped with the analyzer container image.
+
+Support for custom certificate authorities was introduced in the following versions.
+
+| Analyzer | Version |
+|--------------------|--------------------------------------------------------------------------------------------------------|
+| `gemnasium` | [v2.8.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/releases/v2.8.0) |
+| `gemnasium-maven` | [v2.9.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/releases/v2.9.0) |
+| `gemnasium-python` | [v2.7.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/releases/v2.7.0) |
+
+#### Using a custom TLS certificate authority
+
+To use a custom TLS certificate authority, assign the
+[text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1)
+to the CI/CD variable `ADDITIONAL_CA_CERT_BUNDLE`.
+
+For example, to configure the certificate in the `.gitlab-ci.yml` file:
+
+```yaml
+variables:
+ ADDITIONAL_CA_CERT_BUNDLE: |
+ -----BEGIN CERTIFICATE-----
+ MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
+ ...
+ jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
+ -----END CERTIFICATE-----
+```
+
+### Authenticate with a private Maven repository
+
+To use a private Maven repository that requires authentication, you should store your credentials in
+a CI/CD variable and reference them in your Maven settings file. Do not add the credentials to your
+`.gitlab-ci.yml` file.
+
+To authenticate with a private Maven repository:
+
+1. Add the `MAVEN_CLI_OPTS` CI/CD variable to your
+ [project's settings](../../../ci/variables/_index.md#for-a-project), setting the value to include
+ your credentials.
+
+ For example, if your username is `myuser` and the password is `verysecret`:
+
+ | Type | Key | Value |
+ |----------|------------------|-------|
+ | Variable | `MAVEN_CLI_OPTS` | `--settings mysettings.xml -Drepository.password=verysecret -Drepository.user=myuser` |
+
+1. Create a Maven settings file with your server configuration.
+
+ For example, add the following to the settings file `mysettings.xml`. This file is referenced in
+ the `MAVEN_CLI_OPTS` CI/CD variable.
+
+ ```xml
+
+
+ ...
+
+
+ private_server
+ ${repository.user}
+ ${repository.password}
+
+
+
+ ```
+
+### FIPS-enabled images
+
+{{< history >}}
+
+- Introduced in GitLab 15.0 - Gemnasium uses FIPS-enabled images when FIPS mode is enabled.
+
+{{< /history >}}
+
+GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image)
+versions of the Gemnasium images. When FIPS mode is enabled in the GitLab instance, Gemnasium
+scanning jobs automatically use the FIPS-enabled images. To manually switch to FIPS-enabled images,
+set the variable `DS_IMAGE_SUFFIX` to `"-fips"`.
+
+Dependency scanning for Gradle projects and auto-remediation for Yarn projects are not supported in FIPS mode.
+
+FIPS-enabled images are based on RedHat's UBI micro.
+They don't have package managers such as `dnf` or `microdnf`
+so it's not possible to install system packages at runtime.
+
+### Offline environment
+
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab Self-Managed
+
+{{< /details >}}
+
+For instances in an environment with limited, restricted, or intermittent access
+to external resources through the internet, some adjustments are required for dependency scanning
+jobs to run successfully. For more information, see [Offline environments](../offline_deployments/_index.md).
+
+#### Requirements
+
+To run dependency scanning in an offline environment you must have:
+
+- A GitLab Runner with the `docker` or `kubernetes` executor
+- Local copies of the dependency scanning analyzer images
+- Access to the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db)
+- Access to the [Package Metadata Database](../../../topics/offline/quick_start_guide.md#enabling-the-package-metadata-database)
+
+#### Local copies of analyzer images
+
+To use dependency scanning with all [supported languages and frameworks](#supported-languages-and-package-managers):
+
+1. Import the following default dependency scanning analyzer images from `registry.gitlab.com` into
+ your [local Docker container registry](../../packages/container_registry/_index.md):
+
+ ```plaintext
+ registry.gitlab.com/security-products/gemnasium:6
+ registry.gitlab.com/security-products/gemnasium:6-fips
+ registry.gitlab.com/security-products/gemnasium-maven:6
+ registry.gitlab.com/security-products/gemnasium-maven:6-fips
+ registry.gitlab.com/security-products/gemnasium-python:6
+ registry.gitlab.com/security-products/gemnasium-python:6-fips
+ ```
+
+ The process for importing Docker images into a local offline Docker registry depends on
+ **your network security policy**. Consult your IT staff to find an accepted and approved
+ process by which external resources can be imported or temporarily accessed.
+ These scanners are [periodically updated](../detect/vulnerability_scanner_maintenance.md)
+ with new definitions, and you may want to download them regularly.
+
+1. Configure GitLab CI/CD to use the local analyzers.
+
+ Set the value of the CI/CD variable `SECURE_ANALYZERS_PREFIX` to your local Docker registry - in
+ this example, `docker-registry.example.com`.
+
+ ```yaml
+ include:
+ - template: Jobs/Dependency-Scanning.gitlab-ci.yml
+
+ variables:
+ SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"
+ ```
+
+#### Access to the GitLab Advisory Database
+
+The [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is the
+source of vulnerability data used by the `gemnasium`, `gemnasium-maven`, and `gemnasium-python`
+analyzers. The Docker images of these analyzers include a clone of the database.
+The clone is synchronized with the database before starting a scan,
+to ensure the analyzers have the latest vulnerability data.
+
+In an offline environment, the default host of the GitLab Advisory Database can't be accessed.
+Instead, you must host the database somewhere that it is accessible to the GitLab runners. You must
+also update the database manually at your own schedule.
+
+Available options for hosting the database are:
+
+- [Use a clone of the GitLab Advisory Database](#use-a-copy-of-the-gitlab-advisory-database).
+- [Use a copy of the GitLab Advisory Database](#use-a-copy-of-the-gitlab-advisory-database).
+
+##### Use a clone of the GitLab Advisory Database
+
+Using a clone of the GitLab Advisory Database is recommended because it is the most efficient
+method.
+
+To host a clone of the GitLab Advisory Database:
+
+1. Clone the GitLab Advisory Database to a host that is accessible by HTTP from the GitLab runners.
+1. In your `.gitlab-ci.yml` file, set the value of the CI/CD variable `GEMNASIUM_DB_REMOTE_URL` to
+ the URL of the Git repository.
+
+For example:
+
+```yaml
+variables:
+ GEMNASIUM_DB_REMOTE_URL: https://users-own-copy.example.com/gemnasium-db.git
+```
+
+##### Use a copy of the GitLab Advisory Database
+
+Using a copy of the GitLab Advisory Database requires you to host an archive file which is
+downloaded by the analyzers.
+
+To use a copy of the GitLab Advisory Database:
+
+1. Download an archive of the GitLab Advisory Database to a host that is accessible by HTTP from the
+ GitLab runners. The archive is located at
+ `https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/archive/master/gemnasium-db-master.tar.gz`.
+1. Update your `.gitlab-ci.yml` file.
+
+ - Set CI/CD variable `GEMNASIUM_DB_LOCAL_PATH` to use the local copy of the database.
+ - Set CI/CD variable `GEMNASIUM_DB_UPDATE_DISABLED` to disable the database update.
+ - Download and extract the advisory database before the scan begins.
+
+ ```yaml
+ variables:
+ GEMNASIUM_DB_LOCAL_PATH: ./gemnasium-db-local
+ GEMNASIUM_DB_UPDATE_DISABLED: "true"
+
+ dependency_scanning:
+ before_script:
+ - wget https://local.example.com/gemnasium_db.tar.gz
+ - mkdir -p $GEMNASIUM_DB_LOCAL_PATH
+ - tar -xzvf gemnasium_db.tar.gz --strip-components=1 -C $GEMNASIUM_DB_LOCAL_PATH
+ ```
+
+### Using a proxy with Gradle projects
+
+The Gradle wrapper script does not read the `HTTP(S)_PROXY` environment variables. See [this upstream issue](https://github.com/gradle/gradle/issues/11065).
+
+To make the Gradle wrapper script use a proxy, you can specify the options using the `GRADLE_CLI_OPTS` CI/CD variable:
+
+```yaml
+variables:
+ GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost"
+```
+
+### Using a proxy with Maven projects
+
+Maven does not read the `HTTP(S)_PROXY` environment variables.
+
+To make the Maven dependency scanner use a proxy, you can configure it using a `settings.xml` file (see [Maven documentation](https://maven.apache.org/guides/mini/guide-proxies.html)) and instruct Maven to use this configuration by using the `MAVEN_CLI_OPTS` CI/CD variable:
+
+```yaml
+variables:
+ MAVEN_CLI_OPTS: "--settings mysettings.xml"
+```
+
+### Specific settings for languages and package managers
+
+See the following sections for configuring specific languages and package managers.
+
+#### Python (pip)
+
+If you need to install Python packages before the analyzer runs, you should use `pip install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies.
+
+#### Python (setuptools)
+
+If you need to install Python packages before the analyzer runs, you should use `python setup.py install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies.
+
+When using self-signed certificates for your private PyPi repository, no extra job configuration (aside
+from the previous `.gitlab-ci.yml` template) is needed. However, you must update your `setup.py` to
+ensure that it can reach your private repository. Here is an example configuration:
+
+1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each
+ dependency in the `install_requires` list:
+
+ ```python
+ install_requires=['pyparsing>=2.0.3'],
+ dependency_links=['https://pypi.example.com/simple/pyparsing'],
+ ```
+
+1. Fetch the certificate from your repository URL and add it to the project:
+
+ ```shell
+ printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt
+ ```
+
+1. Point `setup.py` at the newly downloaded certificate:
+
+ ```python
+ import setuptools.ssl_support
+ setuptools.ssl_support.cert_paths = ['internal.crt']
+ ```
+
+#### Python (Pipenv)
+
+If running in a limited network connectivity environment, you must configure the `PIPENV_PYPI_MIRROR`
+variable to use a private PyPi mirror. This mirror must contain both default and development dependencies.
+
+```yaml
+variables:
+ PIPENV_PYPI_MIRROR: https://pypi.example.com/simple
+```
+
+
+Alternatively, if it's not possible to use a private registry, you can load the required packages
+into the Pipenv virtual environment cache. For this option, the project must check in the
+`Pipfile.lock` into the repository, and load both default and development packages into the cache.
+See the example [python-pipenv](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/41cc017bd1ed302f6edebcfa3bc2922f428e07b6/.gitlab-ci.yml#L20-42)
+project for an example of how this can be done.
+
+
## Dependency detection
Dependency Scanning automatically detects the languages used in the repository. All analyzers
@@ -653,7 +1279,7 @@ To support the following package managers, the GitLab analyzers proceed in two s
-### How analyzers are triggered
+## How analyzers are triggered
GitLab relies on [`rules:exists`](../../../ci/yaml/_index.md#rulesexists) to start the relevant analyzers for the languages detected by the presence of the
[supported files](#supported-languages-and-package-managers) in the repository.
@@ -662,7 +1288,7 @@ A maximum of two directory levels from the repository's root is searched. For ex
`api/Gemfile`, or `api/client/Gemfile`, but not if the only supported dependency file is
`api/v1/client/Gemfile`.
-### How multiple files are processed
+## How multiple files are processed
{{< alert type="note" >}}
@@ -671,7 +1297,7 @@ If you've run into problems while scanning multiple files, contribute a comment
{{< /alert >}}
-#### Python
+### Python
We only execute one installation in the directory where either a requirements file or a lock file has been detected. Dependencies are only analyzed by `gemnasium-python` for the first file that is detected. Files are searched for in the following order:
@@ -682,7 +1308,7 @@ We only execute one installation in the directory where either a requirements fi
The search begins with the root directory and then continues with subdirectories if no builds are found in the root directory. Consequently a Poetry lock file in the root directory would be detected before a Pipenv file in a subdirectory.
-#### Java and Scala
+### Java and Scala
We only execute one build in the directory where a build file has been detected. For large projects that include
multiple Gradle, Maven, or sbt builds, or any combination of these, `gemnasium-maven` only analyzes dependencies for the first build file
@@ -695,7 +1321,7 @@ that is detected. Build files are searched for in the following order:
The search begins with the root directory and then continues with subdirectories if no builds are found in the root directory. Consequently an sbt build file in the root directory would be detected before a Gradle build file in a subdirectory.
For [multi-module](https://maven.apache.org/pom.html#Aggregation) Maven projects, and multi-project [Gradle](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html) and [sbt](https://www.scala-sbt.org/1.x/docs/Multi-Project.html) builds, sub-module and sub-project files are analyzed if they are declared in the parent build file.
-#### JavaScript
+### JavaScript
The following analyzers are executed, each of which have different behavior when processing multiple files:
@@ -711,18 +1337,18 @@ The following analyzers are executed, each of which have different behavior when
The `gemnasium` analyzer scans supports JavaScript projects for vendored libraries
(that is, those checked into the project but not managed by the package manager).
-#### Go
+### Go
Multiple files are supported. When a `go.mod` file is detected, the analyzer attempts to generate a [build list](https://go.dev/ref/mod#glos-build-list) using
[Minimal Version Selection](https://go.dev/ref/mod#glos-minimal-version-selection). If this fails, the analyzer instead attempts to parse the dependencies within the `go.mod` file.
As a requirement, the `go.mod` file should be cleaned up using the command `go mod tidy` to ensure proper management of dependencies. The process is repeated for every detected `go.mod` file.
-#### PHP, C, C++, .NET, C#, Ruby, JavaScript
+### PHP, C, C++, .NET, C#, Ruby, JavaScript
The analyzer for these languages supports multiple lockfiles.
-#### Support for additional languages
+### Support for additional languages
Support for additional languages, dependency managers, and dependency files are tracked in the following issues:
@@ -730,612 +1356,6 @@ Support for additional languages, dependency managers, and dependency files are
| ------------------- | --------- | --------------- | ---------- | ----- |
| [Poetry](https://python-poetry.org/) | Python | `pyproject.toml` | [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) | [GitLab#32774](https://gitlab.com/gitlab-org/gitlab/-/issues/32774) |
-## Configuration
-
-Enable the dependency scanning analyzer to ensure it scans your application's dependencies for known
-vulnerabilities. You can then adjust its behavior by using CI/CD variables.
-
-### Enabling the analyzer
-
-Prerequisites:
-
-- The `test` stage is required in the `.gitlab-ci.yml` file.
-- With self-managed runners 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 SaaS runners on GitLab.com, this is enabled by default.
-
-To enable the analyzer, either:
-
-- Enable [Auto DevOps](../../../topics/autodevops/_index.md), which includes dependency scanning.
-- Use a preconfigured merge request.
-- Create a [scan execution policy](../policies/scan_execution_policies.md) that enforces dependency
- scanning.
-- Edit the `.gitlab-ci.yml` file manually.
-- [Use CI/CD components](#use-cicd-components)
-
-#### Use a preconfigured merge request
-
-This method automatically prepares a merge request that includes the Dependency Scanning template
-in the `.gitlab-ci.yml` file. You then merge the merge request to enable Dependency Scanning.
-
-{{< alert type="note" >}}
-
-This method works best with no existing `.gitlab-ci.yml` file, or with a minimal configuration file.
-If you have a complex GitLab configuration file it might not be parsed successfully, and an error
-might occur. In that case, use the [manual](#edit-the-gitlab-ciyml-file-manually) method instead.
-
-{{< /alert >}}
-
-To enable Dependency Scanning:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Secure > Security configuration**.
-1. In the **Dependency Scanning** row, select **Configure with a merge request**.
-1. Select **Create merge request**.
-1. Review the merge request, then select **Merge**.
-
-Pipelines now include a Dependency Scanning job.
-
-#### Edit the `.gitlab-ci.yml` file manually
-
-This method requires you to manually edit the existing `.gitlab-ci.yml` file. Use this method if
-your GitLab CI/CD configuration file is complex.
-
-To enable Dependency Scanning:
-
-1. On the left sidebar, select **Search or go to** and find your project.
-1. Select **Build > Pipeline editor**.
-1. If no `.gitlab-ci.yml` file exists, select **Configure pipeline**, then delete the example
- content.
-1. Copy and paste the following to the bottom of the `.gitlab-ci.yml` file. If an `include` line
- already exists, add only the `template` line below it.
-
- ```yaml
- include:
- - template: Jobs/Dependency-Scanning.gitlab-ci.yml
- ```
-
-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. Do not use the default branch for the **Branch** field.
-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**.
-
-Pipelines now include a Dependency Scanning job.
-
-#### Use CI/CD components
-
-{{< history >}}
-
-- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/454143) in GitLab 17.0. This feature is an [experiment](../../../policy/development_stages_support.md).
-- The dependency scanning CI/CD component only supports Android projects.
-
-{{< /history >}}
-
-Use [CI/CD components](../../../ci/components/_index.md) to perform Dependency Scanning of your
-application. For instructions, see the respective component's README file.
-
-##### Available CI/CD components
-
-See
-
-### Running jobs in merge request pipelines
-
-See [Use security scanning tools with merge request pipelines](../detect/security_configuration.md#use-security-scanning-tools-with-merge-request-pipelines)
-
-### Customizing analyzer behavior
-
-To customize Dependency Scanning, use [CI/CD variables](#available-cicd-variables).
-
-{{< alert type="warning" >}}
-
-Test all customization of GitLab analyzers in a merge request before merging these changes to the
-default branch. Failure to do so can give unexpected results, including a large number of false
-positives.
-
-{{< /alert >}}
-
-### Overriding dependency scanning jobs
-
-To override a job definition (for example, to change properties like `variables` or `dependencies`),
-declare a new job with the same name as the one to override. Place this new job after the template
-inclusion and specify any additional keys under it. For example, this disables `DS_REMEDIATE` for
-the `gemnasium` analyzer:
-
-```yaml
-include:
- - template: Jobs/Dependency-Scanning.gitlab-ci.yml
-
-gemnasium-dependency_scanning:
- variables:
- DS_REMEDIATE: "false"
-```
-
-To override the `dependencies: []` attribute, add an override job as described previously, targeting this attribute:
-
-```yaml
-include:
- - template: Jobs/Dependency-Scanning.gitlab-ci.yml
-
-gemnasium-dependency_scanning:
- dependencies: ["build"]
-```
-
-### Available CI/CD variables
-
-You can use CI/CD variables to [customize](#customizing-analyzer-behavior) dependency scanning behavior.
-
-#### Global analyzer settings
-
-The following variables allow configuration of global dependency scanning settings.
-
-| CI/CD variables | Description |
-| ----------------------------|------------ |
-| `ADDITIONAL_CA_CERT_BUNDLE` | Bundle of CA certificates to trust. The bundle of certificates provided here is also used by other tools during the scanning process, such as `git`, `yarn`, or `npm`. For more details, see [Custom TLS certificate authority](#custom-tls-certificate-authority). |
-| `DS_EXCLUDED_ANALYZERS` | Specify the analyzers (by name) to exclude from Dependency Scanning. For more information, see [Analyzers](#analyzers). |
-| `DS_EXCLUDED_PATHS` | Exclude files and directories from the scan based on the paths. A comma-separated list of patterns. Patterns can be globs (see [`doublestar.Match`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4@v4.0.2#Match) for supported patterns), or file or folder paths (for example, `doc,spec`). Parent directories also match patterns. This is a pre-filter which is applied before the scan is executed. Default: `"spec, test, tests, tmp"`. |
-| `DS_IMAGE_SUFFIX` | Suffix added to the image name. (GitLab team members can view more information in this confidential issue: `https://gitlab.com/gitlab-org/gitlab/-/issues/354796`). Automatically set to `"-fips"` when FIPS mode is enabled. |
-| `DS_MAX_DEPTH` | Defines how many directory levels deep that the analyzer should search for supported files to scan. A value of `-1` scans all directories regardless of depth. Default: `2`. |
-| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). |
-
-#### Analyzer-specific settings
-
-The following variables configure the behavior of specific dependency scanning analyzers.
-
-| CI/CD variable | Analyzer | Default | Description |
-|--------------------------------------|--------------------|------------------------------|-------------|
-| `GEMNASIUM_DB_LOCAL_PATH` | `gemnasium` | `/gemnasium-db` | Path to local Gemnasium database. |
-| `GEMNASIUM_DB_UPDATE_DISABLED` | `gemnasium` | `"false"` | Disable automatic updates for the `gemnasium-db` advisory database. For usage see [Access to the GitLab Advisory Database](#access-to-the-gitlab-advisory-database). |
-| `GEMNASIUM_DB_REMOTE_URL` | `gemnasium` | `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git` | Repository URL for fetching the GitLab Advisory Database. |
-| `GEMNASIUM_DB_REF_NAME` | `gemnasium` | `master` | Branch name for remote repository database. `GEMNASIUM_DB_REMOTE_URL` is required. |
-| `GEMNASIUM_IGNORED_SCOPES` | `gemnasium` | | Comma-separated list of Maven dependency scopes to ignore. For more details, see the [Maven dependency scope documentation](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Dependency_Scope) |
-| `DS_REMEDIATE` | `gemnasium` | `"true"`, `"false"` in FIPS mode | Enable automatic remediation of vulnerable dependencies. Not supported in FIPS mode. |
-| `DS_REMEDIATE_TIMEOUT` | `gemnasium` | `5m` | Timeout for auto-remediation. |
-| `GEMNASIUM_LIBRARY_SCAN_ENABLED` | `gemnasium` | `"true"` | Enable detecting vulnerabilities in vendored JavaScript libraries (libraries which are not managed by a package manager). This functionality requires a JavaScript lockfile to be present in a commit, otherwise Dependency Scanning is not executed and vendored files are not scanned. Dependency scanning uses the [Retire.js](https://github.com/RetireJS/retire.js) scanner to detect a limited set of vulnerabilities. For details of which vulnerabilities are detected, see the [Retire.js repository](https://github.com/RetireJS/retire.js/blob/master/repository/jsrepository.json). |
-| `DS_INCLUDE_DEV_DEPENDENCIES` | `gemnasium` | `"true"` | When set to `"false"`, development dependencies and their vulnerabilities are not reported. Only projects using Composer, Maven, npm, pnpm, Pipenv or Poetry are supported. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/227861) in GitLab 15.1. |
-| `GOOS` | `gemnasium` | `"linux"` | The operating system for which to compile Go code. |
-| `GOARCH` | `gemnasium` | `"amd64"` | The architecture of the processor for which to compile Go code. |
-| `GOFLAGS` | `gemnasium` | | The flags passed to the `go build` tool. |
-| `GOPRIVATE` | `gemnasium` | | A list of glob patterns and prefixes to be fetched from source. For more information, see the Go private modules [documentation](https://go.dev/ref/mod#private-modules). |
-| `DS_JAVA_VERSION` | `gemnasium-maven` | `17` | Version of Java. Available versions: `8`, `11`, `17`, `21`. |
-| `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](#authenticate-with-a-private-maven-repository). |
-| `GRADLE_CLI_OPTS` | `gemnasium-maven` | | List of command line arguments that are passed to `gradle` by the analyzer. |
-| `GRADLE_PLUGIN_INIT_PATH` | `gemnasium-maven` | `"gemnasium-init.gradle"` | Specifies the path to the Gradle initialization script. The init script must include `allprojects { apply plugin: 'project-report' }` to ensure compatibility. |
-| `DS_GRADLE_RESOLUTION_POLICY` | `gemnasium-maven` | `"failed"` | Controls Gradle dependency resolution strictness. Accepts `"none"` to allow partial results, or `"failed"` to fail the scan when any dependencies fail to resolve. |
-| `SBT_CLI_OPTS` | `gemnasium-maven` | | List of command-line arguments that the analyzer passes to `sbt`. |
-| `PIP_INDEX_URL` | `gemnasium-python` | `https://pypi.org/simple` | Base URL of Python Package Index. |
-| `PIP_EXTRA_INDEX_URL` | `gemnasium-python` | | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma-separated. **Warning**: Read [the following security consideration](#python-projects) when using this environment variable. |
-| `PIP_REQUIREMENTS_FILE` | `gemnasium-python` | | Pip requirements file to be scanned. This is a filename and not a path. When this environment variable is set only the specified file is scanned. |
-| `PIPENV_PYPI_MIRROR` | `gemnasium-python` | | If set, overrides the PyPi index used by Pipenv with a [mirror](https://github.com/pypa/pipenv/blob/v2022.1.8/pipenv/environments.py#L263). |
-| `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. |
-| `DS_PIP_DEPENDENCY_PATH` | `gemnasium-python` | | Path to load Python pip dependencies from. |
-
-#### Other variables
-
-The previous tables are not an exhaustive list of all variables that can be used. They contain all specific GitLab and analyzer variables we support and test. There are many variables, such as environment variables, that you can pass in and they do work. This is a large list, many of which we may be unaware of, and as such is not documented.
-
-For example, to pass the non-GitLab environment variable `HTTPS_PROXY` to all Dependency Scanning jobs,
-set it as a [CI/CD variable in your `.gitlab-ci.yml`](../../../ci/variables/_index.md#define-a-cicd-variable-in-the-gitlab-ciyml-file)
-file like this:
-
-```yaml
-variables:
- HTTPS_PROXY: "https://squid-proxy:3128"
-```
-
-{{< alert type="note" >}}
-
-Gradle projects require [an additional variable](#using-a-proxy-with-gradle-projects) setup to use a proxy.
-
-{{< /alert >}}
-
-Alternatively we may use it in specific jobs, like Dependency Scanning:
-
-```yaml
-dependency_scanning:
- variables:
- HTTPS_PROXY: $HTTPS_PROXY
-```
-
-As we have not tested all variables you may find some do work and others do not.
-If one does not work and you need it we suggest
-[submitting a feature request](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Feature%20proposal%20-%20detailed&issue[title]=Docs%20feedback%20-%20feature%20proposal:%20Write%20your%20title)
-or contributing to the code to enable it to be used.
-
-### Custom TLS certificate authority
-
-Dependency Scanning allows for use of custom TLS certificates for SSL/TLS connections instead of the
-default shipped with the analyzer container image.
-
-Support for custom certificate authorities was introduced in the following versions.
-
-| Analyzer | Version |
-|--------------------|--------------------------------------------------------------------------------------------------------|
-| `gemnasium` | [v2.8.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium/-/releases/v2.8.0) |
-| `gemnasium-maven` | [v2.9.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-maven/-/releases/v2.9.0) |
-| `gemnasium-python` | [v2.7.0](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium-python/-/releases/v2.7.0) |
-
-#### Using a custom TLS certificate authority
-
-To use a custom TLS certificate authority, assign the
-[text representation of the X.509 PEM public-key certificate](https://www.rfc-editor.org/rfc/rfc7468#section-5.1)
-to the CI/CD variable `ADDITIONAL_CA_CERT_BUNDLE`.
-
-For example, to configure the certificate in the `.gitlab-ci.yml` file:
-
-```yaml
-variables:
- ADDITIONAL_CA_CERT_BUNDLE: |
- -----BEGIN CERTIFICATE-----
- MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
- ...
- jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
- -----END CERTIFICATE-----
-```
-
-### Authenticate with a private Maven repository
-
-To use a private Maven repository that requires authentication, you should store your credentials in
-a CI/CD variable and reference them in your Maven settings file. Do not add the credentials to your
-`.gitlab-ci.yml` file.
-
-To authenticate with a private Maven repository:
-
-1. Add the `MAVEN_CLI_OPTS` CI/CD variable to your
- [project's settings](../../../ci/variables/_index.md#for-a-project), setting the value to include
- your credentials.
-
- For example, if your username is `myuser` and the password is `verysecret`:
-
- | Type | Key | Value |
- |----------|------------------|-------|
- | Variable | `MAVEN_CLI_OPTS` | `--settings mysettings.xml -Drepository.password=verysecret -Drepository.user=myuser` |
-
-1. Create a Maven settings file with your server configuration.
-
- For example, add the following to the settings file `mysettings.xml`. This file is referenced in
- the `MAVEN_CLI_OPTS` CI/CD variable.
-
- ```xml
-
-
- ...
-
-
- private_server
- ${repository.user}
- ${repository.password}
-
-
-
- ```
-
-### FIPS-enabled images
-
-{{< history >}}
-
-- Introduced in GitLab 15.0 - Gemnasium uses FIPS-enabled images when FIPS mode is enabled.
-
-{{< /history >}}
-
-GitLab also offers [FIPS-enabled Red Hat UBI](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image)
-versions of the Gemnasium images. When FIPS mode is enabled in the GitLab instance, Gemnasium
-scanning jobs automatically use the FIPS-enabled images. To manually switch to FIPS-enabled images,
-set the variable `DS_IMAGE_SUFFIX` to `"-fips"`.
-
-Dependency scanning for Gradle projects and auto-remediation for Yarn projects are not supported in FIPS mode.
-
-FIPS-enabled images are based on RedHat's UBI micro.
-They don't have package managers such as `dnf` or `microdnf`
-so it's not possible to install system packages at runtime.
-
-## Output
-
-Dependency Scanning produces the following output:
-
-- **Dependency scanning report**: Contains details of all vulnerabilities detected in dependencies.
-- **CycloneDX Software Bill of Materials**: Software Bill of Materials (SBOM) for each supported
- lock or build file detected.
-
-### Dependency scanning report
-
-Dependency scanning outputs a report containing details of all vulnerabilities. The report is
-processed internally and the results are shown in the UI. The report is also output as an artifact
-of the dependency scanning job, named `gl-dependency-scanning-report.json`.
-
-For more details of the dependency scanning report, see the
-[Dependency scanning report schema](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/dependency-scanning-report-format.json).
-
-### CycloneDX Software Bill of Materials
-
-{{< history >}}
-
-- Generally available in GitLab 15.7.
-
-{{< /history >}}
-
-Dependency Scanning outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM)
-for each supported lock or build file it detects.
-
-The CycloneDX SBOMs are:
-
-- Named `gl-sbom--.cdx.json`.
-- Available as job artifacts of the dependency scanning job.
-- Saved in the same directory as the detected lock or build files.
-
-For example, if your project has the following structure:
-
-```plaintext
-.
-├── ruby-project/
-│ └── Gemfile.lock
-├── ruby-project-2/
-│ └── Gemfile.lock
-├── php-project/
-│ └── composer.lock
-└── go-project/
- └── go.sum
-```
-
-Then the Gemnasium scanner generates the following CycloneDX SBOMs:
-
-```plaintext
-.
-├── ruby-project/
-│ ├── Gemfile.lock
-│ └── gl-sbom-gem-bundler.cdx.json
-├── ruby-project-2/
-│ ├── Gemfile.lock
-│ └── gl-sbom-gem-bundler.cdx.json
-├── php-project/
-│ ├── composer.lock
-│ └── gl-sbom-packagist-composer.cdx.json
-└── go-project/
- ├── go.sum
- └── gl-sbom-go-go.cdx.json
-```
-
-#### Merging multiple CycloneDX SBOMs
-
-You can use a CI/CD job to merge the multiple CycloneDX SBOMs into a single SBOM. GitLab uses
-[CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store) to store
-implementation-specific details in the metadata of each CycloneDX SBOM, such as the location of
-build and lock files. If multiple CycloneDX SBOMs are merged together, this information is removed
-from the resulting merged file.
-
-For example, the following `.gitlab-ci.yml` extract demonstrates how the Cyclone SBOM files can be
-merged, and the resulting file validated.
-
-```yaml
-stages:
- - test
- - merge-cyclonedx-sboms
-
-include:
- - template: Jobs/Dependency-Scanning.gitlab-ci.yml
-
-merge cyclonedx sboms:
- stage: merge-cyclonedx-sboms
- image:
- name: cyclonedx/cyclonedx-cli:0.25.1
- entrypoint: [""]
- script:
- - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
- # optional: validate the merged sbom
- - cyclonedx validate --input-version v1_4 --input-file gl-sbom-all.cdx.json
- artifacts:
- paths:
- - gl-sbom-all.cdx.json
-```
-
-## Contributing to the vulnerability database
-
-To find a vulnerability, you can search the [`GitLab Advisory Database`](https://advisories.gitlab.com/).
-You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md).
-
-## Offline environment
-
-{{< details >}}
-
-- Tier: Ultimate
-- Offering: GitLab Self-Managed
-
-{{< /details >}}
-
-For instances in an environment with limited, restricted, or intermittent access
-to external resources through the internet, some adjustments are required for dependency scanning
-jobs to run successfully. For more information, see [Offline environments](../offline_deployments/_index.md).
-
-### Requirements
-
-To run dependency scanning in an offline environment you must have:
-
-- A GitLab Runner with the `docker` or `kubernetes` executor
-- Local copies of the dependency scanning analyzer images
-- Access to the [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db)
-- Access to the [Package Metadata Database](../../../topics/offline/quick_start_guide.md#enabling-the-package-metadata-database)
-
-### Local copies of analyzer images
-
-To use dependency scanning with all [supported languages and frameworks](#supported-languages-and-package-managers):
-
-1. Import the following default dependency scanning analyzer images from `registry.gitlab.com` into
- your [local Docker container registry](../../packages/container_registry/_index.md):
-
- ```plaintext
- registry.gitlab.com/security-products/gemnasium:6
- registry.gitlab.com/security-products/gemnasium:6-fips
- registry.gitlab.com/security-products/gemnasium-maven:6
- registry.gitlab.com/security-products/gemnasium-maven:6-fips
- registry.gitlab.com/security-products/gemnasium-python:6
- registry.gitlab.com/security-products/gemnasium-python:6-fips
- ```
-
- The process for importing Docker images into a local offline Docker registry depends on
- **your network security policy**. Consult your IT staff to find an accepted and approved
- process by which external resources can be imported or temporarily accessed.
- These scanners are [periodically updated](../detect/vulnerability_scanner_maintenance.md)
- with new definitions, and you may want to download them regularly.
-
-1. Configure GitLab CI/CD to use the local analyzers.
-
- Set the value of the CI/CD variable `SECURE_ANALYZERS_PREFIX` to your local Docker registry - in
- this example, `docker-registry.example.com`.
-
- ```yaml
- include:
- - template: Jobs/Dependency-Scanning.gitlab-ci.yml
-
- variables:
- SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"
- ```
-
-### Access to the GitLab Advisory Database
-
-The [GitLab Advisory Database](https://gitlab.com/gitlab-org/security-products/gemnasium-db) is the
-source of vulnerability data used by the `gemnasium`, `gemnasium-maven`, and `gemnasium-python`
-analyzers. The Docker images of these analyzers include a clone of the database.
-The clone is synchronized with the database before starting a scan,
-to ensure the analyzers have the latest vulnerability data.
-
-In an offline environment, the default host of the GitLab Advisory Database can't be accessed.
-Instead, you must host the database somewhere that it is accessible to the GitLab runners. You must
-also update the database manually at your own schedule.
-
-Available options for hosting the database are:
-
-- [Use a clone of the GitLab Advisory Database](#use-a-copy-of-the-gitlab-advisory-database).
-- [Use a copy of the GitLab Advisory Database](#use-a-copy-of-the-gitlab-advisory-database).
-
-#### Use a clone of the GitLab Advisory Database
-
-Using a clone of the GitLab Advisory Database is recommended because it is the most efficient
-method.
-
-To host a clone of the GitLab Advisory Database:
-
-1. Clone the GitLab Advisory Database to a host that is accessible by HTTP from the GitLab runners.
-1. In your `.gitlab-ci.yml` file, set the value of the CI/CD variable `GEMNASIUM_DB_REMOTE_URL` to
- the URL of the Git repository.
-
-For example:
-
-```yaml
-variables:
- GEMNASIUM_DB_REMOTE_URL: https://users-own-copy.example.com/gemnasium-db.git
-```
-
-#### Use a copy of the GitLab Advisory Database
-
-Using a copy of the GitLab Advisory Database requires you to host an archive file which is
-downloaded by the analyzers.
-
-To use a copy of the GitLab Advisory Database:
-
-1. Download an archive of the GitLab Advisory Database to a host that is accessible by HTTP from the
- GitLab runners. The archive is located at
- `https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/archive/master/gemnasium-db-master.tar.gz`.
-1. Update your `.gitlab-ci.yml` file.
-
- - Set CI/CD variable `GEMNASIUM_DB_LOCAL_PATH` to use the local copy of the database.
- - Set CI/CD variable `GEMNASIUM_DB_UPDATE_DISABLED` to disable the database update.
- - Download and extract the advisory database before the scan begins.
-
- ```yaml
- variables:
- GEMNASIUM_DB_LOCAL_PATH: ./gemnasium-db-local
- GEMNASIUM_DB_UPDATE_DISABLED: "true"
-
- dependency_scanning:
- before_script:
- - wget https://local.example.com/gemnasium_db.tar.gz
- - mkdir -p $GEMNASIUM_DB_LOCAL_PATH
- - tar -xzvf gemnasium_db.tar.gz --strip-components=1 -C $GEMNASIUM_DB_LOCAL_PATH
- ```
-
-## Using a proxy with Gradle projects
-
-The Gradle wrapper script does not read the `HTTP(S)_PROXY` environment variables. See [this upstream issue](https://github.com/gradle/gradle/issues/11065).
-
-To make the Gradle wrapper script use a proxy, you can specify the options using the `GRADLE_CLI_OPTS` CI/CD variable:
-
-```yaml
-variables:
- GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost"
-```
-
-## Using a proxy with Maven projects
-
-Maven does not read the `HTTP(S)_PROXY` environment variables.
-
-To make the Maven dependency scanner use a proxy, you can configure it using a `settings.xml` file (see [Maven documentation](https://maven.apache.org/guides/mini/guide-proxies.html)) and instruct Maven to use this configuration by using the `MAVEN_CLI_OPTS` CI/CD variable:
-
-```yaml
-variables:
- MAVEN_CLI_OPTS: "--settings mysettings.xml"
-```
-
-## Specific settings for languages and package managers
-
-See the following sections for configuring specific languages and package managers.
-
-### Python (pip)
-
-If you need to install Python packages before the analyzer runs, you should use `pip install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies.
-
-### Python (setuptools)
-
-If you need to install Python packages before the analyzer runs, you should use `python setup.py install --user` in the `before_script` of the scanning job. The `--user` flag causes project dependencies to be installed in the user directory. If you do not pass the `--user` option, packages are installed globally, and they are not scanned and don't show up when listing project dependencies.
-
-When using self-signed certificates for your private PyPi repository, no extra job configuration (aside
-from the previous `.gitlab-ci.yml` template) is needed. However, you must update your `setup.py` to
-ensure that it can reach your private repository. Here is an example configuration:
-
-1. Update `setup.py` to create a `dependency_links` attribute pointing at your private repository for each
- dependency in the `install_requires` list:
-
- ```python
- install_requires=['pyparsing>=2.0.3'],
- dependency_links=['https://pypi.example.com/simple/pyparsing'],
- ```
-
-1. Fetch the certificate from your repository URL and add it to the project:
-
- ```shell
- printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt
- ```
-
-1. Point `setup.py` at the newly downloaded certificate:
-
- ```python
- import setuptools.ssl_support
- setuptools.ssl_support.cert_paths = ['internal.crt']
- ```
-
-### Python (Pipenv)
-
-If running in a limited network connectivity environment, you must configure the `PIPENV_PYPI_MIRROR`
-variable to use a private PyPi mirror. This mirror must contain both default and development dependencies.
-
-```yaml
-variables:
- PIPENV_PYPI_MIRROR: https://pypi.example.com/simple
-```
-
-
-Alternatively, if it's not possible to use a private registry, you can load the required packages
-into the Pipenv virtual environment cache. For this option, the project must check in the
-`Pipfile.lock` into the repository, and load both default and development packages into the cache.
-See the example [python-pipenv](https://gitlab.com/gitlab-org/security-products/tests/python-pipenv/-/blob/41cc017bd1ed302f6edebcfa3bc2922f428e07b6/.gitlab-ci.yml#L20-42)
-project for an example of how this can be done.
-
-
## Warnings
We recommend that you use the most recent version of all containers, and the most recent supported version of all package managers and languages. Using previous versions carries an increased security risk because unsupported versions may no longer benefit from active security reporting and backporting of security fixes.
@@ -1596,3 +1616,8 @@ Follow these best practices when you build projects that use CocoaPods for depen
1. After you update your Podfile, run `pod install` to install dependencies and update your workspace.
Remember to always run `pod install` after updating your Podfile to ensure all dependencies are properly installed and the workspace is updated.
+
+## Contributing to the vulnerability database
+
+To find a vulnerability, you can search the [`GitLab Advisory Database`](https://advisories.gitlab.com/).
+You can also [submit new vulnerabilities](https://gitlab.com/gitlab-org/security-products/gemnasium-db/blob/master/CONTRIBUTING.md).
diff --git a/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md b/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md
index aea391215ac..4290cd593e1 100644
--- a/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md
+++ b/doc/user/application_security/dependency_scanning/dependency_scanning_sbom/_index.md
@@ -45,52 +45,127 @@ ensure coverage for all of these dependency types. To cover as much of your risk
we encourage you to use all of our security scanners. For a comparison of these features, see
[Dependency Scanning compared to Container Scanning](../../comparison_dependency_and_container_scanning.md).
-## How it scans an application
+## Getting started
-The dependency scanning using SBOM approach relies on two distinct phases:
+Enable the Dependency Scanning using SBOM feature with one of the following options:
-- First, the dependency detection phase that focuses solely on creating a comprehensive inventory of your
-project’s dependencies and their relationship (dependency graph). This inventory is captured in an SBOM (Software Bill of Materials)
-document.
-- Second, after the CI/CD pipeline completes, the GitLab platform processes your SBOM report and performs
-a thorough security analysis using the built-in GitLab SBOM Vulnerability Scanner. It is the same scanner
-that provides [Continuous Vulnerability Scanning](../../continuous_vulnerability_scanning/_index.md).
+- Use the `latest` Dependency Scanning CI/CD template `Dependency-Scanning.latest.gitlab-ci.yml` to enable a GitLab provided analyzer.
+ - The (deprecated) Gemnasium analyzer is used by default.
+ - To enable the new Dependency Scanning analyzer, set the CI/CD variable `DS_ENFORCE_NEW_ANALYZER` to `true`.
+- Use the [Scan Execution Policies](../../policies/scan_execution_policies.md) with the `latest` template to enable a GitLab provided analyzer.
+ - The (deprecated) Gemnasium analyzer is used by default.
+ - To enable the new Dependency Scanning analyzer, set the CI/CD variable `DS_ENFORCE_NEW_ANALYZER` to `true`.
+- Use the [Dependency Scanning CI/CD component](https://gitlab.com/explore/catalog/components/dependency-scanning) to enable the new Dependency Scanning analyzer.
+- Provide your own CycloneDX SBOM document as [a CI/CD artifact report](../../../../ci/yaml/artifacts_reports.md#artifactsreportscyclonedx) from a successful pipeline.
-This separation of concerns and the modularity of this architecture allows to better support customers through expansion
-of language support, a tighter integration and experience within the GitLab platform, and a shift towards industry standard
-report types.
+The preferred method is to use the new Dependency Scanning analyzer and this is what is documented in the next section.
+To enable the (deprecated) Gemnasium analyzer, refer to the enablement instructions for the [legacy Dependency Scanning feature](../_index.md#getting-started).
-## Dependency detection
+## Understanding the results
-Dependency scanning using SBOM requires the detected dependencies to be captured in a CycloneDX SBOM document.
-However, the modular aspect of this functionality allows you to select how this document is generated:
+The dependency scanning analyzer produces CycloneDX Software Bill of Materials (SBOM) for each supported
+lock file or dependency graph export detected.
-- Using the Dependency Scanning analyzer provided by GitLab (recommended)
-- Using the (deprecated) Gemnasium analyzer provided by GitLab
-- Using a custom job with a 3rd party CycloneDX SBOM generator or a custom tool.
+### CycloneDX Software Bill of Materials
-In order to activate dependency scanning using SBOM, the provided CycloneDX SBOM document must:
+The dependency scanning analyzer outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM)
+for each supported lock or dependency graph export it detects. The CycloneDX SBOMs are created as job artifacts.
-- Comply with [the CycloneDX specification](https://github.com/CycloneDX/specification) version `1.4`, `1.5`, or `1.6`. Online validator available on [CycloneDX Web Tool](https://cyclonedx.github.io/cyclonedx-web-tool/validate).
-- Comply with the GitLab CycloneDX property taxonomy.
-- Be uploaded as [a CI/CD artifact report](../../../../ci/yaml/artifacts_reports.md#artifactsreportscyclonedx) from a successful pipeline.
+The CycloneDX SBOMs are:
-When using GitLab provided analyzers, these requirements are met.
+- Named `gl-sbom--.cdx.json`.
+- Available as job artifacts of the dependency scanning job.
+- Uploaded as `cyclonedx` reports.
+- Saved in the same directory as the detected lock or dependency graph exports files.
-## Security analysis
+For example, if your project has the following structure:
-Once a compatible CycloneDX SBOM document is uploaded, GitLab automatically performs the security analysis
-with the GitLab SBOM Vulnerability Scanner. Each component is checked against the GitLab Advisory Database and
-scan results are processed in the following manners:
+```plaintext
+.
+├── ruby-project/
+│ └── Gemfile.lock
+├── ruby-project-2/
+│ └── Gemfile.lock
+└── php-project/
+ └── composer.lock
+```
-If the SBOM report is declared by a CI/CD job on the default branch: vulnerabilities are created,
-and can be seen in the [vulnerability report](../../vulnerability_report/_index.md).
+The following CycloneDX SBOMs are created as job artifacts:
-If the SBOM report is declared by a CI/CD job on a non-default branch: security findings are created,
-and can be seen in the [security tab of the pipeline view](../../detect/security_scanning_results.md) and MR security widget.
-This functionality is behing a feature flag and tracked in [Epic 14636](https://gitlab.com/groups/gitlab-org/-/epics/14636).
+```plaintext
+.
+├── ruby-project/
+│ ├── Gemfile.lock
+│ └── gl-sbom-gem-bundler.cdx.json
+├── ruby-project-2/
+│ ├── Gemfile.lock
+│ └── gl-sbom-gem-bundler.cdx.json
+└── php-project/
+ ├── composer.lock
+ └── gl-sbom-packagist-composer.cdx.json
+```
-### Supported package types
+### Merging multiple CycloneDX SBOMs
+
+You can use a CI/CD job to merge the multiple CycloneDX SBOMs into a single SBOM.
+
+{{< alert type="note" >}}
+
+GitLab uses [CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store)
+to store implementation-specific details in the metadata of each CycloneDX SBOM, such as the
+location of dependency graph exports and lock files. If multiple CycloneDX SBOMs are merged together,
+this information is removed from the resulting merged file.
+
+{{< /alert >}}
+
+For example, the following `.gitlab-ci.yml` extract demonstrates how the Cyclone SBOM files can be
+merged, and the resulting file validated.
+
+```yaml
+stages:
+ - test
+ - merge-cyclonedx-sboms
+
+include:
+ - component: $CI_SERVER_FQDN/components/dependency-scanning/main@0
+
+merge cyclonedx sboms:
+ stage: merge-cyclonedx-sboms
+ image:
+ name: cyclonedx/cyclonedx-cli:0.27.1
+ entrypoint: [""]
+ script:
+ - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
+ # optional: validate the merged sbom
+ - cyclonedx validate --input-version v1_6 --input-file gl-sbom-all.cdx.json
+ artifacts:
+ paths:
+ - gl-sbom-all.cdx.json
+```
+
+## Optimization
+
+To optimize Dependency Scanning with SBOM according to your requirements you can:
+
+- Exclude files and directories from the scan.
+- Define the max depth to look for files.
+
+### Exclude files and directories from the scan
+
+To exclude files or directories from being scanned, use `DS_EXCLUDED_PATHS` with a comma-separated list of patterns in your `.gitlab-ci.yml`. This will prevent specified files and directories from being targeted by the scan.
+
+### Define the max depth to look for files
+
+To optmize the analyzer behavior you may set a max depth value through the `DS_MAX_DEPTH` environment variable. A value of `-1` scans all directories regardless of depth. The default is `2`.
+
+## Roll out
+
+After you are confident in the Dependency Scanning with SBOM results for a single project, you can extend its implementation to additional projects:
+
+- Use [enforced scan execution](../../detect/security_configuration.md#create-a-shared-configuration) to apply Dependency Scanning with SBOM settings across groups.
+- If you have unique requirements, Dependency Scanning with SBOM can be run in [offline environments](../../offline_deployments/_index.md).
+
+## Supported package types
For the security analysis to be effective, the components listed in your SBOM report must have corresponding
entries in the [GitLab Advisory Database](../../gitlab_advisory_database/_index.md).
@@ -122,7 +197,7 @@ Enable the Dependency Scanning using SBOM feature with one of the following opti
- Provide your own CycloneDX SBOM document as [a CI/CD artifact report](../../../../ci/yaml/artifacts_reports.md#artifactsreportscyclonedx) from a successful pipeline.
The preferred method is to use the new Dependency Scanning analyzer and this is what is documented in the next section.
-To enable the (deprecated) Gemnasium analyzer, refer to the enablement instructions for the [legacy Dependency Scanning feature](../_index.md#enabling-the-analyzer).
+To enable the (deprecated) Gemnasium analyzer, refer to the enablement instructions for the [legacy Dependency Scanning feature](../_index.md#getting-started).
## Enabling the analyzer
@@ -483,7 +558,7 @@ The following variables allow configuration of global dependency scanning settin
| `DS_PIPCOMPILE_REQUIREMENTS_FILE_NAME_PATTERN` | Defines which requirement files to process using glob pattern matching (for example, `requirements*.txt` or `*-requirements.txt`). The pattern should match filenames only, not directory paths. See [glob pattern documentation](https://github.com/bmatcuk/doublestar/tree/v1?tab=readme-ov-file#patterns) for syntax details. |
| `SECURE_ANALYZERS_PREFIX` | Override the name of the Docker registry providing the official default images (proxy). |
-#### Overriding dependency scanning jobs
+##### Overriding dependency scanning jobs
To override a job definition declare a new job with the same name as the one to override.
Place this new job after the template inclusion and specify any additional keys under it.
@@ -501,93 +576,50 @@ dependency-scanning:
When using the Dependency Scanning CI/CD component, the analyzer can be customized by configuring the [inputs](https://gitlab.com/explore/catalog/components/dependency-scanning).
-## Output
+## How it scans an application
-The dependency scanning analyzer produces CycloneDX Software Bill of Materials (SBOM) for each supported
-lock file or dependency graph export detected.
+The dependency scanning using SBOM approach relies on two distinct phases:
-### CycloneDX Software Bill of Materials
+- First, the dependency detection phase that focuses solely on creating a comprehensive inventory of your
+project’s dependencies and their relationship (dependency graph). This inventory is captured in an SBOM (Software Bill of Materials)
+document.
+- Second, after the CI/CD pipeline completes, the GitLab platform processes your SBOM report and performs
+a thorough security analysis using the built-in GitLab SBOM Vulnerability Scanner. It is the same scanner
+that provides [Continuous Vulnerability Scanning](../../continuous_vulnerability_scanning/_index.md).
-{{< history >}}
+This separation of concerns and the modularity of this architecture allows to better support customers through expansion
+of language support, a tighter integration and experience within the GitLab platform, and a shift towards industry standard
+report types.
-- Generally available in GitLab 15.7.
+## Dependency detection
-{{< /history >}}
+Dependency scanning using SBOM requires the detected dependencies to be captured in a CycloneDX SBOM document.
+However, the modular aspect of this functionality allows you to select how this document is generated:
-The dependency scanning analyzer outputs a [CycloneDX](https://cyclonedx.org/) Software Bill of Materials (SBOM)
-for each supported lock or dependency graph export it detects. The CycloneDX SBOMs are created as job artifacts.
+- Using the Dependency Scanning analyzer provided by GitLab (recommended)
+- Using the (deprecated) Gemnasium analyzer provided by GitLab
+- Using a custom job with a 3rd party CycloneDX SBOM generator or a custom tool.
-The CycloneDX SBOMs are:
+To activate dependency scanning using SBOM, the provided CycloneDX SBOM document must:
-- Named `gl-sbom--.cdx.json`.
-- Available as job artifacts of the dependency scanning job.
-- Uploaded as `cyclonedx` reports.
-- Saved in the same directory as the detected lock or dependency graph exports files.
+- Comply with [the CycloneDX specification](https://github.com/CycloneDX/specification) version `1.4`, `1.5`, or `1.6`. Online validator available on [CycloneDX Web Tool](https://cyclonedx.github.io/cyclonedx-web-tool/validate).
+- Comply with [the GitLab CycloneDX property taxonomy](../../../../development/sec/cyclonedx_property_taxonomy.md).
+- Be uploaded as [a CI/CD artifact report](../../../../ci/yaml/artifacts_reports.md#artifactsreportscyclonedx) from a successful pipeline.
-For example, if your project has the following structure:
+When using GitLab-provided analyzers, these requirements are met.
-```plaintext
-.
-├── ruby-project/
-│ └── Gemfile.lock
-├── ruby-project-2/
-│ └── Gemfile.lock
-└── php-project/
- └── composer.lock
-```
+## Security analysis
-The following CycloneDX SBOMs are created as job artifacts:
+After a compatible CycloneDX SBOM document is uploaded, GitLab automatically performs the security analysis
+with the GitLab SBOM Vulnerability Scanner. Each component is checked against the GitLab Advisory Database and
+scan results are processed in the following manners:
-```plaintext
-.
-├── ruby-project/
-│ ├── Gemfile.lock
-│ └── gl-sbom-gem-bundler.cdx.json
-├── ruby-project-2/
-│ ├── Gemfile.lock
-│ └── gl-sbom-gem-bundler.cdx.json
-└── php-project/
- ├── composer.lock
- └── gl-sbom-packagist-composer.cdx.json
-```
+If the SBOM report is declared by a CI/CD job on the default branch: vulnerabilities are created,
+and can be seen in the [vulnerability report](../../vulnerability_report/_index.md).
-### Merging multiple CycloneDX SBOMs
-
-You can use a CI/CD job to merge the multiple CycloneDX SBOMs into a single SBOM.
-
-{{< alert type="note" >}}
-
-GitLab uses [CycloneDX Properties](https://cyclonedx.org/use-cases/#properties--name-value-store)
-to store implementation-specific details in the metadata of each CycloneDX SBOM, such as the
-location of dependency graph exports and lock files. If multiple CycloneDX SBOMs are merged together,
-this information is removed from the resulting merged file.
-
-{{< /alert >}}
-
-For example, the following `.gitlab-ci.yml` extract demonstrates how the Cyclone SBOM files can be
-merged, and the resulting file validated.
-
-```yaml
-stages:
- - test
- - merge-cyclonedx-sboms
-
-include:
- - component: $CI_SERVER_FQDN/components/dependency-scanning/main@0
-
-merge cyclonedx sboms:
- stage: merge-cyclonedx-sboms
- image:
- name: cyclonedx/cyclonedx-cli:0.27.1
- entrypoint: [""]
- script:
- - find . -name "gl-sbom-*.cdx.json" -exec cyclonedx merge --output-file gl-sbom-all.cdx.json --input-files "{}" +
- # optional: validate the merged sbom
- - cyclonedx validate --input-version v1_6 --input-file gl-sbom-all.cdx.json
- artifacts:
- paths:
- - gl-sbom-all.cdx.json
-```
+If the SBOM report is declared by a CI/CD job on a non-default branch: security findings are created,
+and can be seen in the [security tab of the pipeline view](../../vulnerability_report/pipeline.md) and MR security widget.
+This functionality is behind a feature flag and tracked in [Epic 14636](https://gitlab.com/groups/gitlab-org/-/epics/14636).
## Troubleshooting
diff --git a/doc/user/application_security/dependency_scanning/static_reachability.md b/doc/user/application_security/dependency_scanning/static_reachability.md
index ca20418a1c3..87cd7a021eb 100644
--- a/doc/user/application_security/dependency_scanning/static_reachability.md
+++ b/doc/user/application_security/dependency_scanning/static_reachability.md
@@ -49,7 +49,7 @@ Enable static reachability analysis to identify high-risk dependencies.
Prerequisites:
-- Enable [Dependency Scanning by using SBOM](dependency_scanning_sbom/_index.md#configuration).
+- Enable [Dependency Scanning by using SBOM](dependency_scanning_sbom/_index.md#getting-started).
Make sure you follow the [pip](dependency_scanning_sbom/_index.md#pip) or [pipenv](dependency_scanning_sbom/_index.md#pipenv)
related instructions for dependency scanning using SBOM. You can also use any other Python package manager that is [supported](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning#supported-files) by the DS analyzer.
diff --git a/doc/user/application_security/detect/roll_out_security_scanning.md b/doc/user/application_security/detect/roll_out_security_scanning.md
index 4c9d9b359b3..f7bedac08d3 100644
--- a/doc/user/application_security/detect/roll_out_security_scanning.md
+++ b/doc/user/application_security/detect/roll_out_security_scanning.md
@@ -1,22 +1,365 @@
---
-stage: Application Security Testing
+stage: Secure
group: Static Analysis
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
-title: Roll out security scanning
+title: 'Roll out application security testing'
---
-You can roll out security scanning to individual projects, subgroups, and groups. You should start
-with individual projects, then increase the scope in increments. An incremental roll out allows you
-to evaluate the results at each point and adjust as needed.
+Plan your application security testing implementation in phases to ensure a smooth transition to a
+more secure development practice.
-To enable security scanning of individual projects:
+This guide helps you implement GitLab application security testing across your organization in
+phases. By starting with a pilot group and gradually expanding coverage, you can minimize disruption
+while maximizing security benefits. The phased approach allows your team to become familiar with
+application security testing tools and workflows before scaling to all projects.
-- Enable individual security scanners.
-- Enable all security scanners by using AutoDevOps.
+Prerequisites:
-To enable security scanning of multiple projects, subgroups, or groups, use one of the following
-methods:
+- GitLab Ultimate.
+- Familiarity with GitLab CI/CD pipelines. The following GitLab self-paced courses provide a good
+ introduction:
+ - [Introduction to CI/CD](https://university.gitlab.com/courses/introduction-to-cicd-s2)
+ - [Hands-on Labs: CI Fundamentals](https://university.gitlab.com/courses/hands-on-labs-ci-fundamentals)
+- Understanding of your organization's security requirements and risk tolerance.
-- [Scan execution policy](../policies/scan_execution_policies.md)
-- [Pipeline execution policy](../policies/pipeline_execution_policies.md)
-- [Compliance framework](../../compliance/compliance_frameworks/_index.md)
+## Scope
+
+This guide covers how to plan and execute a phased implementation of GitLab application security
+testing features, including configuration, vulnerability management, and prevention
+strategies. It assumes you want to gradually introduce application security testing to minimize
+disruption to existing workflows while securing your codebase.
+
+## Phases
+
+The implementation consists of two main phases:
+
+1. **Pilot phase**: Implement application security testing for a limited set of projects to validate
+ configurations and train teams.
+1. **Rollout phase**: Expand application security testing to all target projects using the knowledge
+ gained during the pilot.
+
+## Pilot phase
+
+The pilot phase allows you to apply application security testing with minimal risk before a wider
+rollout.
+
+Consider the following guidance before starting on the pilot phase:
+
+- Identify key stakeholders including security team members, developers, and project managers.
+- Select pilot projects that are representative of your codebase but not critical to daily
+ operations.
+- Schedule training sessions for developers and security team members.
+- Document current security practices to measure improvements.
+
+### Pilot goals
+
+The pilot phase helps you achieve several key objectives:
+
+- Implement application security testing without slowing development
+
+ During the pilot, application security testing results are available to developers in the UI,
+ without blocking merge requests. This approach minimizes risk to projects outside the pilot's
+ scope while collecting valuable data on your current security posture. In the rollout phase you
+ should use a [merge request approval policy](#merge-request-approval-policy) to add an additional
+ approval gate when vulnerabilities are detected in merge requests.
+
+- Establish scalable detection methods
+
+ Implement application security testing on pilot projects in a way that can be expanded to include
+ all projects in the wider rollout scope. Focus on configurations that scale well and can be
+ standardized across projects.
+
+- Test scan times
+
+ Test scan times on representative codebases and applications.
+
+- Simulate the vulnerability remediation workflow
+
+ Simulate detecting, triaging, analyzing, and remediating vulnerabilities in the developer
+ workflows. Verify that engineers can act on findings.
+
+- Compare maintenance costs
+
+ Compare the maintenance of a single solution versus integrating multiple endpoint solutions. How
+ well does this integrate into the IDE, merge request, and pipeline?
+
+#### Benefits for developers
+
+Developers in the pilot group will gain:
+
+- Familiarity with application security testing methods and how to interpret results.
+- Experience preventing vulnerabilities from being merged into the default branch.
+- Understanding of the vulnerability management workflow that begins when a vulnerability is
+ detected in the default branch.
+
+#### Benefits for security management
+
+Security team members participating in the pilot will gain:
+
+- Experience with vulnerability tracking and management in GitLab.
+- Data to establish security baselines and set realistic remediation goals.
+- Insights to refine the security policy before wider rollout.
+
+### Pilot plan
+
+Proper planning ensures an effective pilot phase.
+
+#### Roles and responsibilities
+
+Define who is responsible for:
+
+- Configuring application security testing
+- Reviewing scan results
+- Triaging vulnerabilities
+- Managing remediation
+- Training team members
+- Measuring the pilot's success
+
+### Pilot scope
+
+Carefully select which projects to include in the pilot phase.
+
+Consider these factors when selecting pilot projects:
+
+- Include projects with different technology stacks to test application security testing
+ effectiveness.
+- Choose projects with active development to see real-time results.
+- Select projects with teams open to learning new security practices.
+- Avoid starting with mission-critical applications.
+
+### Security application security testing order
+
+Introduce security application security testing in the following order. This balances value and ease
+of deployment.
+
+- Dependency scanning
+- SAST
+- Advanced SAST
+- Pipeline secret detection
+- Secret push protection
+- Container scanning
+- DAST
+- API security testing
+- IaC scanning
+- Operational container scanning
+
+## Test pilot projects
+
+With planning complete, begin implementing application security testing of your pilot projects.
+
+### Set up testing of pilot projects
+
+Prerequisites:
+
+- You must have the Maintainer role for the projects in which application security testing is to be
+ enabled.
+
+For each project in scope:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Secure > Security configuration**.
+1. Expand **Security configuration**.
+1. Enable the appropriate application security testing based on your project's stack.
+
+For more details, see [Security configuration](../configuration/_index.md).
+
+### For developers
+
+Introduce developers to the tools that provide visibility into security findings.
+
+#### Pipeline results
+
+Developers can view security findings directly in pipeline results:
+
+1. On the left sidebar, select **Search or go to** and find your project.
+1. Select **Build > Pipelines**.
+1. Select the pipeline to review.
+1. In the pipeline details, select the **Security** tab to view detected vulnerabilities.
+
+For more details, see
+[View security scan results in pipelines](../vulnerability_report/pipeline.md).
+
+#### Merge request security widget
+
+The security widget provides visibility into vulnerabilities detected in merge request pipelines:
+
+1. Open a merge request.
+1. Review the security widget to see detected vulnerabilities.
+1. Select **Expand** to see detailed findings.
+
+For more details, see [View security scan results in merge requests](security_scan_results.md).
+
+#### VS Code integration with GitLab Workflow extension
+
+Developers can view security findings directly in their IDE:
+
+1. Install the GitLab Workflow extension for VS Code.
+1. Connect the extension to your GitLab instance.
+1. Use the extension to view security findings without leaving your development environment.
+
+For more details, see
+[GitLab Workflow extension for VS Code](../../../editor_extensions/visual_studio_code/_index.md).
+
+## Vulnerability management workflow
+
+Establish a structured workflow for handling detected vulnerabilities.
+
+The vulnerability management workflow consists of four key stages:
+
+1. **Detect**: Find vulnerabilities through automated application security testing in pipelines.
+1. **Triage**: Assess the severity and impact of detected vulnerabilities.
+1. **Analyze**: Investigate the root cause and determine the best approach for remediation.
+1. **Remediate**: Implement fixes to resolve the vulnerabilities.
+
+### Efficient triage
+
+GitLab provides several features to streamline vulnerability triage:
+
+- Vulnerability filters to focus on high-impact issues first.
+- Severity and confidence ratings to prioritize efforts.
+- Vulnerability tracking to maintain visibility of outstanding issues.
+- Risk assessment data.
+
+For more details, see [Triage](../triage/_index.md).
+
+Triage should include regular reviews of the vulnerability report with security stakeholders.
+
+### Efficient remediation
+
+Streamline the remediation process with these GitLab features:
+
+- Automated remediation suggestions for certain vulnerability types.
+- Merge request creation directly from vulnerability details.
+- Vulnerability history tracking to monitor progress.
+- Automatically resolve vulnerabilities that are no longer detected.
+
+For more details, see [Remediate](../remediate/_index.md).
+
+#### Integrate with ticketing systems
+
+You can use a GitLab issue to track the remediation work required for a vulnerability.
+Alternatively, you can use a Jira issue if that is your primary ticketing system.
+
+For more details, see
+[Linking a vulnerability to GitLab and Jira issues](../vulnerabilities/_index.md#linking-a-vulnerability-to-gitlab-and-jira-issues).
+
+## Vulnerability prevention
+
+Implement features to prevent vulnerabilities from being introduced in the first place.
+
+### Merge request approval policy
+
+Use a merge request approval policy to add an extra approval requirement if the number and
+severity of vulnerabilities in a merge request exceeds a specific threshold. This allows an extra
+review from a member of the application security team, providing an extra level of scrutiny.
+
+Configure approval policies to require security reviews:
+
+1. On the left sidebar, select **Search or go to** and find your group.
+1. Select **Secure > Policies**.
+1. Select **New policy**
+1. In the **Merge request approval policy** pane, select **Select policy**.
+1. Add a merge request approval policy requiring approval from security team members.
+
+For more details, see
+[Security approvals in merge requests](../policies/merge_request_approval_policies.md).
+
+## Rollout phase
+
+After a successful pilot, expand application security testing to all target projects.
+
+Before starting on the rollout phase consider the following:
+
+- Evaluate the results of the pilot phase.
+- Document lessons learned and best practices.
+- Prepare training materials based on pilot experiences.
+- Update implementation plans based on pilot feedback.
+
+### Define access to team members
+
+Application security testing tasks require specific roles or permissions. For each person taking
+part in the rollout phases, define their access according to the tasks they'll be
+performing.
+
+- Users with the Developer role can view vulnerabilities on their projects and merge requests.
+- Users with the Maintainer role can configure security configurations for projects.
+- Users assigned a Custom Role with `admin_vulnerability` permission can manage and triage
+ vulnerabilities.
+- Users assigned a Custom Role with `manage_security_policy_link` permission can enforce policies
+ on groups and projects.
+
+For more details, see
+[Roles and permissions](../../permissions.md#application-security-group-permissions).
+
+### Rollout goals
+
+The rollout phase aims to implement application security testing across all projects in scope,
+using the knowledge and experience gained during the pilot.
+
+### Rollout plan
+
+Review and update roles and responsibilities established during the pilot. The same team
+structure should work for the rollout, but you may need to add more team members as the
+scope expands.
+
+## Implement application security testing at scale
+
+Use policy features to efficiently scale your security implementation.
+
+### Use policy inheritance
+
+Use policy inheritance to maximize effectiveness while also minimizing the number of policies to be
+managed.
+
+Consider the scenario in which you have a top-level group named Finance which contains subgroups A,
+B, and C. You want to run dependency scanning and secret detection on all projects in the Finance
+group. For each subgroup you want to run different sets of application security testing tools.
+
+To achieve this goal, you could define 3 policies for the Finance group:
+
+- Policy 1:
+ - Includes dependency scanning and secret detection.
+ - Applies to the Finance group, all its subgroups, and their projects.
+- Policy 2:
+ - Includes DAST and API security testing.
+ - Scoped to only subgroups A and B.
+- Policy 3:
+ - Includes SAST.
+ - Scoped to only subgroup C.
+
+Only a single set of policies needs to be maintained but still provides the flexibility to suit
+the needs of different projects.
+
+For more details, see [Enforcement](../policies/_index.md#enforcement).
+
+### Configure scan execution policies
+
+Implement consistent application security testing across multiple projects by using scan execution
+policies.
+
+Prerequisites:
+
+- You must have the Owner role, or a custom role with `manage_security_policy_link` permission, for
+ the groups in which application security testing is to be enabled.
+
+1. On the left sidebar, select **Search or go to** and find your project or group.
+1. Select **Secure > Policies**.
+1. Create scan execution policies based on the application security testing configuration used
+ during the pilot phase.
+
+For more details, see [Security policies](../policies/_index.md).
+
+### Scale gradually
+
+Scale the rollout gradually, first to the pilot projects and incrementally to all target projects.
+When applying policies to all groups and projects, create awareness to all project stakeholders as
+this can impact changes in pipelines and merge request workflows. For example, notify stakeholders
+
+Implement your security policies in phases:
+
+1. Start by applying policies to the projects from the pilot phase.
+1. Monitor for any issues or disruptions.
+1. Gradually expand the policies' scope to include more projects.
+1. Continue until all target projects are covered.
+
+For more details, see [Policy design guidelines](../policies/_index.md#policy-design-guidelines).
diff --git a/doc/user/application_security/get-started-security.md b/doc/user/application_security/get-started-security.md
index f20dd8af03b..a041d19fd5f 100644
--- a/doc/user/application_security/get-started-security.md
+++ b/doc/user/application_security/get-started-security.md
@@ -73,7 +73,7 @@ For more information, see:
- [Enable Secret Detection](secret_detection/pipeline/_index.md#enable-the-analyzer)
- [Secret Detection settings](secret_detection/pipeline/configure.md)
-- [Enable Dependency Scanning](dependency_scanning/_index.md#configuration)
+- [Enable Dependency Scanning](dependency_scanning/_index.md#getting-started)
- [Dependency Scanning settings](dependency_scanning/_index.md#available-cicd-variables)
## Step 4: Review scan results
diff --git a/doc/user/application_security/offline_deployments/_index.md b/doc/user/application_security/offline_deployments/_index.md
index 1b458db9d47..0dfeb471879 100644
--- a/doc/user/application_security/offline_deployments/_index.md
+++ b/doc/user/application_security/offline_deployments/_index.md
@@ -104,6 +104,7 @@ You can find more information at each of the pages below:
- [API Fuzzing offline directions](../api_fuzzing/configuration/offline_configuration.md)
- [License Scanning offline directions](../../compliance/license_scanning_of_cyclonedx_files/_index.md#running-in-an-offline-environment)
- [Dependency Scanning offline directions](../dependency_scanning/_index.md#offline-environment)
+- [IaC Scanning offline directions](../iac_scanning/_index.md#offline-configuration)
## Loading Docker images onto your offline host
diff --git a/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md b/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md
index b8d0ec86577..e6a8b7e810c 100644
--- a/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md
+++ b/doc/user/compliance/license_scanning_of_cyclonedx_files/_index.md
@@ -44,7 +44,7 @@ No contextual information (for example, a list of project dependencies) is sent
To enable License scanning of CycloneDX files:
- Using the Dependency Scanning template
- - Enable [Dependency Scanning](../../application_security/dependency_scanning/_index.md#enabling-the-analyzer)
+ - Enable [Dependency Scanning](../../application_security/dependency_scanning/_index.md#getting-started)
and ensure that its prerequisites are met.
- On GitLab Self-Managed, you can [choose package registry metadata to synchronize](../../../administration/settings/security_and_compliance.md#choose-package-registry-metadata-to-sync) in the **Admin** area for the GitLab instance. For this data synchronization to work, you must allow outbound network traffic from your GitLab instance to the domain `storage.googleapis.com`. If you have limited or no network connectivity then refer to the documentation section [running in an offline environment](#running-in-an-offline-environment) for further guidance.
- Or use the [CI/CD component](../../../ci/components/_index.md) for applicable package registries.
diff --git a/locale/gitlab.pot b/locale/gitlab.pot
index f2b359241c6..17dc1d8aa50 100644
--- a/locale/gitlab.pot
+++ b/locale/gitlab.pot
@@ -2407,6 +2407,9 @@ msgstr ""
msgid "AI|Accept & Insert"
msgstr ""
+msgid "AI|Agents"
+msgstr ""
+
msgid "AI|Apply AI-generated description"
msgstr ""
@@ -12669,6 +12672,9 @@ msgstr ""
msgid "Check feature availability on namespace plan"
msgstr ""
+msgid "Check option: %{option}"
+msgstr ""
+
msgid "Check out branch"
msgstr ""
diff --git a/spec/frontend/ai/catalog/components/ai_catalog_nav_tabs_spec.js b/spec/frontend/ai/catalog/components/ai_catalog_nav_tabs_spec.js
new file mode 100644
index 00000000000..6903e1b64da
--- /dev/null
+++ b/spec/frontend/ai/catalog/components/ai_catalog_nav_tabs_spec.js
@@ -0,0 +1,65 @@
+import { GlTab, GlTabs } from '@gitlab/ui';
+import { shallowMountExtended } from 'helpers/vue_test_utils_helper';
+
+import AiCatalogNavTabs from '~/ai/catalog/components/ai_catalog_nav_tabs.vue';
+import { AI_CATALOG_AGENTS_ROUTE } from '~/ai/catalog/router/constants';
+
+describe('AiCatalogNavTabs', () => {
+ let wrapper;
+
+ const mockRouter = {
+ push: jest.fn(),
+ };
+
+ const createComponent = ({ routePath = '/ai/catalog' } = {}) => {
+ wrapper = shallowMountExtended(AiCatalogNavTabs, {
+ mocks: {
+ $route: {
+ path: routePath,
+ },
+ $router: mockRouter,
+ },
+ });
+ };
+
+ const findTabs = () => wrapper.findComponent(GlTabs);
+ const findAllTabs = () => wrapper.findAllComponents(GlTab);
+
+ beforeEach(() => {
+ createComponent();
+ });
+
+ it('renders tabs', () => {
+ expect(findTabs().exists()).toBe(true);
+ });
+
+ it('renders the correct number of tabs', () => {
+ expect(findAllTabs()).toHaveLength(1);
+ });
+
+ it('renders the Agents tab', () => {
+ const agentsTab = findAllTabs().at(0);
+
+ expect(agentsTab.attributes('title')).toBe('Agents');
+ });
+
+ describe('navigation', () => {
+ it('navigates to the correct route when tab is clicked', () => {
+ const agentsTab = findAllTabs().at(0);
+
+ agentsTab.vm.$emit('click');
+
+ expect(mockRouter.push).toHaveBeenCalledWith({ name: AI_CATALOG_AGENTS_ROUTE });
+ });
+
+ it('does not navigate if already on the same route', () => {
+ createComponent({ routePath: AI_CATALOG_AGENTS_ROUTE });
+
+ const agentsTab = findAllTabs().at(0);
+
+ agentsTab.vm.$emit('click');
+
+ expect(mockRouter.push).not.toHaveBeenCalled();
+ });
+ });
+});
diff --git a/spec/frontend/ai/catalog/pages/ai_catalog_agents_spec.js b/spec/frontend/ai/catalog/pages/ai_catalog_agents_spec.js
new file mode 100644
index 00000000000..e130ec50d65
--- /dev/null
+++ b/spec/frontend/ai/catalog/pages/ai_catalog_agents_spec.js
@@ -0,0 +1,108 @@
+import { GlSkeletonLoader } from '@gitlab/ui';
+
+import { shallowMountExtended } from 'helpers/vue_test_utils_helper';
+import waitForPromises from 'helpers/wait_for_promises';
+
+import AiCatalogAgents from '~/ai/catalog/pages/ai_catalog_agents.vue';
+
+describe('AiCatalogAgents', () => {
+ let wrapper;
+
+ const mockAgentsData = [
+ {
+ id: 1,
+ name: 'Test Agent 1',
+ description: 'Description for agent 1',
+ },
+ {
+ id: 2,
+ name: 'Test Agent 2',
+ description: 'Description for agent 2',
+ },
+ {
+ id: 3,
+ name: 'Test Agent 3',
+ description: 'Description for agent 3',
+ },
+ ];
+
+ const emptyAgentsData = [];
+
+ const createComponent = ({ loading = false, mockData = mockAgentsData } = {}) => {
+ wrapper = shallowMountExtended(AiCatalogAgents, {
+ data() {
+ return { aiCatalogAgents: mockData };
+ },
+ mocks: {
+ $apollo: {
+ queries: {
+ aiCatalogAgents: {
+ loading,
+ },
+ },
+ },
+ },
+ });
+
+ return waitForPromises();
+ };
+
+ const findSkeletonLoader = () => wrapper.findComponent(GlSkeletonLoader);
+ const findAllParagraphs = () => wrapper.findAll('p');
+
+ describe('loading state', () => {
+ it('shows skeleton loader when loading', () => {
+ createComponent({ loading: true });
+
+ expect(findSkeletonLoader().exists()).toBe(true);
+ expect(findAllParagraphs()).toHaveLength(0);
+ });
+
+ it('does not show agent content when loading', () => {
+ createComponent({ loading: true });
+
+ expect(findAllParagraphs()).toHaveLength(0);
+ });
+ });
+
+ describe('with agent data', () => {
+ beforeEach(async () => {
+ await createComponent();
+ });
+
+ it('displays agent names and descriptions correctly', () => {
+ const paragraphs = findAllParagraphs();
+
+ // Should have 6 paragraphs total (2 per agent: name and description)
+ expect(paragraphs).toHaveLength(6);
+
+ // Check agent names (even indices: 0, 2, 4)
+ expect(paragraphs.at(0).text()).toBe('Test Agent 1');
+ expect(paragraphs.at(2).text()).toBe('Test Agent 2');
+ expect(paragraphs.at(4).text()).toBe('Test Agent 3');
+
+ // Check agent descriptions (odd indices: 1, 3, 5)
+ expect(paragraphs.at(1).text()).toBe('Description for agent 1');
+ expect(paragraphs.at(3).text()).toBe('Description for agent 2');
+ expect(paragraphs.at(5).text()).toBe('Description for agent 3');
+ });
+
+ it('does not show skeleton loader', () => {
+ expect(findSkeletonLoader().exists()).toBe(false);
+ });
+ });
+
+ describe('with empty agent data', () => {
+ beforeEach(async () => {
+ await createComponent({ mockData: emptyAgentsData });
+ });
+
+ it('renders no agent paragraphs', () => {
+ expect(findAllParagraphs()).toHaveLength(0);
+ });
+
+ it('does not show skeleton loader', () => {
+ expect(findSkeletonLoader().exists()).toBe(false);
+ });
+ });
+});
diff --git a/spec/frontend/ai/catalog/pages/ai_catalog_index_spec.js b/spec/frontend/ai/catalog/pages/ai_catalog_index_spec.js
deleted file mode 100644
index 5a5eba942b5..00000000000
--- a/spec/frontend/ai/catalog/pages/ai_catalog_index_spec.js
+++ /dev/null
@@ -1,111 +0,0 @@
-import { GlSkeletonLoader } from '@gitlab/ui';
-
-import { shallowMountExtended } from 'helpers/vue_test_utils_helper';
-import waitForPromises from 'helpers/wait_for_promises';
-
-import AiCatalogIndex from '~/ai/catalog/pages/ai_catalog_index.vue';
-
-describe('AiCatalogIndex', () => {
- let wrapper;
-
- const mockWorkflowsData = [
- {
- id: 1,
- name: 'Test Workflow 1',
- type: 'Type A',
- },
- {
- id: 2,
- name: 'Test Workflow 2',
- type: 'Type B',
- },
- {
- id: 3,
- name: 'Test Workflow 3',
- type: 'Type C',
- },
- ];
-
- const emptyWorkflowsData = [];
-
- const createComponent = ({ loading = false, mockData = mockWorkflowsData } = {}) => {
- wrapper = shallowMountExtended(AiCatalogIndex, {
- data() {
- return { userWorkflows: mockData };
- },
- mocks: {
- $apollo: {
- queries: {
- userWorkflows: {
- loading,
- },
- },
- },
- },
- });
-
- return waitForPromises();
- };
-
- const findSkeletonLoader = () => wrapper.findComponent(GlSkeletonLoader);
- const findTitle = () => wrapper.find('h1');
- const findAllParagraphs = () => wrapper.findAll('p');
-
- describe('component initialization', () => {
- it('renders the page title', async () => {
- await createComponent();
-
- expect(findTitle().text()).toBe('AI Catalog');
- });
- });
-
- describe('loading state', () => {
- it('shows skeleton loader when loading', () => {
- createComponent({ loading: true });
-
- expect(findSkeletonLoader().exists()).toBe(true);
- expect(findAllParagraphs()).toHaveLength(0);
- });
- });
-
- describe('with workflow data', () => {
- beforeEach(async () => {
- await createComponent();
- });
-
- it('displays workflow names and types correctly', () => {
- const paragraphs = findAllParagraphs();
-
- // Should have 6 paragraphs total (2 per workflow: name and type)
- expect(paragraphs).toHaveLength(6);
-
- // Check workflow names (even indices: 0, 2, 4)
- expect(paragraphs.at(0).text()).toBe('Test Workflow 1');
- expect(paragraphs.at(2).text()).toBe('Test Workflow 2');
- expect(paragraphs.at(4).text()).toBe('Test Workflow 3');
-
- // Check workflow types (odd indices: 1, 3, 5)
- expect(paragraphs.at(1).text()).toBe('Type A');
- expect(paragraphs.at(3).text()).toBe('Type B');
- expect(paragraphs.at(5).text()).toBe('Type C');
- });
-
- it('does not show skeleton loader', () => {
- expect(findSkeletonLoader().exists()).toBe(false);
- });
- });
-
- describe('with empty workflow data', () => {
- beforeEach(async () => {
- await createComponent({ mockData: emptyWorkflowsData });
- });
-
- it('renders no workflow paragraphs', () => {
- expect(findAllParagraphs()).toHaveLength(0);
- });
-
- it('does not show skeleton loader', () => {
- expect(findSkeletonLoader().exists()).toBe(false);
- });
- });
-});
diff --git a/spec/frontend/content_editor/extensions/task_item_spec.js b/spec/frontend/content_editor/extensions/task_item_spec.js
index 2d549fb45da..31a472e41ca 100644
--- a/spec/frontend/content_editor/extensions/task_item_spec.js
+++ b/spec/frontend/content_editor/extensions/task_item_spec.js
@@ -26,25 +26,26 @@ describe('content_editor/extensions/task_item', () => {
tiptapEditor.commands.setContent(initialDoc.toJSON());
expect(tiptapEditor.view.dom.querySelector('li')).toMatchInlineSnapshot(`
-
-
-
-
- foo
-
-
-
- `);
+
+
+
+
+ foo
+
+
+
+`);
});
it('renders task item as disabled if it is inapplicable', () => {
@@ -53,27 +54,28 @@ describe('content_editor/extensions/task_item', () => {
tiptapEditor.commands.setContent(initialDoc.toJSON());
expect(tiptapEditor.view.dom.querySelector('li')).toMatchInlineSnapshot(`
-
-
-
-
- foo
-
-
-
- `);
+
+
+
+
+ foo
+
+
+
+`);
});
it('ignores any tags in the task item', () => {
@@ -87,26 +89,27 @@ describe('content_editor/extensions/task_item', () => {
`);
expect(tiptapEditor.view.dom.querySelector('li')).toMatchInlineSnapshot(`
-