## Business Case 1. This is the first iteration of non-default branch tracking. 2. This is the most oft-requested Security Insights feature request with [32 accounts totaling $30.6M](https://10az.online.tableau.com/#/site/gitlab/views/CustomerIssueDashboard/CustomerIssuesEpics?:iid=1) ARR requesting this. 3. It is a blocker to adoption because customers lack visibility and the ability to conduct vulnerability management for branches that are releasing artifacts to production. Providing this capability will provide a path for increasing the value of Ultimate, increasing adoption and in turn reducing churn and/or providing expansion opportunities. 4. Target metric 1. Metric: ‘Vulnerability Management Activity’ on Tracked non-default branches 2. Secondary Metric: Branches configured for tracking. 3. Target: Equal VM Activity on non default branches to default branches 4. Why? We are providing the same must-have vulnerability management flows for non default branches. If customers are treating those branches like they are default branches, we assume they are accomplishing the goal of the feature which is to support vuln management on branches with that are deploying live artifacts. In the interest of attempting to provide a Minimal Valuable Product within the desired timelines, it will likely be necessary for us to divide effort up by criticality to deliver an initial releases versus modifications and improvements we can make once the core functionality is defined. Iteration 1 will be the MVP release of Vulns Tracked Across Refs. The core tracking and reporting functionality should be part of this release, though certain behaviors, customization's and features may be pushed back to following iterations depending on available time. ## Product Requirement Scope This iteration should be seeking to fufill the following functionalities: As an appsec admin, I want to configure which branches are available for vulnerability and dependency scanning, so that engineers can focus on relevant branches without overwhelming the system with tracking every branch. 1. A dedicated configuration page where admins can define branch selection criteria 2. This configuration page should be permissioned in the same way other permissions are, which is how the config page is permissioned now. There should be no way to override this in the yaml today. 3. Ability to select branches using the following searches / predefined lists. * The ability to see all protected branches and select them or a subset of them * The ability to see all branches based on tag and select them or a subset of them * ~~Ability to search for branch name patterns using regex or wildcard matching (or normal text) (e.g., `release/*`, `v*.*.*`)~~ 4. An indicator to set a maximum number of branches to track per project to prevent scalability issues 1. For closed beta - a limit is not required but we must communicate the limit OR cap earlier on. 2. For open beta - we will limit the branches on the project level (project \* 2 = limit) 3. For GA - we will simply remove the closed branch beta label. 4. Implement a warning on the settings page as well, since some users might not know they can break self managed. 5. Changes to branch configuration are logged for audit purposes 1. If a branch is changed, then the data for the previous branch must be purged eventually. Users will be advised to produce SBOM exports and vulnerability report exports of the relevant branch for release attestation purposes, and advised that the data will be purged later. 6. ~~The branch configuration should allow users to configure whether the branch is 'merging' or 'long lasting/releasing'~~ 1. Long lasting/releasing branches should 1. Allow for local changes to vulnerability state 2. Duplicate vulnerabilities of the same type on the vulnerability report 3. Duplicate counts of vulnerabilities on the dashboard 2. ~~Merging branches should~~ 1. ~~Allow for global or broader-than-local changes to vulnerability state~~ 2. ~~Deduplicate vulnerabilities of the same type on the vulnerability report~~ 3. ~~Disallow for selection in the dashboard OR deduplicate against the branch it merges into~~ As an AppSec engineer, I want to view vulnerability and dependency information by branch, so that I can verify the security of all branches used in production releases. 1. See all vulnerabilities related to a specific branch in the vulnerability report. 1. SAST, ~~Composition Analysis~~ (tracked in iteration 2), DAST, Secrets are in scope. Other less adopted except OCS are also in scope. 2. OCS results are out of scope 2. ~~In the vulnerability details page, if a unique vulnerability is present in multiple branches, the vulnerability details page should include that vulnerability, the branches it is located, and its status in that branch.~~ 3. Detected at time should refer to the first detection of a vulnerability on a specific branch. IE each instance of a vuln on different branches should have different detection times. 4. ~~See all libraries present in a specific branch in the dependency list.~~ 1. ~~When the branch is set, the version of the library should always refer to the specific manifest file present in that branch.~~ 2. ~~All exports (CycloneDX, JSON, SPDX) should support exporting based on the selected filter.~~ 3. ~~If filtering on the dependency list is blocked by elasticsearch and the dependency is not resolved, then we could remove this requirement and track it in a seperate issue.~~ 5. The default view of the dependency list and vulnerability report should be default branch. 6. Users can select multiple branches at once on ~~both the dependency list and~~ vulnerability report. 1. If a user filters for a project(s) first, they need to see refs scoped to those selected projects  2. If a user filters for refs without projects being selected, we need to show all.  3. On the filter _value_, the associated project should be shown along with the branch name 4. On the vulnerability report, multiple branches per project can be selected. As an AppSec engineer, I also want to track vulnerability trends on the security dashboard branch, so that I can get a complete view of specific teams/products that represent that branch. 1. Allow for filtering by branch on the security dashboard. If a branch is selected. All vulnerabilities present in that branch should be aggregated in the same fashion. and all other filters should still be honored. 2. The default view of the should be default branch. The branches may be aggregated. 1. The default view at the group level should be the default branch of each project. ([Thread w/ design here](https://gitlab.com/gitlab-org/gitlab/-/work_items/579096#note_3062782345).) 3. Users should select only one branch per project at once (or stay on the default branch) to avoid deduplication. This is only required on the dashboard, the other pages should support multi-select. 4. If a user filters for a project(s) first, they need to see refs scoped to those selected projects  5. If a user filters for refs without projects being selected, we need to show all.  6. On the filter _value_, the associated project should be shown along with the branch name As an AppSec engineer, I also want to ensure my vulnerability management workflows are supported on non default branches in ways that correspond with its existence as a 'long lived releasing branch'. 1. ~~Extend the manual vulnerability creation flows to include a branch name. This should be available in the API and is required.~~ 2. ~~Autoresolution should function the same on a given branch as it does on the default branch. Vulnerabilities should only resolve if they are no longer detected on the branch they were seen on.~~ 3. State changes, severity changes, or comments to the vulnerability should default to be local changes (IE - just to the vuln on that branch) with an option to configure a global change to all 'related vulnerbilities' which are calculated in the vulnerability details page. 4. ~~Issues should be related to a vulnerability on a specific branch. The 'branch' metadata should be present in the issue content somewhere.~~ 5. ~~In a similar vein, JIRA tickets should be related to a vulnerability on a specific branch. The 'branch' metadata should be present in the issue content somewhere.~~ Other considerations in scope 1. ~~Webhook support for branch metadata is in scope.~~ 2. If a branch is merged, then the metadata from that branch should propogate into that branch for certain scan types. 3. If a branch is deleted, then (creating a survey Q to understand this) 4. The cascading of policies where applicable 1. MR policies will cascade to protected branches which is what happens now. 2. SEP and PEP will cascade to any branch. 3. Autoresolve is expected to cascade to all. ## Out of Scope 1. Tracking the lifecycle of vulnerabilities across branches 2. ~~Tracking branches specific to 'experimentation' - the primary use case is to track two feature branches with explicit releases. (such as a development branch on a local machine)~~ 3. Aggregate comparisons between branches. 4. Tracking vulnerability state in other branches in the MR widgets. 5. Filtering in the 'security center' 6. In the future - 'long lived releasing branches' should _not_ be deduplicated, but "branches that merge into main or releasing branch eventually" should be deduped on the dashboard view theoretically. Support for allowing customers to configure this, or doing it via automation, is important. 7. Apply security policies to specific branches in a project - the expectation is a policy will cascade to all branches in a project