Assess the configuration of GitLab groups and projects with cnspec

Rely on cnspec to ensure your GitLab groups and projects follow recommended security and operational best practices, such as enforcing two-factor authentication, managing group visibility, preventing forking outside your organization, scanning Terraform files stored in repos, and verifying project-level security settings.

You can scan individual projects, entire groups, or all the groups you have access to — making it easy to audit security across your GitLab environment.

Prerequisites

Before you begin, install cnspec.

Give cnspec access using a GitLab personal access token

To scan GitLab groups and projects, cnspec needs access through the GitLab API. You create a personal access token and then provide it when running cnspec commands.

To learn how to create a personal access token, read Personal access tokens in the GitLab documentation. We recommend creating a token with these scopes:

read_api — Required for scanning group and project configurations
read_repository — Required if you want to scan Terraform files or other repository contents

The token's level of access determines how much information cnspec can retrieve.

Configure a GITLAB_TOKEN environment variable

You can supply your personal access token to cnspec using the GITLAB_TOKEN environment variable. This avoids passing the token on the command line with every command.

On Linux / macOS:

export GITLAB_TOKEN=<YOUR_TOKEN>

On Windows, using PowerShell:

$Env:GITLAB_TOKEN = "<YOUR_TOKEN>"

When GITLAB_TOKEN is set, you can omit the --token flag from all the commands below.

Test your connection

Before running a full scan, verify that your token works by opening a cnspec shell:

cnspec shell gitlab --group <GROUP_NAME> --token <YOUR_TOKEN>

cnspec> gitlab.group.name
gitlab.group.name: "your-group-name"

If you see your group name, cnspec is connected and ready to scan.

Scan GitLab groups and projects

In GitLab, a group is a collection of projects (similar to a GitHub organization). You can scope your scans to a single project, a group, or all groups your token has access to.

Scan a group

To scan the configuration of a GitLab group, run this command:

cnspec scan gitlab --group <GROUP_NAME> --token <YOUR_TOKEN>

Scan all groups you have access to

To scan all the groups your token can access, run this command:

cnspec scan gitlab --discover projects --token <YOUR_TOKEN>

Scan a single project

To scan a specific project within a group, run this command:

cnspec scan gitlab --group <GROUP_NAME> --project <PROJECT_NAME> --token <YOUR_TOKEN>

Scan all projects in a group

To scan all projects in a group, run this command:

cnspec scan gitlab --group <GROUP_NAME> --discover projects --token <YOUR_TOKEN>

Scan Terraform files

To scan all Terraform files in all the projects discovered across your groups, run this command:

cnspec scan gitlab --discover terraform --token <YOUR_TOKEN>

Scan a self-hosted GitLab instance

By default, cnspec connects to gitlab.com. To scan a self-hosted GitLab instance, add the --url flag:

cnspec scan gitlab --group <GROUP_NAME> --token <YOUR_TOKEN> --url https://gitlab.example.com

Understand scan output

When a scan completes, cnspec prints a summary of all the checks it ran, grouped by policy. Each check shows a pass or fail result. For example:

✓ Pass:  Ensure the GitLab group visibility is set to private
✕ Fail:  Ensure two-factor authentication is required for the group
✓ Pass:  Ensure forking outside the group is prevented

At the end of the output, cnspec shows a risk score from 0 (no risk) to 100 (highest risk). Failed checks include remediation guidance to help you fix issues.

By default, cnspec applies the Mondoo GitLab Security policy, which covers group visibility, authentication settings, merge request approvals, branch protection, and more. You can also create your own policies or specify a particular policy bundle with --policy-bundle.

Example checks

Run cnspec shell gitlab --token <YOUR_TOKEN> to open the cnspec interactive shell. From there you can make checks like the examples below.

Ensure two-factor authentication is required for the group

cnspec> gitlab.group.requireTwoFactorAuthentication
[failed] gitlab.group.requireTwoFactorAuthentication
  expected: == true
  actual:   false

Ensure the GitLab group is private

cnspec> gitlab.group.visibility == "private"
[ok] value: "private"

Ensure group email notifications are disabled

cnspec> gitlab.group.emailsDisabled
[failed] gitlab.group.emailsDisabled
  expected: == true
  actual:   false

Ensure forking outside the group is prevented

cnspec> gitlab.group.preventForkingOutsideGroup
[failed] gitlab.group.preventForkingOutsideGroup
  expected: == true
  actual:   false

Ensure merge requests can only be merged when the pipeline succeeds

cnspec> gitlab.project.onlyAllowMergeIfPipelineSucceeds
[ok] value: true

Ensure the default branch is protected

cnspec> gitlab.project.protectedBranches.where( defaultBranch == true ).length > 0
[ok] value: true

Continuously scan your fleet

To move beyond one-off scans, set up a GitLab integration in Mondoo Platform. You get continuous monitoring across your GitLab groups and projects, a dashboard to track security posture over time, and integration with ticketing systems to manage remediation.

Learn more

To learn about all the GitLab resources and properties, read the Mondoo GitLab Resource Pack Reference.
To learn how to write checks, read Write Effective MQL.

Assess the configuration of GitLab groups and projects with cnspec

On this page