### Release notes Policy Scoping provides granular management and enforcement of policies. Across both merge request approval (scan result) policies and scan execution policies, this new feature enables security and compliance teams to scope policy enforcement to a compliance framework or to a set of included/excluded projects in a group. While today all policies managed in a security policy project are enforced against all linked groups, subgroups, and projects, Policy Scoping will allow you to refine that enforcement policy by policy. This allows security and compliance teams to: * More easily manage policies centrally across their organization, while still enforcing policies granularly * Get a better sense of how the controls they are implementing and enforcing in GitLab roll up to the Compliance Frameworks they've defined * View and manage which policies are linked to a Compliance Framework through the Compliance Center * Better organize and understand their security and compliance posture ### Problem to solve Many users do not want to scan ALL of the projects in their group/workspace. Instead, they are only interested in requiring scans to run on projects that match certain criteria. Some examples include the following: * Scan only projects in my workspace that are required to meet SOC2 requirements * Scan only projects in my workspace that are marked as `Gold Support` projects * Scan only projects in my group that are marked as `Production` Similarly, approval requirements may vary based on the project, meaning Scan Result Policies should also allow for policies to be enforced only on projects with specified compliance labels. (Note: Designs or mocks are still needed to reflect changes in SRPs) ### Intended users * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) * [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst) * [Alex (Security Operations Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#alex-security-operations-engineer) ### Design proposal **Original design issue: https://gitlab.com/gitlab-org/gitlab/-/issues/379123/** 1. While editing or creating a new policy, introduce the "Scope" configuration for workspace/group level policy; the user can select either apply to all projects or projects with specific compliance framework labels. Users can also create a new framework label if needed. | Edit policy: introduce scope area - use compliance framework | Edit policy: introduce scope area - use group | When the user clicks on creating a new policy, open a modal window | tooltip | Edge case | Error message | |--------------------------------------------------------------|-----------------------------------------------|--------------------------------------------------------------------|---------|-----------|---------------| |  |  |  |  |  |  | 2. While editing compliance framework labels, users can see what policies are linked. If a project has the framework label, the linked policy will be applied to the project. In the compliance framework label area, users are able to link or remove a linked a policy | Framework edit area - expanded policy | after linked policy-pending | after pending- Merge page | After policy MR merged | edit policy drawer | |---------------------------------------|-----------------------------|---------------------------|------------------------|--------------------| |  |  |  |  |  | | MVC- Read-only and have hinted to direct user to policies | MVC- User can still click on the line to open the drawer to see details | MVC- if user has no edit right | |-----------------------------------------------------------|-------------------------------------------------------------------------|--------------------------------| |  |  |  | Solution validation completed in https://gitlab.com/gitlab-org/ux-research/-/issues/2287+. ### Further details #### JTBD this epic will address within the Compliance Configuration screens 1. I want to know what will happen when I apply a CF label to a project. #### JTBD this epic will address within the Security Policy screens 2. I want to enforce policies globally across all the projects in my group or for projects with specific compliance frameworks. #### Use cases 1. Users who want to manage policies centrally at the top-level group at the same level as the compliance frameworks. 2. In some very large organizations, the security team wants to enforce some organization-wide policies across the entire group, but also wants to allow individual business units, departments, or teams (some of which may have their own security teams) to layer on their security policies on top of the organization policies. For example, they may want to require Secret Detection to run for all projects, but then they leave it up to each business unit to choose which additional scans to run and whether or not to require MR approvals when Critical vulns are found. 3. For some large companies using Self-managed instances, compliance frameworks are created in the top-level groups. They may want a particular policy enforced across all TLGs, and thus they would create the label in each group, then scope the policy to target that framework (in all groups). It should be possible to create a policy in a SPP that is linked to multiple TLGs, and that the compliance framework can be used to scope/enforce policies in all of the groups. #### Existing users & impacts: 1. \~SaaS Today, users may establish security policy projects (SPP) in a separate subgroup, then link individual projects or sub-groups up to the SPP. This allows for granular enforcement of policies, to pick and choose the sub-groups or projects that are in-scope. We'll want to consider the path for users to move from this structure to using Compliance Frameworks. With our current approach, it's notable that projects may not appear within the UI, only sub-groups. 2. ~"self-managed" Today, users may establish security policy projects (SPP) in a separate a group/subgroup, then link individual projects, sub-groups, or groups up to the SPP. This allows for granular enforcement of policies, to pick and choose the sub-groups or projects that are in-scope. We'll want to consider the path for users to move from this structure to using Compliance Frameworks. With our current approach, it's notable that projects or additional top-level groups may not appear within the UI, sub-groups. Granted, the scope of compliance frameworks may only be the group, but it's not clear if current plans address these users' needs well. #### Constraints & Dependencies 1. Compliance Frameworks will enable users within a group to globally manage the policies that are enforced the group or any subgroups within it. They will not be able to make changes that impact other groups or sub-groups. 2. Only one security policy project can be linked in a given project, sub-group, or group at one time. 3. Compliance Frameworks are scoped to groups. There is no instance level, nor is there a sub-group or project level. While security policy projects can be linked to a group, sub-group, or project, and in the case of Self-managed users, this could span across top-level groups in an instance. 4. New policies can be created and then subsequently linked to the available Compliance Frameworks within the group. They cannot be directly created from a Compliance Framework. To create a policy that can be utilized by a Compliance Framework, policies must be defined within a security policy project that is linked to the group or any subgroups within it. This will require a merge request to update the policies in the SPP, and if the owners of the SPP are different from that of the Compliance Framework, they will need to work with the SPP owners to update the policies prior to linking them to a Compliance Framework. 5. Compliance Frameworks only support a single compliance framework label per project today. We have several prerequisites before Compliance Frameworks can support multiple labels. Currently labels are associated with compliance pipelines because they are a parent pipeline and the project pipeline is a child pipeline. Once users are able to utilize security policies and move off of compliance pipelines, we can introduce support for multiple compliance framework labels. 6. Only policies within a SPP that is linked to a group or subgroup will be available within the Compliance Framework. Polices created in a SPP that is linked to a single project would not be applicable to global compliance. ### Next steps (outside of the scope of this epic) 1. Deprecate and remove compliance pipelines ( ~"group::compliance" would be responsible for this piece) 2. Allow multiple compliance framework labels to apply to a single project ( ~"group::compliance" would be responsible for this piece) 3. Re-evaluate whether we might be able to simplify management in some way while still meeting the needs of large organizations with multiple independent business units. At this point in time, it is probable that our [Granular Permission](https://gitlab.com/groups/gitlab-org/-/epics/4035 "Custom Roles and Permissions") capabilities will have also improved significantly which may also open doors to additional possibilities that we are unable to address easily today. ### Permissions and Security This epic does not change the permissions ### Documentation ### Availability & Testing ### What does success look like, and how can we measure that? ### What is the type of buyer? ~"GitLab Ultimate" ### Is this a cross-stage feature? This feature will likely overlap and leverage the work being done by the ~"group::compliance" in [this Epic](https://gitlab.com/groups/gitlab-org/-/epics/4082 "Improve the concept of compliance frameworks"). ### Epic Planning Breakdown Issues will be shared between ~"group::security policies" and ~"group::compliance" . | \# | Description | Epic/Issue | Group | FE/BE | |----|-------------|------------|-------|-------| | 1 | Add ability in YAML-only editor to assign given policy to Compliance Framework (policy scope). Add logic needed to distinguish if a given policy should be applied in the project based on the selected Compliance Framework for the project. | https://gitlab.com/gitlab-org/gitlab/-/issues/428490+ | ~"group::security policies" | ~backend | | 2 | Add UI-editor to specify Policy Scope | https://gitlab.com/gitlab-org/gitlab/-/issues/428492+ | ~"group::security policies" | ~frontend | | 3 | Extend `group.complianceFrameworks` and \`\`project.complianceFrameworks`GraphQL APIs with`securityPolicies\` section where details about policy related to given Compliance Framework is listed and information if given user has ability to modify policies or not. | | ~"group::security policies" | ~backend | | 4 | List policies related to the given Compliance Framework in Compliance center | https://gitlab.com/groups/gitlab-org/-/epics/11480+ | ~"group::compliance" | ~frontend | | 5 | Add drawer to the Compliance Framework's Policy list with details about the given policy. | https://gitlab.com/groups/gitlab-org/-/epics/11480+ | ~"group::compliance" | ~frontend | | 6 | Add modal to Policy UI Editor to create new Compliance Framework <br>[Here is the create framework form](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/assets/javascripts/groups/settings/compliance_frameworks/components/create_form.vue?ref_type=heads) and here is the [modal component](https://gitlab.com/gitlab-org/gitlab/-/blob/a089cb8572a2633473e45f30ab178ce58444531c/ee/app/assets/javascripts/groups/settings/compliance_frameworks/components/form_modal.vue) | | ~"group::security policies" | ~frontend | | 7 | Add ability to [search](https://gitlab.com/groups/gitlab-org/-/uploads/44630a07aa345f490c4118c24955c0a8/linked-policy-framework.png) for policies in Compliance Center | https://gitlab.com/groups/gitlab-org/-/epics/11480+ | ~"group::compliance" | ~frontend | | 8a | Add ability to list all policies available for a given project and ability to link policy to the project (including `Link all policies`) in Compliance Center | https://gitlab.com/groups/gitlab-org/-/epics/11628+ | ~"group::compliance" | ~frontend | | 8b | (if required) Add ability to list all policies available for a given project and ability to link policy to the project (including `Link all policies`) in Compliance Center | https://gitlab.com/groups/gitlab-org/-/epics/11628+ | ~"group::security policies" | ~backend | | 9a | Add ability to create a new policy from Compliance Center view | https://gitlab.com/groups/gitlab-org/-/epics/11628+ | ~"group::compliance" | ~frontend | | 9b | (if required) Add ability to create a new policy from Compliance Center view | https://gitlab.com/groups/gitlab-org/-/epics/11628+ | ~"group::security policies" | ~backend | | 10 | Compliance Pipeline to Security Policy Migration | https://gitlab.com/groups/gitlab-org/-/epics/11275+ | ~"group::compliance" | ~frontend | ### Links / references https://gitlab.com/groups/gitlab-org/-/epics/4082 _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._ _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._ _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._ _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 --> *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 -->