gitlabcis 1.20.0

An automated tool that assesses the GitLab CIS benchmarks against a project.

CIS GitLab Benchmark Scanner - gitlabcis

Background

On April 17th 2024, GitLab™ published a blog post introducing its Center for Internet Security® (CIS) GitLab Benchmark. With the goal to improve the security of the product and offer hardening recommendations to GitLab's customers. You can download a copy of the benchmarks which are published on the Center for Internet Security® website.

"The CIS GitLab Benchmark stemmed from a collaboration between CIS and GitLab's Field Security and Product Management teams. After numerous conversations with customers, we understood the need for a specific benchmark that would guide their hardening efforts. We conducted an in-depth review of GitLab’s product and documentation to understand how our offering mapped to CIS's Software Supply Chain Security Benchmark. After the initial draft was ready, it entered into the CIS consensus process, where the broader CIS Benchmark Community was able to review it and suggest edits prior to publication."

Ref: Creating the CIS GitLab Benchmark

Overview

gitlabcis is a Python® package which audits a GitLab project against the Center for Internet Security® (CIS) GitLab Benchmark. It includes recommendations-as-code formatted in YAML™.

GitLab Product Enhancement

Compliance Adherence Report

There is a larger effort to add the CIS Benchmark as a compliance standard to the Compliance Adherence Report.

• Once implemented, this will enable customers to automatically have visibility into whether there are additional measures they need to take in order to comply with the measures recommended in the CIS Benchmark.

Contributing back to GitLab

Through the course of developing this tool, the authors contributed 2 features to the GitLab product (#39):

• Show Crosslinked/related issues in merge requests via the API
• Groups API: Add Restrict group access by Domain

Table of Contents

[[TOC]]

Disclaimers

Disclaimer	Comment
This tool assumes that one is using GitLab for everything	For example, the first recommendation (1.1.1 - version_control): "Ensure any changes to code are tracked in a version control platform." Using GitLab automatically passes this control.
This tool cannot audit every recommendation	We have kept a record of every recommendation that we cannot automate. Review our limitations doc (docs/limitations.md), which highlights automation gaps in which a condition cannot confidently be automated.
This tool does not execute any write operations on your GitLab instance, group or project. No write actions are performed.	This tool is expressly designed to refrain from performing any write operations that may: modify, alter, change, or otherwise impact the configuration, data, or integrity of your GitLab project ensuring that no alterations or unauthorized adjustments are made to its state or contents.
This is not an official GitLab product	This repository was created by GitLab engineers and is not officially supported by GitLab.

Getting started

• Required:
  • You need to have python® & pip installed
  • One of:
    • GitLab Personal Access Token (PAT)
    • GitLab OAuth Token

Tokens

gitlabcis requires one of the following tokens:

Personal Access Token (PAT)

• Create a Personal Access Token (PAT).

You can either pass the token as an option or store it as an environment variable:

• GITLAB_TOKEN - (optional) Environment Variable
• --token / -t - (optional) gitlabcis token option

OAuth Token

• Create an OAuth Token.

You can either pass the token as an option or store it as an environment variable:

• GITLAB_OAUTH_TOKEN - (optional) Environment Variable
• --oauth-token / -ot - (optional) gitlabcis token option

Token Scope

• Required: Your token needs to have at least the read_api scope.
• (optional) Providing your token more scope will unlock more controls that require higher levels of permission.

Install

There's a number of ways to download the scanner. Please see them below:

Pypi

Install gitlabcis from pypi.org:

pip install gitlabcis

GitLab

Install gitlabcis from the package registry:

pip install gitlabcis --index-url https://gitlab.com/api/v4/projects/57279821/packages/pypi/simple

If you haven't already done so, you will need to add the below to your .pypirc file.

[gitlab]
repository = https://gitlab.com/api/v4/projects/57279821/packages/pypi
username = __token__
password = <your personal access token>

Install gitlabcis from source via clone, or our releases page

# make a clone (or create a local fork) of the repo
git clone [e-mail]:gitlab-security-oss/cis/gitlabcis.git
cd gitlabcis
make install

Usage

The following syntax is expected:

gitlabcis URL OPTIONS

Screenshot

Generate a report

To generate a report from the shell:

gitlabcis https://gitlab.example.com/path/to/project --token $TOKEN

Generate a json report: (Using the $GITLAB_TOKEN variable, you do not need to specify --token option)

gitlabcis \
    https://gitlab.example.com/path/to/project \
    -o results.json \
    -f json

To execute a single control:

gitlabcis \
    https://gitlab.example.com/path/to/project \
    -ids 1.2.3 # or multiple: 2.3.4 3.4.5 etc

Scan all sub-groups and projects under an instance or group (1 level deep by default):

gitlabcis https://gitlab.example.com/path-to-group --nest

Scan all sub-groups and projects up to 2 levels deep, writing per-entity JSON files to ./results/:

gitlabcis \
    https://gitlab.example.com/path-to-group \
    --nest \
    --depth 2 \
    --output-dir results \
    -f json

Scan with unlimited depth and a filename prefix:

gitlabcis \
    https://gitlab.example.com/path-to-group \
    --nest \
    --depth 0 \
    --prefix "audit_" \
    --output-dir results \
    -f json

Documentation

Review the gitlabcis documentation (./docs) directory - Something missing? Feel free to create contribute with a new issue.

License

gitlabcis was published using the MIT license, it can be reviewed in the ./LICENSE file.

Changelog

See the ./CHANGELOG.md for more information.

Developers

Code of Conduct

Review the heading section of contributing doc (CONTRIBUTING.md) for the code of conduct.

Security

Review our security policy (docs/SECURITY.md) document which outlines how to disclose a vulnerability.

Contributing

Do you want to contribute? - Fantastic! Check out the contributing doc (CONTRIBUTING.md) for more information.