# Plans within this epic will be carried forward in https://gitlab.com/groups/gitlab-org/-/epics/16664+. # Problem to solve As an application security analyst, I want to be able to manage my security policies, without needing to think about how or where they are stored. # User experience goal As a result of completing the changes planned in this epic: * Policy creators will be able to more intuitively create and enforce policies based on their access and permissions. * Policy creators will be able to complete their task of creating/updating policies without having to understand what a security policy project is and where it resides. * Policy creators will only need to think about how to scope policies, without also trying to understand policy links. * Policy creators will have a better understanding of the history of policy changes and the impact/scope of those policies without leaving the policy editor. * Policy creators will be given better context of access and permissions around policy management. Specific steps of the user experience flow are defined for each iteration. # Proposal (updated May 29, 2024) :tv: [See the walkthrough here!](https://youtu.be/XI6CuIgScbI) Today managing security policies requires understanding a lot of context within GitLab for the policy creator. This ranges from understanding "security policy project links", policy scoping, user permissions, and nuances of policy enforcement. This epic covers a number of iterations that will help to simplify policy enforcement, linking, scoping, and management. See the following iterations: ### Iteration 0: Complete UX Research ([UX Issue](https://gitlab.com/gitlab-org/gitlab/-/issues/456926), [UX Issue 2](https://gitlab.com/gitlab-org/ux-research/-/issues/2987)) - Completed We'll first validate some of our plans with users and the feedback may influence refinement of the following plans. * [Script](https://docs.google.com/document/d/1kxhfZMLab_VR0RnT4rzC9HBBMWys0Ek84qNok4--218/edit?usp=sharing) * [Prototype](https://www.figma.com/proto/TYSNp0nyA6DyJctFnvC7iC/Hide-SPP---Settings-MR?page-id=255%3A4573&node-id=255-4574&viewport=1332%2C423%2C0.19&t=BpAlSBV2E60IIzZH-1&scaling=min-zoom&starting-point-node-id=255%3A4574) ### Iteration 1: Add groups to security policy scope ([Epic](https://gitlab.com/groups/gitlab-org/-/epics/14149)) - Completed This is a simple change that would introduce the ability to scope a policy to a specific group/subgroup. Today we support scoping to a project, all projects in a group, or to projects associated with a compliance framework label. This enhancement will provide more options for filtering/enforcement, while also simplifying the next steps of our plan in this epic. ### **Iteration 2: Merge "All policy in linked group" and "Default mode" to "All project in linked group" (**[**Issue**](https://gitlab.com/gitlab-org/gitlab/-/issues/452210)**)** With this change, we will simplify the concepts of linking and scoping. We'll change how security policy project links work by default (default mode). Instead of enforcing on all projects in a group (by default), no projects will be enforced but will become "enforceable". Enforcement would be a result of applying a policy scope to each policy, which ensures policies only take effect where policy creators desire. Instead of requiring policy creators to create links in every group/subgroup/project individually, we will move this step into the policy creation process. Based on permissions/access, users will be able to determine which groups/subgroups/projects are in scope of enforcement. Organizations may leverage [custom permissions](https://docs.gitlab.com/ee/user/custom_roles/abilities.html#security-policy-management) to "manage security policy project links" along with their role in a given group/subgroup/project to determine if they can modify the policy scope. Based on their role/access, they can then apply a scope which ultimately governs the policy enforcement. Which groups, subgroups, or projects are enforced would no longer be relevant to the linking, but a matter of what is defined in the policy scope. Changing the behavior of linking may have an impact on existing customers and we'll need to explore how to ensure consistent behavior. This may require migration from the current "linking" behavior to ensuring the policy scopes are properly applied, along with migration. Or there may be another flow to allow users to opt-in to this change. This iteration depends on https://gitlab.com/gitlab-org/gitlab/-/issues/451327+. <table> <tr> <th>Direct manage cross-group via scope feature (No linking, no default mode)</th> <th>Permissions (This needs to be in the )</th> </tr> <tr> <td>    </td> <td> {width="1304" height="246"} </td> </tr> </table> ### Iteration 3: Hide the SPP in the workflow of editing and creating policies + edit policy.yaml file directly A common UX challenge with policy management is the fact that the policy editor and the policy.yml that stores the policy-as-code configuration are disconnected. Users leveraging the policy editor must navigate between the editor and the security policy project, which causes a lot of confusion and a poor experience navigating through each of the screens to accomplish a task. With this iteration, we'll simplify the workflow by bringing the steps into the `Policies` tab itself. The key steps in the workflow will be: 1. The policy creator visits the Policies tab (in the group/subgroup they manage policies) 2. They work to update a policy and merge the policy change 3. In the next screen, the breadcrumbs update to `Policies  > Change History > !MR` instead of taking users into the security policy project. The MR changes can be committed from there showing merged changes with the same path. 4. The user is then navigated to the change history list shows list, showing open/merged MRs for the given policy. As a result, policy creators can complete their tasks without leaving the policy editor. The design here will also reflect how to reference the `policy.yml`, allowing a user to copy the path or edit the YAML from the `Policies` tab directly. Alternatively, they may navigate the GitLab tree to the security policy project directly. <table> <tr> <th>Create via UI</th> <th>Edit direct policy.yml file</th> </tr> <tr> <td> Don't switch the user to the SPP, where the user creates the policy. Where the user sees the MR. At the MR page, after the user clicks on Merge, show a success banner with CTA back to the policy list or history.  </td> <td> Users click on the path of the file, it goes to a page where the user can read the YAML file. If user clicks on policy, leads user to the edit mode of policy   </td> </tr> </table> ### Iteration 4: Separate "My policy" and "Inherited policy" In this iteration, we'll make it clearer which policies are created _from_ a given group, subgroup, or project vs those that are being _enforced_ against a group, subgroup, or project. `My policies` will reflect the policies the policy creator is managing. `Inherited Policies` will reflect those that are being enforced. As users navigate across GitLab, they will easily be able to understand the source of a policy vs how they are impacted by policies being enforced against them. Within this iteration, we will also improve the way a policy `source` is displayed in the `Policies` tab. We'll ensure that the `source` for each policy listed in the `inherited` policies tab displays accurate information - pointing to the group/subgroup + the policy editor link. We would ensure that a policy scope is also accounted for, so policies do not appear in the list in projects based only on the "link" as it does today, but also the scope as established in earlier iterations. In sum, a policy should only appear in the list for projects that are actively enforced by the policy. Dependencies include https://gitlab.com/gitlab-org/gitlab/-/issues/451327+ and https://gitlab.com/gitlab-org/gitlab/-/issues/452210+. | My policy - all the policies created from the group Mobile banking | Inheritance policy - All the policy NOT created from group mobile banking, but enforce to mobile banking | |--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------| |  |  | ### Iteration 5: Permissions tab (Still in design / refinement) Next, we'll introduce a new tab in the policy editor that helps provide context to users around Permissions. In iterations above, we can rely on documentation to provide context to users, but this UI element will give more dynamic input to policy creators, so they may better understand who has permissions to do what with regards to policy management. This issue depends on https://gitlab.com/gitlab-org/gitlab/-/issues/452210+. | Show a list of permissions(needs refine) | Show the ability to allow review for policy changes | |------------------------------------------|-----------------------------------------------------| | {width="365" height="160"} | {width="284" height="183"} | ### Iteration 6: Hide the SPP completely from the project directory (Still in design / refinement) The last step in this epic, we will make some final changes to fully hide or abstract the concept of a security policy project. This will ensure that users need not rely on the concept of a `security policy project` to achieve their tasks. They may still define policies centrally, enforce them granularly, and gain all benefits of policy-as-code, but with a much simpler UX experience. | The path needs to be updated - potentially have the policy yml as a hidden file | |---------------------------------------------------------------------------------| | {width="819" height="144"} | ### Out-of-scope These changes will improve the overall UX of policy management, but there are other efforts that will continue to improve this outside of the scope of the epic - primarily https://gitlab.com/groups/gitlab-org/-/epics/6881+. Scoping/linking is especially confusing today for self-managed users as the concept of an Organization does not exist (yet). The improvements in this epic will largely simplify the experience for GitLab.com users with a single namespace, while introduction of Organizations and the ability to manage policies at an Org, paired with custom roles/permissions, will provide the ideal long-term experience for policy management. # **Typical personas and expected usage** | User(s) | Target | Permission | Rationale | |---------|--------|------------|-----------| | [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#sidney-systems-administrator) | GitLab instance | Owner | As systems administrator, Sidney is responsible for hosting the GitLab self-managed instance. Sidney is also responsible for defining an organization-wide list of security policy approvers. | | [Alex (Security Operations Engineer)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#alex-security-operations-engineer) | Security Policy project | Maintainer | As a security operations engineer, Alex must be able to change and approve changes to the policies | | [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) | Production project | Maintainer | As a software developer, Delaney needs to commit and merge changes to the application. | | [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) | Security Policy project | Developer | As a software maintainer, Delaney needs to know what policies apply to his projects so he can design code that is in compliance with them. Delaney also needs to propose edits to security policies (but cannot approve them). | | [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#sasha-software-developer) | Production project | Developer | As a software developer, Sasha needs to commit changes to the application. | | [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#sasha-software-developer) | Security Policy project | Reporter (or, for this first iteration, no access at all) | As a software developer, Sasha needs to know what policies apply to his projects so he can design code that is in compliance with them. Sasha is not able to propose edits to the policies. | ### Documentation ### Availability & Testing ### What does success look like, and how can we measure that? ### What is the type of buyer? ### Is this a cross-stage feature? ### Links / references <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> _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._ <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> _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._ <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> _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._ <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> _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._ <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION--> *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.* <!--triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION-->