# Overview Today, the Project, Group, [Vulnerability Report](https://docs.gitlab.com/ee/user/application_security/vulnerability_report/), [Dependency List](https://docs.gitlab.com/ee/user/application_security/dependency_list/), and [Security Dashboards and Security Center](https://docs.gitlab.com/ee/user/application_security/security_dashboard/) only show vulnerabilities and dependencies from `default` branch (which for most projects is `master` or `main`). The [merge request security widget](https://docs.gitlab.com/ee/user/application_security/index.html#ultimate) and [pipeline security tab](https://docs.gitlab.com/ee/user/application_security/vulnerability_report/pipeline.html) show vulnerabilities introduced on the feature branch. The differentiation between `default` branches and `feature` branches was made because the `default` branch is the branch that typically reflects a production environment. The merge request and pipeline security reports show what would be introduced if the vulnerabilities introduced on the feature branch are not fixed before merging. This works for the majority of projects, however, there are common use cases where tracking vulnerabilities in addition to the `default` branch is a requirement. ## Current Status ### Closed Beta Progress (Iterations 1-3) ```glql display: table fields: title, state, assignee, updated, labels query: group = "gitlab-org" and state = opened and label = ~"Vulnerabilities Across Contexts::Iteration 1 (Closed Beta)" title: "Iteration 1 - Remaining Issues" limit: 20 ``` ```glql display: table fields: title, state, assignee, updated query: group = "gitlab-org" and state = opened and label = ~"Vulnerabilities Across Contexts::Iteration 2" title: "Iteration 2 - Remaining Issues" limit: 10 ``` ```glql display: table fields: title, state, assignee, updated query: group = "gitlab-org" and state = opened and label = ~"Vulnerabilities Across Contexts::Iteration 3" title: "Iteration 3 - Remaining Issues" limit: 10 ``` ### GA Progress (Iteration 4) ```glql display: table fields: title, state, assignee, updated query: group = "gitlab-org" and state = opened and label = ~"Vulnerabilities Across Contexts::Iteration 4" title: "Iteration 4 (GA) - Remaining Issues" limit: 10 ``` ## Epic Structure | # | Epic | Iteration | Release | |---|------|-----------|---------| | 1 | &20474 - Tracked Context Management | 1 (Closed Beta) | %18.10 | | 2 | &18653 - Vulnerability Management Across Contexts | 1 (Closed Beta) | %18.10 | | 3 | &19809 - SBOM Across Contexts | 2 (Closed Beta) | TBD | | 4 | &19810 - MR Upgrades for Cross Context Merging | 3 (Closed Beta) | TBD | | 5 | &20476 - Security Dashboard Across Contexts | 1 (Closed Beta) | %18.10 | | 6 | &19372 - Scalability Upgrades (Partitioning) | 4 (GA) | TBD | | 7 | &20475 - Tracked Context Quota Management | 4 (GA) | TBD | | 8 | &18659 - Quality of Life Improvements | 4 (GA) | TBD | | 9 | &18722 - Supporting Merging Branch Workflows | 5 (Future) | TBD | **Iterations 1-3 (Closed Beta):** Core functionality for select customers. **Iteration 4 (GA):** Scalability and improvements for general availability. **Iteration 5 (Future):** Extended workflows. ### Supporting Epics - &2565 - Architecture Document - &17726 - Filtering for Releasing Branches (closed) - &17776 - Track Security Posture of Releases (closed) ## What branches do users want to track in addition to the `default` branch? - Releasing Branches * Protected branches * Document vulnerabilities remaining in a specific release (i.e. at a designated commit point/tag point) * Maintenance branches often live alongside the current production branch for patches and hot fixes * Maintaining multiple versions of self-managed software, i.e. multiple supported versions of an operating system - Feature branches * Tracking vulnerabilities through the software development lifecycle, i.e. development, staging, production ## Jobs to Be Done 1. Release attestation 2. Reporting on Developer Behavior 1. What vulns 'never' get merged 2. What branches are more vulnerable than not 3. Improve vulnerability history for developers 4. Improve security policies (for new and old vulns) 5. Secure Dev, QA, and Prod # Open UX Considerations By Section ### **1. Dependency List** * **Branch Awareness:** * Should dependencies be listed per branch or aggregated across branches? Current thinking is that this should be defaulted to main with filters supplied to select another branch. * Should multiple branches be selected on this page? Likely not, as an SBOM is usually most relevant to whats in production anyway. * If a dependency is updated in `main` but still outdated in `feature-x`, should it be shown as "Fixed" or "Pending": Likely shown as fixed assuming the filter is defaulted to main, with a badge suggesting that the feature-x branch has an outdated dependency. * **Export & SBOM Challenges (SPDX, CycloneDX):** * Do we export an SBOM per branch, or a single SBOM representing the default branch? The export should export based on the applied filters (likely most exports will be for main, or less likely a single dev branch. Exporting multiple dev branches at once seems unlikely) * If exporting per branch, do we include a **"Branch"** field in the SBOM? The SBOM can have the branch name in the title of the export, since multiple branches seems to be an unlikely scenario. * **Performance & Scaling:** * If a polyrepo has **thousands of dependencies** across multiple branches, how do we prevent performance bottlenecks when fetching dependency data? ### **2. Vulnerability Details** * **Branch-Specific Context:** * Users need to know **which branch(es)** the vulnerability appears in. * Consider a **"Branch Occurrences"** section showing all branches where the vulnerability exists. * **Path & SBOM Complexity:** * If a vulnerability exists in different dependency paths per branch, how should we display that? * Example: * `main`: `spring-boot → log4j` (vulnerable) * `feature-y`: `spring-boot → jackson → log4j` (also vulnerable) * Should the UI show one path per branch or all paths together? Should we factor this out? * **Fix Versions & Status Indicators:** * If a fix is applied in one branch, should the UI show "fixed" or "still vulnerable in other branches"? Consider "Fixed in Default Branch, Pending Merge" as a status. ### **3. Vulnerability Report** * **Branch-Aware Filtering:** * Users should be able to filter vulnerabilities **per branch** and compare branches to assess security drift. Should the default view show **all branches** or **just the default one**? * **Handling Duplicate Vulnerabilities Across Branches:** * If a CVE appears in `feature-x` but has already been fixed in `main`, should we still show it in the report? * What is the default view? Main? Or - consider tagging vulnerabilities with **"Not in Default Branch"**. * Sorting conflicts: If a vulnerability is resolved in `main` but exists in an old branch, should it still show up in "Open" vulnerabilities? Or only if its filtered to * **Integration with Filters (CVSS, EPSS, KEV, etc.):** * Do KEV-listed vulnerabilities **count** if they are present in non-default branches? Probably just keep the metadata for now * Should we have a **"Has Been Merged"** filter to identify CVEs that will eventually be fixed in `main`? ### **4. Security Dashboard** * **Filtering by Branch:** * Users must be able to select which branches they want to see security trends for. * Consider defaulting to main or allowing users to set persistent branch filters. * Aggregation complexity: Does "Vulnerabilities Over Time" include non-default branches by default? How do we represent that without overwhelming users? Probably just single branches. * **Historical Tracking & Vulnerability Age:** * If a vulnerability exists in one branch but not another, how should "vulnerability age" be calculated? It should be filtered by branch? * Should branch merges reset the age, or should we track across branches? It should probably be tracked across branches? * **Top CVEs & Exposure Metrics:** * If a CVE exists in multiple branches, should it be counted **once** per repository, or per branch? Probably once. Could Consider adding a toggle: "Aggregate by project" vs. "Show per branch". ### **5. Security Tab in the pipeline** * **Branch-Specific Vulnerability Status:** * Users running scans in feature branches need clear indicators of whether vulnerabilities exist **only in this branch** or also in `main`. * **Pipeline Merge Request Integration:** * If a pipeline detects a vulnerability that is **not in `main`**, should the UI prompt users to fix it before merging? This should be addressed with security policies * **Historical Tracking & Regression Prevention:** * If a vulnerability was previously fixed in `main` but reappears in a feature branch, should the pipeline indicate it as a **regression**? This could be cool a new feature. ### **6. Security Policies** 1. Should policies be applied differently to vulnerabilities found in default branch (older) or found in feature branches first (new). Other Notes * https://gitlab.com/gitlab-org/gitlab/-/issues/534479#note_2437825276 # Proposal Enable storing and tracking of vulnerabilities for locations other than `default` branch, allowing users to toggle between branches on the [Vulnerability Report](https://docs.gitlab.com/ee/user/application_security/vulnerability_report/), [Dependency List](https://docs.gitlab.com/ee/user/application_security/dependency_list/), and [Security Dashboards and Security Center](https://docs.gitlab.com/ee/user/application_security/security_dashboard/). ## Closed Beta Requirements 1. **Branch limits:** Starting at 1 tracked branch per project, scaling up to 16 as we gain confidence in GitLab's infrastructure during closed beta. 2. **Untracking:** Users can remove branches they no longer want to track. *(Implemented)* 3. **Export on untrack:** Users can export vulnerability data for branches being untracked. *(UI built, needs testing - may need additional issues for GA)* 4. **Vulnerability report:** Users can see which tracked branches a vulnerability is present in. 5. **MR/Pipeline reports:** Continue to show vulnerabilities introduced on feature branches. If the target branch is tracked, vulnerabilities appear as existing. 6. **Group-level:** Group-level Vulnerability Reports and Security Dashboards are being worked on for closed beta. ## Outstanding Questions <details> <summary>1. Will we show all the vulnerabilities from all the branches by default on the vulnerability report page?</summary> **Decided:** By default, the Vulnerability Report at the project and group level will be filtered by the default branch. If the user decides to remove the filter, ALL vulnerabilities from all branches will need to load on the page. Filtering by one branch at a time will meet many (most?) use cases. However, there are use cases where users will need to look at multiple branches to know what branches the vulnerability exists on. *Status: Implementation in progress.* </details> <details> <summary>2. What would happen when someone dismisses a vulnerability that exists on multiple branches?</summary> **Decided:** Initially, dismissals are per-branch (each finding can be dismissed independently). Cross-branch bulk dismissal will be added in a future iteration. *Status: Per-branch dismissal in progress. Cross-branch dismissal tracked for Iteration 5.* </details> <details> <summary>3. What will happen when someone adds a comment to a vulnerability that exists in multiple branches?</summary> **TBD:** Design work needed. CC @beckalippert @mclausen35 for UX input. </details> <details> <summary>4. Should we proceed with the 1:1 Vulnerability/Finding relationship work (&10819)?</summary> **Resolved - No.** We are going the opposite direction. With VAC, Findings represent branch-specific instances of a vulnerability (one per branch), while Vulnerabilities represent the canonical vulnerability definition. This 1:N relationship is intentional and core to the VAC architecture. </details> Architecture Document https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/track_vulns_across_branches/