MR Approval Policies Warn Mode (#15552) · Epics · GitLab.org

MR Approval Policies Warn Mode

# Release notes  # Problem to solve  As a security engineer who is responsible for creating security policies for my organization, I want to understand the impact of a security policy before I enable it, so that I do not disrupt development teams. Security engineers, when they introduce new changes that negatively impact development teams, can lose trust from those teams when unnecessarily impacting the development process. Today, validating the impact of a policy requires creating test projects and scenarios, trialing with a subset of projects, and other involved tasks to ensure that the security team is confident in the new policy they may be creating, or to identify the potential impact of changing an existing policy. Some customers also have different strategies for rolling out security programs. They are often balancing between security/compliance requirements and developer velocity. Supplying a Warn Mode for Security Policies gives AppSec teams a more versatile tool for deploying their program, granting them with ability to apply policies with a lighter touch in a high-trust environment or to increase the level of enforcement where the security and compliance oversight is necessary. # :chart_with_upwards_trend: Target metrics 1. 30% increase in number of MR approval policies created within 3 months. * **Why**: Security teams are more willing to create policies when they can test impact first without blocking developers # Intended users  * [Amy, Application Security Engineer](/handbook/product/personas/#amy-application-security-engineer) * [Alex (Security Operations Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#alex-security-operations-engineer) * [Cameron (Compliance Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#cameron-compliance-manager) # User experience goal  Moved previous concepts to "Archive" at the bottom of the page. Working on a streamlined workflow in [FigJam](https://www.figma.com/board/R7HtTIR2uLOt9I9dvyyCQi/MR-approval-policies---Warn-Mode?node-id=0-1&t=2ReayNDZaX0yyRst-1). ![MR_approval_policies_-_Warn_Mode](/uploads/b68f29b902d80d5a256ccc18c1a8f107/MR_approval_policies_-_Warn_Mode.jpg) _Screenshot - Apr 1 2025_ **WIP DESIGNS** (as of April 30)**:** [https://www.figma.com/design/Mt0Jf0PRatC5y3epaKUaX6/Warn-Mode--MVC-proto?node-id=0-1&p=f&t=5jAnF9OtZoPIVvuM-0](https://www.figma.com/design/Mt0Jf0PRatC5y3epaKUaX6/Warn-Mode--MVC-proto?node-id=313-44376&p=f&t=KA90aLrVForZsM6P-0) # Proposal  1. Introduce a new enforcement mode configuration in the policy editor (radio buttons with two options), allowing users to choose "Warn" vs "Enforce". 2. The new mode will make it clearer to users how to configure MR approval policies to avoid blocking developers while still incentivizing developers to take action. 3. Warn mode would generate the YAML for current functionality to require 0 approvals on the MR, which generates the security approval rule, but makes it optional. It would also generate YAML for setting the bot comments to true. 4. When Warn mode is enabled, do not enforce project override settings. Instead, we will only report projects that do not meet the requirements (where possible). Update the settings area to make it more apparent that we will no longer enforce settings with Warn mode. 5. When Warn mode is enabled, toggle the ability for developers to be allowed to "dismiss findings". When a finding that violates a policy is dismissed, require a comment/reason for the dismissal which will be tracked and made visible for security teams to review. This will incentivize developers to address policy violations, but they may dismiss findings where there may be valid reasons. Dismissals will include `dismissed as` with a dropdown of categories for dismissal, as well as a comment section. A dismissal would dismiss all policy violations and would not require dismissals for each individual violation. 6. When an MR is merged after a policy has been dismissed or approved. Capture the state of the MR and any violations present at that point. Store this in the vulnerability database with any security findings. Store in the Dependency list database for any license compliance findings. Additionally use for reporting audit events. For "any merge request" requirements, generate an audit event. 7. When a finding that is a policy violation is merged and reaches the `default branch`, maintain an indicator in the vulnerability's "activity" column. This may appear as a unique icon with a hover state "this vulnerability violates policy "Policy Name - 1". 8. Include information in the vulnerability "history" to also show a record of the vulnerability's history as a policy violation, and that a user chose to dismiss the finding and the reasoning for doing so. ~~Allow for the vulnerability report to be filtered to view vulnerabilities that violate polices.~~ Due to limitations with the vulnerability report filtering with elastic search, instead provide an API endpoint that can be used to list all the vulnerability UUIDs 9. Generate an audit event when a policy violation is dismissed. Surface the event in the `Security Policy > Audit Log` in addition to `Audit events`. Include the following: 1. MR author 2. Approvers 3. Policy violation details 1. Findings violating the policy and vulnerability severity 2. Dismissal reason # Out-of-scope for MVC / TBC in the future 1. Add a widget to the security dashboard for "Policy Violations" that helps give AppSec teams insight into the success/progress of their policy efficacy and adoption (regardless of if they are using Warn Mode or Enforcement Mode). 1. Count of violations by severity in branches targeting the `default` branch. 2. Count of dismissals 3. Count of vulnerabilities on the `default` branch that contain `policy violations` (either dismissed when audit mode is enabled or approved exceptions). 4. Projects violating settings rules (e.g. push / force push is too permissive). # Dependencies 1. ~"group::security insights" - 1. Introduction of Policy Activity, allowing users to filter vulnerabilities by "Policy Violations". 2. Surface data in Vulnerability database that can be used as history in the vulnerability object (e.g. dismissed in merge request, risk accepted in merge request). 3. Security policies group to introduce. We'll just need review support. 2. ~"group::code review" - 1. Introduce a button/modal to dismiss policy requirements when a policy is set to "Warn" mode. 2. Security policies group to introduce. We'll just need review support. 3. ~"group::compliance" 1. Add audit events with existing audit event framework. 2. No action required by compliance, but guidance/review may be required. # Further details  # Permissions and Security  # Documentation  # Availability & Testing  # Available Tier  # Feature Usage Metrics  # What does success look like, and how can we measure that?  # What is the type of buyer?  # Is this a cross-stage feature?  # What is the competitive advantage or differentiation for this feature? # Links / references # Archive <details> <summary>Previous designs / concepts</summary> <table> <tr> <th>Current state</th> <th>Proposed - Add a new action option for "Warn"</th> </tr> <tr> <td> ![image.png](/uploads/76fc7423b182dee489b5ff3242cbef81/image.png){width="526" height="264"} * In the current state, it's possible to trigger a bot comment and generate an approval rule that requires 0 approvals, making the approval optional. * Bot comments will be generated and will not require action, but can warn users there are policy violations per the policy rules. * Once https://gitlab.com/gitlab-org/gitlab/-/issues/474853 is addressed, comments will still be generated when policies "fail open". </td> <td> ![image.png](/uploads/9a34b8b1854ca1d381ceaa2463c24d3c/image.png) * On hover, give users more context for Warn mode: “Warn mode will generate bot comments for detected violations and generate an approval rule that is Optional.” * Rather than assuming users want to require approvers by default, we may want to default to Warn or require users to choose which actions they prefer. </td> </tr> </table> | New "Warn" Action | YAML generated is unchanged | |-------------------|-----------------------------| | ![image.png](/uploads/bb6c1cc0c6a6853531b1257a5c717f11/image.png) | ![image.png](/uploads/e638f0f20e40dc43e43af15190ed0daf/image.png){width="890" height="518"} | We're still considering the best way to surface violation data outside of the MR for AppSec teams. Here are a few concepts: #### MR attribute to search and filter in "Merge Requests" tab <table> <tr> <th>Search/filter MRs in a group/subgroup/project</th> <th> Add a new filter option for `Policy Violations Detected` </th> </tr> <tr> <td> ![image.png](/uploads/3287e9fd39219a30b0322929f5fe417c/image.png){width="696" height="442"} </td> <td> ![image.png](/uploads/ef3f2e2ab116390ff0078364cd24da60/image.png){width="354" height="227"} * By adding an attribute to MRs, it will be easier for security and compliance teams who are monitoring the policies in "warn" mode to understand the impact. They could query or generate counts for MRs that have violations detected at different states, such as during the development process (prior to merge to default). Or they could query MRs that were merged while still having violations detected - e.g. approved with exceptions. * Whenever policies detect violations, we generate a bot comment with details. At this point, we could update the MR record as well to update the state for `violations` to `true`. </td> </tr> </table> #### Add violation attribute/metadata to Vulnerabilities and search/filter vulnerabilities that violate a policy directly in Vulnerability Report <table> <tr> <th>Vulnerabilities that violate a policy directly in Vulnerability Report</th> </tr> <tr> <td> ![image.png](/uploads/aa8001d8c045175aa3f0cec970945fb9/image.png){width="653" height="412"} * Violations listed in the vulnerability report would have associated metadata that indicates the vulnerability also violations policies. This could give AppSec teams a tool for better filtering out vulnerabilities based on the rules defined in a policy (which could be fairly advanced/custom as policies evolve). * Consider ignore policies, exceptions for individual CVEs or vuln classes, re-rating policies, etc. The policies could do more of the heavy lifting compared to having tons of filter options like "OWASP Top 10". Add rules to your policies, filter the results based on if detected vulns violate the policies configured. * This would require the vulnerability report to allow for vulnerability data to be surfaced for non-default branches as the most common use case is detecting new vulnerabilities that would be introduced in a merge request that is targeting the default branch. * We'd also need to consider if we could/should surface other policy violations outside of application vulnerabilities (such as configuration violations). </td> </tr> </table> #### Create a dashboard that we supply in the Policies tab #### <table> <tr> <th>Generic policy executions, failures, errors, and violations view</th> <th>Instead of a more generic approach, we could have a view focused on MR Approval Policy violations</th> </tr> <tr> <td> ![image.png](/uploads/4dc604bcd72cfeb3296f73d69a5999e5/image.png) * This approach may be more aligned with https://gitlab.com/groups/gitlab-org/-/epics/6770 but would additionally consider executions and violations, not only failures/errors. * Users would be able to learn more about coverage of their policies. Did they execute in all projects properly? Were there configuration errors? Is a policy failing to be applied in a particular project? * Where are policy violations occurring and how many are there? * Which groups, subgroups, or projects require the most attention? </td> <td> ![image.png](/uploads/0cd7cf16dded3c4e08b807f6b42dadd5/image.png){width="1850" height="1643"} * Group, subgroup, and project structure that allows you to drill down and see where MR approval policy violations are detected, get a sense of severity/priority, and determine which can be most readily addressed. * Provide an approach to determine which violations, if addressed, have the greatest return or impact on security. * Note: While useful, there is a concern/risk this may overlap with the vulnerability report itself to some extent. </td> </tr> </table> </details>   > [!important] > > This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.

epic