Compliance Policy Projects

Purpose of this guide

This guide will walk you through connecting GitLab's Security Policy Projects with your Namespace Configuration project's Infrastructure-as-Code to ensure you are taking advantage of mutually re-inforcing controls.

What is a Compliance Policy Project?

Security Policy Projects make it easy to enforce policies across projects within a namespace or subgroup.

They work hand-in-hand with the controls enforced by your Namespace Configuration project to provide a full set of security and compliance controls to ensure your development is following your Configuration Management controls and running the proper security scans.

Security Policy projects can be created either through the GitLab UI or directly within your Namespace Configuration project. We'll document both methods below.

Creating a Namespace-wide Security Policy Project

Via Namespace Configuration

Creating a Security Policy Project is no different than creating a normal project and adding security_policy_project_scope: namespace to link this project to the entire Namespace.

./cf-workshop.yml

projects:
  namespace-security-project:
    name: Namespace - Security Policy Project
    description: Security Policies to be applied to the entire namespace
    visibility: private
    security_policy_project_scope: namespace

Via GitLab UI

Security Policy Projects can easily be created via the GitLab UI from the Policies tab. Once you've created a Policy Project in this manner, it is good practice to pull it into your Namespace Configuration project so that approval rules and branch protections can be set appropriatly.

./cf-workshop.yml

projects:
  namespace-security-project:
    name: Namespace - Security Policy Project
    description: Security Policies to be applied to the entire namespace
    visibility: private
    security_policy_project_scope: namespace
    import_id: <your project's ID>

Security Policy Projects for Subgroups and Projects

Security Policy Projects can also be created for subgroups or individual projects, instead of the entire Namespace. You can do this via both the Namespace Configuration project directly as well as the GitLab UI, same as for Namespace-scoped projects.

Creating the Security Policy Project

Use security_policy_project_scope: assigned to create or import a security policy project that will be available to be assigned to Subgroups and Projects.

./cf-workshop.yml

projects:
  namespace-security-project:
    name: Assigned Security Policy Project
    description: Security Policies to be applied to specific subgroups or projects
    visibility: private
    security_policy_project_scope: assigned
    # import_id: <your project's ID> use this setting if you created the project via GitLab UI

Associating Security Policy Project with Subgroups and Projects

The configuration for assigning a Security Policy Project is the same whether assigning to either a Subgroup or a Project. Add the following bit to either the subgroup or project that should be associated with the Security Policy Project. Multiple subgroups and projects can be associated with a single Security Policy Project.

security_policy_project:
  key: <project_yaml_key>
  # set `import` to true if you associated the subgroup or project
  # with the Security Policy Project in the GitLab UI.
  # Set to false or omit this setting otherwise
  import: <false|true>

Subgroup Policy Project Example

Here is a full example of creating a Security Policy Project and associating it with a Subgroup.

./cg-workshop.yml

subgroups:
  program_office:
    name: ProgramOffice
    description: Projects managed by ProgramOffice
    visibility: public
    security_policy_project:
      key: program_office_policies

projects:
  program_office_policies:
    name: Program Office - Security Policies
    description: Security Policies to assign to the ProgramOffice subgroup
    visiblity: private
    security_policy_project_scope: assigned
    subgroup_key: program_office