Skip to content

Annotate policy yaml with a comment next to IDs

Imam Hossainrequested to merge
497774-when-generating-policy-yaml-add-a-comment-next-to-ids-that-contains-the-name-corresponding into master

What does this MR do and why?

This MR annotates policy.yml with comments next to IDs to give the user more context about what record the ID refers to.

Why?

When working with security policies through the policies editor UI, the comments in the existing policy.yml file or in the new policy.yml file get lost in the process as we load the YML to a Ruby hash and dump it back to YML. The Ruby library doesn't retain comments in the process. This is a known limitation of the underlying library. We have explored different brute force workarounds here to solve it, but they are not suitable for our use case.

Instead, we choose to annotate the policy.yml file first with auto-generated comments next to the different types of IDs to help identify the referenced record. This will partially solve the customer problem, as the comments are often used for identifying the IDs in the YML.

Implementation:

We will annotate the following ID fields:

  • User approver IDs in MR approval policy rules
  • Group approver IDs in MR approval policy rules
  • Including/excluding Project/Group IDs in Policy Scope
  • Compliance framework IDs in Policy Scope
  • Skip CI user IDs in SEP/PEP policies
  • Group IDs in approval settings exceptions ( for Group-level Merge Request Approval Policies for block_group_branch_modification )
  • Custom Role IDs in role approvers

References

Screenshots or screen recordings

Before After
image image

How to set up and validate locally

  1. Enable the feature flag locally from console
Feature.enable(:annotate_security_orchestration_policy_yaml)
  1. Navigate to "Secure => Policies" for a project/group
  2. Create / Edit a policy referencing some ID fields. (Refer to the fields mentioned in the #Implementation section).

Example: Group MR approval policy

Policy.yml 
approval_policy:
 - name: MR Approval Policy
   description: ''
   enabled: true
   policy_scope:
     groups:
       including:
         - id: 24
     projects:
       excluding:
         - id: 3
         - id: 2
   rules:
     - type: scan_finding
       scanners: []
       vulnerabilities_allowed: 0
       severity_levels: []
       vulnerability_states: []
       branch_type: protected
   actions:
     - type: require_approval
       approvals_required: 1
       group_approvers_ids:
         - 24
         - 22
         - 143
       user_approvers_ids:
         - 1
         - 5
       role_approvers: []
     - type: send_bot_message
       enabled: true
   approval_settings:
     block_branch_modification: false
     block_group_branch_modification:
       enabled: true
       exceptions:
         - id: 24
     prevent_pushing_and_force_pushing: false
     prevent_approval_by_author: false
     prevent_approval_by_commit_author: false
     remove_approvals_with_new_commit: false
     require_password_to_approve: false
   fallback_behavior:
     fail: closed
  1. Create Merge request with the changes
  2. The changes in the merge request should Include comments next IDs

Other Test Cases:

  • When the project has existing policy.yml file with IDs, the first MR with policy annotations will also annotate the existing ID fields of the policy.yml
  • Once the annotations are in place, subsequent updates to the existing policy.yml should only introduced annotations to current policy

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #497774 (closed)

Edited by Imam Hossain

Merge request reports