Skip to main content

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

Project description

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):

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 project
  • 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

Tokens

gitlabcis requires one of the following tokens:

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

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 git@gitlab.com:gitlab-org/govern/compliance/engineering/cis/gitlabcis.git
cd cis-benchmark-scanner
make install

Usage

The following syntax is expected:

gitlabcis URL OPTIONS

Screenshot

results

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

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 (docs/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 (docs/CONTRIBUTING.md) for more information.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gitlabcis-1.4.1.tar.gz (545.5 kB view details)

Uploaded Source

Built Distribution

gitlabcis-1.4.1-py3-none-any.whl (256.8 kB view details)

Uploaded Python 3

File details

Details for the file gitlabcis-1.4.1.tar.gz.

File metadata

  • Download URL: gitlabcis-1.4.1.tar.gz
  • Upload date:
  • Size: 545.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for gitlabcis-1.4.1.tar.gz
Algorithm Hash digest
SHA256 a3558b74aaa13165b38063af842a4b361847355d1756cdd98e4bcef9d71d6591
MD5 86b650ce6833d19d97e239f154ec2b05
BLAKE2b-256 bdd64a6c246c0d3b34e2665774e3b0040f811ceb413da8f3cb1385123b1485af

See more details on using hashes here.

File details

Details for the file gitlabcis-1.4.1-py3-none-any.whl.

File metadata

  • Download URL: gitlabcis-1.4.1-py3-none-any.whl
  • Upload date:
  • Size: 256.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for gitlabcis-1.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e878ba5bb83b632748a6325e5d2f7df7441e377946290a0d0d312f384e932c3a
MD5 0321b4a721ea48f93e7fb51d7c37b25e
BLAKE2b-256 f88a70e061e0dada51056fbb9181a5b8c266a244e2074727d88e0b661cb29d82

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page