diff --git a/data/deprecations/17-9-DS-upgrade-to-SBOM-scanner.yml b/data/deprecations/17-9-DS-upgrade-to-SBOM-scanner.yml
index 41a8347568a43d4a1d74bd25f8480291a116af4b..4b5c6a386ddc2cd6abbf58f40dda1857b7fb760a 100644
--- a/data/deprecations/17-9-DS-upgrade-to-SBOM-scanner.yml
+++ b/data/deprecations/17-9-DS-upgrade-to-SBOM-scanner.yml
@@ -25,8 +25,10 @@
Please review the fully detailed changes below and consult [the migration guide](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.html) to assist you with the transition.
- - When using the Dependency Scanning CI/CD template (`Dependency-Scanning.gitlab-ci.yml`), the existing CI/CD jobs based on the Gemnasium analyzer will continue to be used by default. The new Dependency Scanning analyzer will run by default only
- for newly supported languages and package managers that are not already covered by the Gemnasium analyzer. You can also opt-in to fully migrate to the new Dependency Scanning analyzer and use for all supported projects.
+ - To prevent disruptions to your CI/CD configuration, when your application uses the stable Dependency Scanning CI/CD template (`Dependency-Scanning.gitlab-ci.yml`), Dependency Scanning uses only the existing CI/CD jobs based on the Gemnasium analyzer.
+ - When your application uses the latest Dependency Scanning CI/CD template (`Dependency-Scanning.latest.gitlab-ci.yml`), Dependency Scanning uses the existing CI/CD jobs based on the Gemnasium analyzer and the new Dependency Scanning analyzer also runs on the supported file types.
+ - You can also opt-in to enforce the new Dependency Scanning analyzer for all projects.
+ - Other migration paths might be considered as the feature gains maturity.
- To transition to Dependency Scanning with SBOM, the security scan results generated by the Gemansium analyzer will no longer be uploaded to the GitLab platform as a
[Dependency Scanning security report artifact](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsdependency_scanning). Instead, Dependency Scanning results will be generated within the GitLab platform,
using the GitLab SBOM Vulnerability Scanner, and based on the [CycloneDX SBOM report artifact](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscyclonedx) generated in the CI/CD pipeline.
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index b6cbbe9fd666827d77beb43ff8c9f1fe5ade9886..43fa9b6f75acc2e8b4abfcc096cc3e64ae9847bf 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -662,8 +662,10 @@ using the Gemnasium analyzer will continue to function by default to prevent dis
Please review the fully detailed changes below and consult [the migration guide](https://docs.gitlab.com/ee/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.html) to assist you with the transition.
-- When using the Dependency Scanning CI/CD template (`Dependency-Scanning.gitlab-ci.yml`), the existing CI/CD jobs based on the Gemnasium analyzer will continue to be used by default. The new Dependency Scanning analyzer will run by default only
-for newly supported languages and package managers that are not already covered by the Gemnasium analyzer. You can also opt-in to fully migrate to the new Dependency Scanning analyzer and use for all supported projects.
+- To prevent disruptions to your CI/CD configuration, when your application uses the stable Dependency Scanning CI/CD template (`Dependency-Scanning.gitlab-ci.yml`), Dependency Scanning uses only the existing CI/CD jobs based on the Gemnasium analyzer.
+- When your application uses the latest Dependency Scanning CI/CD template (`Dependency-Scanning.latest.gitlab-ci.yml`), Dependency Scanning uses the existing CI/CD jobs based on the Gemnasium analyzer and the new Dependency Scanning analyzer also runs on the supported file types.
+- You can also opt-in to enforce the new Dependency Scanning analyzer for all projects.
+- Other migration paths might be considered as the feature gains maturity.
- To transition to Dependency Scanning with SBOM, the security scan results generated by the Gemansium analyzer will no longer be uploaded to the GitLab platform as a
[Dependency Scanning security report artifact](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportsdependency_scanning). Instead, Dependency Scanning results will be generated within the GitLab platform,
using the GitLab SBOM Vulnerability Scanner, and based on the [CycloneDX SBOM report artifact](https://docs.gitlab.com/ee/ci/yaml/artifacts_reports.html#artifactsreportscyclonedx) generated in the CI/CD pipeline.
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 8fc0405fd282510829b4490419b798f4cab0a277..4ef16bf4308263469972fa4b5627b33dfe15ea37 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
@@ -14,7 +14,13 @@ DETAILS:
> - [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://gitlab.com/gitlab-org/gitlab/-/issues/395692) in GitLab 17.5.
> - Released [lockfile-based Dependency Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning/-/blob/main/README.md?ref_type=heads#supported-files) analyzer as an [Experiment](../../../../policy/development_stages_support.md#experiment-features) in GitLab 17.4.
> - Released [Dependency Scanning CI/CD Component](https://gitlab.com/explore/catalog/components/dependency-scanning) version [`0.4.0`](https://gitlab.com/components/dependency-scanning/-/tags/0.4.0) in GitLab 17.5 with support for the [lockfile-based Dependency Scanning](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning/-/blob/main/README.md?ref_type=heads#supported-files) analyzer.
-> - [Enabled by default with the Dependency Scanning CI/CD templates](https://gitlab.com/gitlab-org/gitlab/-/issues/519597) and Scan Execution Policies for Cargo, Conda, Cocoapods and Swift in GitLab 17.9.
+> - [Enabled by default with the latest Dependency Scanning CI/CD templates](https://gitlab.com/gitlab-org/gitlab/-/issues/519597) for Cargo, Conda, Cocoapods and Swift in GitLab 17.9.
+
+FLAG:
+The availability of this feature is controlled by a feature flag.
+For more information, see the history.
+This feature uses an experimental scanner.
+This feature is available for testing, but not ready for production use.
Dependency scanning using CycloneDX SBOM analyzes your application's dependencies for known
vulnerabilities. All dependencies are scanned, [including transitive dependencies](../_index.md).
@@ -104,10 +110,10 @@ following [PURL types](https://github.com/package-url/purl-spec/blob/34658984613
Enable the Dependency Scanning using SBOM feature with one of the following options:
-- Use either the Dependency Scanning CI/CD template `Dependency-Scanning.gitlab-ci.yml` or `Dependency-Scanning.latest.gitlab-ci.yml` to enable a GitLab provided analyzer.
+- 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) to enable a GitLab provided analyzer.
+- 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.
@@ -133,18 +139,18 @@ Prerequisites:
To enable the analyzer, you must:
-- Use either the Dependency Scanning CI/CD template `Dependency-Scanning.gitlab-ci.yml` or `Dependency-Scanning.latest.gitlab-ci.yml`
-and enforce the new Dependency Scanning analyzer by settin the CI/CD variable `DS_ENFORCE_NEW_ANALYZER` to `true`.
+- Use either the `latest` Dependency Scanning CI/CD template `Dependency-Scanning.latest.gitlab-ci.yml`
+and enforce the new Dependency Scanning analyzer by setting the CI/CD variable `DS_ENFORCE_NEW_ANALYZER` to `true`.
```yaml
include:
- - template: Jobs/Dependency-Scanning.gitlab-ci.yml
+ - template: Jobs/Dependency-Scanning.latest.gitlab-ci.yml
variables:
DS_ENFORCE_NEW_ANALYZER: 'true'
```
-- Use the [Scan Execution Policies](../../policies/scan_execution_policies.md) and enforce the new Dependency Scanning analyzer by settin the CI/CD variable `DS_ENFORCE_NEW_ANALYZER` to `true`.
+- Use the [Scan Execution Policies](../../policies/scan_execution_policies.md) with the `latest` template and enforce the new Dependency Scanning analyzer by setting 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)
```yaml
diff --git a/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md b/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md
index f993af18ae30114ac09c70f90233b9152827706e..b16d462ae8fb806689fe490db4145a918893da1e 100644
--- a/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md
+++ b/doc/user/application_security/dependency_scanning/migration_guide_to_sbom_based_scans.md
@@ -15,7 +15,7 @@ replace the legacy Dependency Scanning feature based on the Gemnasium analyzer.
Follow this migration guide if you use GitLab Dependency Scanning and any of the following conditions apply:
- The Dependency Scanning CI/CD jobs are configured by including a Dependency Scanning CI/CD templates.
-
+
```yaml
include:
- template: Jobs/Dependency-Scanning.gitlab-ci.yml
@@ -43,15 +43,10 @@ This also impacts the availability of some functionalities that depend on the se
### CI/CD configuration
-When you migrate, you'll find several provisions to help prevent disruption to your workflows:
-
-The stable Dependency Scanning CI/CD template (`Dependency-Scanning.gitlab-ci.yml`) maintains backward compatibility by default. It continues to run existing Gemnasium analyzer jobs, while the new Dependency Scanning analyzer only activates for newly supported languages and package managers.
-You can opt-in to use the new Dependency Scanning analyzer for all projects by configuring the `DS_ENFORCE_NEW_ANALYZER` CI/CD variable to `true`.
-
-For the latest CI/CD template (`Dependency-Scanning.latest.gitlab-ci.yml`), the behavior depends on the version of GitLab you are using:
+To prevent disruption to your CI/CD pipelines, the new approach is not yet applied to the stable Dependency Scanning CI/CD template (`Dependency-Scanning.gitlab-ci.yml`) and you must use the `latest` template (`Dependency-Scanning.latest.gitlab-ci.yml`) to enable it.
+Other migration paths might be considered as the feature gains maturity.
-- In GitLab 17.9, 17.10, and 17.11, it matches the stable template's behavior.
-- From GitLab 18.0 and later, it switches to use the new Dependency Scanning analyzer exclusively for all projects (`DS_ENFORCE_NEW_ANALYZER` is set to `true` by default).
+The latest Dependency Scanning CI/CD template (`Dependency-Scanning.latest.gitlab-ci.yml`) still maintains backward compatibility by default. It continues to run existing Gemnasium analyzer jobs, while the new Dependency Scanning analyzer only activates for newly supported languages and package managers. You can opt-in to use the new Dependency Scanning analyzer for all projects by configuring the `DS_ENFORCE_NEW_ANALYZER` CI/CD variable to `true`.
If you're using [Scan Execution Policies](../policies/scan_execution_policies.md), these changes apply in the same way because they build upon the CI/CD templates.
@@ -86,12 +81,12 @@ To migrate to the Dependency Scanning using SBOM method, perform the following s
- If you have manually overridden the `gemnasium-dependency_scanning`, `gemnasium-maven-dependency_scanning`, or `gemnasium-python-dependency_scanning` CI/CD jobs to customize them in a project's `.gitlab-ci.yml` or in the CI/CD configuration for a Pipeline Execution Policy, remove them.
- If you have configured any of [the impacted CI/CD variables](#changes-to-cicd-variables), adjust your configuration accordingly.
1. Enable the Dependency Scanning using SBOM feature with one of the following options:
- - Use either the Dependency Scanning CI/CD template `Dependency-Scanning.gitlab-ci.yml` or `Dependency-Scanning.latest.gitlab-ci.yml` to run the new Dependency Scanning analyzer:
- 1. Keep the Dependency Scanning CI/CD template `include` statement from your `.gitlab-ci.yml` CI/CD configuration.
+ - Use the `latest` Dependency Scanning CI/CD template `Dependency-Scanning.latest.gitlab-ci.yml` to run the new Dependency Scanning analyzer:
+ 1. Ensure your `.gitlab-ci.yml` CI/CD configuration includes the latest Dependency Scanning CI/CD template.
1. Add the CI/CD variable `DS_ENFORCE_NEW_ANALYZER` and set it to `true`. This variable can be set in many different places, while observing the [CI/CD variable precedence](../../../ci/variables/_index.md#cicd-variable-precedence).
1. Adjust your project and your CI/CD configuration if needed by following the language-specific instructions below.
- Use the [Scan Execution Policies](../policies/scan_execution_policies.md) to run the new Dependency Scanning analyzer:
- 1. Edit the configured scan execution policy for Dependency Scanning.
+ 1. Edit the configured scan execution policy for Dependency Scanning and ensure it uses the `latest` template.
1. Add the CI/CD variable `DS_ENFORCE_NEW_ANALYZER` and set it to `true`. This variable can be set in many different places, while observing the [CI/CD variable precedence](../../../ci/variables/_index.md#cicd-variable-precedence).
1. Adjust your project and your CI/CD configuration if needed by following the language-specific instructions below.
- Use the [Dependency Scanning CI/CD component](https://gitlab.com/explore/catalog/components/dependency-scanning) to run the new Dependency Scanning analyzer: