Add latest changes from gitlab-org/gitlab@master

doc/development/sec/cyclonedx_property_taxonomy.md

@@ -78,6 +78,12 @@ The `Property of` column describes what object a property may be attached to.
 | ------------------------------------------ | ----------- | -------------- | ----------- |
 | `gitlab:dependency_scanning:language:name` | The name of the programming language associated with the dependency | `JavaScript`, `Ruby`, `Go` | `metadata`, `component` |
 
+## `gitlab:dependency_scanning_component` namespace taxonomy
+
+| Property                                   | Description | Example values | Property of |
+| ------------------------------------------ | ----------- | -------------- | ----------- |
+| `gitlab:dependency_scanning_component:reachability` | Identifies if a component is used | `in_use`, `not_found` | `component` |
+
 ## `gitlab:container_scanning` namespace taxonomy
 
 ### Namespaces

doc/user/application_security/dependency_scanning/static_reachability.md

@@ -0,0 +1,203 @@
+---
+stage: Application Security Testing
+group: Composition 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: Static reachability analysis
+---
+
+{{< details >}}
+
+- Tier: Ultimate
+- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
+- Status: Beta
+
+{{< /details >}}
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/14177) as an [experiment](../../../policy/development_stages_support.md) in GitLab 17.5.
+- [Changed](https://gitlab.com/groups/gitlab-org/-/epics/15781) from experiment to beta in GitLab 17.11.
+
+{{< /history >}}
+
+Static reachability analysis (SRA) helps you prioritize remediation of vulnerabilities in dependencies.
+
+An application is generally deployed with many dependencies. Dependency scanning identifies which of
+those dependencies have vulnerabilities. However, not all dependencies are used by an application.
+Static reachability analysis identifies those dependencies that are used, in other words reachable,
+and so are a higher security risk than others. Use this information to help prioritize remediation
+of vulnerabilities according to risk.
+
+To identify vulnerable dependencies that are reachable, either:
+
+- Hover over the **Severity** value of a vulnerability in the vulnerability report.
+- Check the `Reachable` value in the vulnerability page.
+- Use a GraphQL query to list those vulnerabilities that are reachable.
+
+## Supported languages and package managers
+
+Static reachability analysis is available only for Python projects. SRA uses the new dependency
+scanning analyzer to generate SBOMs and so supports the same package managers as the analyzer.
+
+| Language | Supported Package Managers |
+|----------|----------------------------|
+| Python   | `pip`, `pipenv`, `poetry`, `uv` |
+
+## Enable static reachability analysis
+
+Enable static reachability analysis to identify high-risk dependencies.
+
+Prerequisites:
+
+- Enable [Dependency Scanning by using SBOM](dependency_scanning_sbom/_index.md#configuration).
+
+  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.
+
+To enable static reachability analysis:
+
+- Edit the project `.gitlab-ci.yml` file and set `DS_STATIC_REACHABILITY_ENABLED` to `true`.
+
+Enabling static reachability:
+
+```yaml
+stages:
+  - build
+  - test
+
+include:
+  - template: Jobs/Dependency-Scanning.latest.gitlab-ci.yml
+
+variables:
+  DS_STATIC_REACHABILITY_ENABLED: true
+  DS_ENFORCE_NEW_ANALYZER: true
+
+# Build job required by the DS analyzer to create pipdeptree.json
+# https://docs.gitlab.com/user/application_security/dependency_scanning/dependency_scanning_sbom/#pip
+build:
+  stage: build
+  image: "python:latest"
+  script:
+    - "pip install -r requirements.txt"
+    - "pip install pipdeptree"
+    - "pipdeptree --json > pipdeptree.json"
+  artifacts:
+    when: on_success
+    access: developer
+    paths: ["**/pipdeptree.json"]
+```
+
+The dependency scanning analyzer requires specific lock files to function properly. These files must
+be generated during a build job on a stage prior to dependency scanning. By default, the dependency
+scanning with reachability job is configured to depend on a job named `build`. If you need to use a
+different name for your build job, you must override the dependency scanning `needs` section in your
+configuration. Below is an example using `pip-compile` to generate a requirement lock file. This
+file is passed to the new DS analyzer by using the `DS_PIPCOMPILE_REQUIREMENTS_FILE_NAME_PATTERN`
+because the name is not standard.
+
+```yaml
+stages:
+  - build
+  - test
+
+include:
+  - template: Jobs/Dependency-Scanning.latest.gitlab-ci.yml
+
+variables:
+  DS_ENFORCE_NEW_ANALYZER: true
+  DS_STATIC_REACHABILITY_ENABLED: true
+  DS_PIPCOMPILE_REQUIREMENTS_FILE_NAME_PATTERN: "requirements-lock.txt"
+
+create:
+  stage: build
+  image: "python:3.12"
+  script:
+    - pip install pip-tools
+    - pip-compile requirements.txt -o requirements-lock.txt
+  artifacts:
+    when: on_success
+    access: developer
+    paths: ["**/requirements-lock.txt"]
+
+dependency-scanning-with-reachability:
+  needs:
+    - job: gitlab-static-reachability
+      optional: true
+      artifacts: true
+      # For supporting Scan Execution Policies.
+    - job: gitlab-static-reachability-0
+      optional: true
+      artifacts: true
+    - job: create # Instead of depending on build job it depends on `create` job
+      optional: true
+      artifacts: true
+```
+
+Static reachability introduces two key jobs:
+
+- `gitlab-static-reachability`: Performs Static Reachability Analysis (SRA) on your Python files.
+- `dependency-scanning-with-reachability`: Executes dependency scanning and generates an SBOM report enriched with reachability data. This job requires the artifact output from the `gitlab-static-reachability` job.
+
+{{< alert type="note" >}}
+
+When you enable static reachability feature for non-Python projects, the
+`gitlab-static-reachability` job will fail but won't break your pipeline, because it's configured to
+allow failures. In such cases, the `dependency-scanning-with-reachability` job will perform standard
+dependency scanning without adding reachability data to the SBOM.
+
+{{< /alert >}}
+
+Static reachability analysis functionality is supported in [Dependency Scanning analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning) version `0.23.0` and all subsequent versions.
+
+{{< alert type="warning" >}}
+
+Changes to the CI/CD configuration for static reachability integration are proposed for the GA release.
+
+{{< /alert >}}
+
+## How static reachability analysis works
+
+Static reachability analysis requires two key components:
+
+- Dependency scanning (DS): Generates an SBOM report that identifies all components and their transitive dependencies.
+- GitLab Advanced SAST (GLAS): Performs static reachability analysis to provide a report showing direct dependencies usage in the codebase.
+
+Static reachability analysis adds reachability data to the SBOM output by dependency scanning. The enriched SBOM is then ingested by the GitLab instance.
+
+Reachability data in the UI can have one of the following values:
+
+| Reachability values | Description                                                               |
+|---------------------|---------------------------------------------------------------------------|
+| Yes                 | The package linked to this vulnerability is confirmed reachable in code   |
+| Not Found           | SRA ran successfully but did not detect usage of the vulnerable package   |
+| Not Available       | SRA was not executed, therefore no reachability data exists               |
+
+## Where to find the reachability data
+
+The reachability data is available in the vulnerability report
+
+![Reachability on the vulnerability report](img/sr_vulnerability_report_v17_11.png)
+
+and the vulnerability page
+
+![Reachability on the vulnerability page](img/sr_vulnerability_page_v17_11.png)
+
+Finally reachability data can be reached using GraphQL.
+
+{{< alert type="warning" >}}
+
+When a vulnerability reachability value shows as "Not Found," exercise caution rather than completely dismissing it, because the beta version of SRA may produce false negatives.
+
+{{< /alert >}}
+
+## Restrictions
+
+Static reachability analysis has the following limitations:
+
+- Offline GitLab instances are not supported, though this is proposed for the GA release.
+- When a direct dependency is marked as `in use`, all its transitive dependencies are also marked as `in use`.
+- Requires the new [dependency scanning analyzer](https://gitlab.com/gitlab-org/security-products/analyzers/dependency-scanning). [Gemnasium](https://gitlab.com/gitlab-org/security-products/analyzers/gemnasium) analyzers are not supported.
+- SRA on beta doesn't officially support pipeline execution policies.
+- SRA on beta works with scan execution policies (SEP), but with the following restrictions:
+  - only dependency scanning and/or static reachability jobs should be added through SEP. You should avoid having a policy while also including the latest dependency scanning template in your project configuration.
+  - Users cannot override the build job name that `dependency-scanning-with-reachability` depends on. Consequently if a build job is required to create a lock file for the dependency scanning analyzer then the name must be named `build`.

doc/user/application_security/terminology/_index.md

@@ -273,6 +273,10 @@ An example primary identifier is `CVE`, which is used for Trivy. The identifier
 Subsequent scans must return the same value for the same finding, even if the location has slightly
 changed.
 
+## Reachability
+
+Reachability indicates whether a [component](#component) listed as a dependency in a project is actually used in the codebase.
+
 ## Report finding
 
 A [finding](#finding) that only exists in a report produced by an analyzer, and is yet to be

doc/user/application_security/vulnerabilities/_index.md

@@ -28,8 +28,9 @@ For vulnerabilities in the [Common Vulnerabilities and Exposures (CVE)](https://
 catalog, these details also include:
 
 - CVSS score
-- [EPSS score](risk_assessment_data.md#epss)
-- [KEV status](risk_assessment_data.md#kev)
+- EPSS score
+- KEV status
+- [Reachability status](../dependency_scanning/static_reachability.md) (Beta)
 
 For further details on this additional data, see [vulnerability risk assessment data](risk_assessment_data.md).
 

doc/user/application_security/vulnerabilities/risk_assessment_data.md

@@ -44,6 +44,18 @@ The KEV catalog lists vulnerabilities that are known to have been exploited. You
 the remediation of vulnerabilities in the KEV catalog above other vulnerabilities. Attacks using
 these vulnerabilities have occurred and the exploitation method is likely known to attackers.
 
+## Reachability
+
+{{< history >}}
+
+- [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/16510) in GitLab 17.11.
+
+{{< /history >}}
+
+Reachability shows whether a vulnerable package is actively used in your application.
+Vulnerabilities in packages that your code directly interacts with pose a higher risk than those in unused dependencies.
+Prioritize fixing reachable vulnerabilities, as they represent real exposure points that attackers could exploit.
+
 ## Query risk assessment data
 
 Use the GraphQL API to query the severity, EPSS, and KEV values of vulnerabilities in a project.
@@ -72,6 +84,7 @@ client.
           isKnownExploit
           cve
         }
+        reachability
       }
     }
   }
@@ -99,6 +112,7 @@ Example output:
               "isKnownExploit": false,
               "cve": "CVE-2019-3859"
             }
+            "reachability": "UNKNOWN"
           },
           {
             "severity": "CRITICAL",
@@ -113,6 +127,7 @@ Example output:
               "isKnownExploit": true,
               "cve": "CVE-2016-8735"
             }
+            "reachability": "IN_USE"
           },
         ]
       }

doc/user/application_security/vulnerability_report/_index.md

@@ -56,7 +56,10 @@ For projects and groups, the vulnerability report contains:
 - Filters for common vulnerability attributes.
 - Details of each vulnerability, presented in a table.
 
-For some vulnerabilities, the details include a link to the relevant file and line number in the default branch. For CVE vulnerabilities, you can also view the KEV status and the CVSS and EPSS scores in the vulnerability report. For more details on the security scores, see [vulnerability risk assessment data](../vulnerabilities/risk_assessment_data.md).
+For some vulnerabilities, the details include a link to the relevant file and line number in the
+default branch. For CVE vulnerabilities, you can also view the KEV status, CVSS and EPSS scores,
+and reachability information (Beta) in the vulnerability report. For more details on the security
+scores, see [vulnerability risk assessment data](../vulnerabilities/risk_assessment_data.md).
 
 For projects, the vulnerability report also contains:
 

spec/graphql/resolvers/work_items_resolver_spec.rb

@@ -133,7 +133,7 @@ RSpec.describe Resolvers::WorkItemsResolver, feature_category: :team_planning do
       end
 
       it 'batches queries that only include IIDs', :request_store do
-        result = batch_sync(max_queries: 11) do
+        result = batch_sync(max_queries: 15) do
           [item1, item2]
             .map { |item| resolve_items(iid: item.iid.to_s) }
             .flat_map(&:to_a)
@@ -143,7 +143,7 @@ RSpec.describe Resolvers::WorkItemsResolver, feature_category: :team_planning do
       end
 
       it 'finds a specific item with iids', :request_store do
-        result = batch_sync(max_queries: 11) do
+        result = batch_sync(max_queries: 15) do
           resolve_items(iids: [item1.iid]).to_a
         end