Documentation

1. Purpose

This document describes the step-by-step procedure to configure GitLab so that the CBOM Source Code Discovery Sensor can successfully discover cryptographic material embedded in source code repositories, including:

Hardcoded private keys and certificates committed to source files
API tokens and secret strings stored in code or configuration files
SSH private key files tracked in repositories
Cryptographic configuration files (e.g., OpenSSL configs, key store references)

The procedure covers:

Creating a Personal Access Token (PAT) with least-privilege scopes
Creating a Project Access Token for single-project scoping
Configuring self-managed GitLab instance URLs
Configuring the CBOM sensor YAML
Validating the connection and reviewing common errors

2. Prerequisites

Before starting, ensure:

You have access to a GitLab account (GitLab SaaS at gitlab.com or a self-managed instance)
You are signed in as: A GitLab user with at least Reporter role on the target group or project, or An Administrator (for group-level tokens or self-managed configuration)
For self-managed instances: GitLab version 13.0 or later (Personal Access Tokens) or 14.1 or later (Project Access Tokens)
The CBOM Collector service has network access (HTTP/HTTPS) to the GitLab instance

3. Create a Personal Access Token

A Personal Access Token (PAT) grants the sensor read access to all projects visible to your GitLab account.

3.1 Open User Settings

Sign in to GitLab
Click your avatar in the top-right corner
Select Edit profile
In the left sidebar, click Access Tokens

3.2 Configure Token Details

Fill in the following fields:

Token name: cbom-source-discovery
Expiration date: Set an appropriate expiry (e.g., one year from today); leave blank for no expiry (not recommended)
Scopes: Select the following minimum required scopes: read_api — grants read-only access to the GitLab API (required to list projects and namespaces) read_repository — grants read-only access to repository contents (required to scan file trees)

Do not select write scopes (write_repository, api, etc.).

3.3 Create the Token

Click Create personal access token
The generated token value will be displayed once only — copy it immediately and store it in a secure vault or password manager

The token will appear in the format:

glpat-xxxxxxxxxxxxxxxxxxxx

3.4 CLI Alternative — Create Token via GitLab API

If scripted provisioning is required, an existing token with api scope can create a new PAT:

curl --request POST \
  --header "PRIVATE-TOKEN: <existing_admin_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "cbom-source-discovery",
    "scopes": ["read_api", "read_repository"],
    "expires_at": "2027-01-01"
  }' \
  "https://gitlab.com/api/v4/users/<user_id>/personal_access_tokens"

Replace <existing_admin_token> with a token that has api scope and <user_id> with the numeric GitLab user ID.

4. Create a Project Access Token (Single-Project Scoping)

If you want to restrict the sensor to a single project rather than all projects visible to a user, use a Project Access Token.

4.1 Open Project Settings

Navigate to the target project in GitLab
In the left sidebar, select Settings → Access Tokens

4.2 Configure Project Token Details

Fill in the following fields:

Token name: cbom-source-discovery
Expiration date: Set an appropriate expiry
Role: Select Reporter (minimum required role)
Scopes: Select: read_api read_repository

4.3 Create the Project Token

Click Create project access token
Copy the generated token value immediately — it is shown only once

5. Self-Managed GitLab — URL Configuration

For self-managed GitLab instances, you must provide the correct API base URL and handle any custom TLS certificates.

5.1 Confirm API Base URL

The GitLab API base URL follows this pattern:

https://<your-gitlab-hostname>/api/v4

Verify the API is reachable:

curl -s --header "PRIVATE-TOKEN: <your_token>" \
  "https://<your-gitlab-hostname>/api/v4/version"

A successful response returns JSON with version and revision fields.

5.2 TLS CA Certificate Handling

If your self-managed instance uses a private or internal certificate authority:

Obtain the CA certificate in PEM format from your PKI team
Save it to a path accessible by the CBOM Collector service, for example:
```
/etc/cbom/certs/gitlab-ca.pem
```
Reference the CA certificate path in the sensor configuration (see Section 6)

6. Configure the CBOM Sensor YAML

Use the token and instance URL in the CBOM source code discovery sensor configuration. Three common variants are shown below.

6.1 GitLab SaaS — Personal Access Token

sensor: Discover_SourceCode
platform: gitlab
gitlab_url: "https://gitlab.com"
private_token: "glpat-xxxxxxxxxxxxxxxxxxxx"
scan_groups:
  - "my-org-group"
scan_name: GitLabSourceCodeDiscovery

6.2 Self-Managed GitLab — Personal Access Token

sensor: Discover_SourceCode
platform: gitlab
gitlab_url: "https://gitlab.internal.example.com"
private_token: "glpat-xxxxxxxxxxxxxxxxxxxx"
ssl_ca_cert: "/etc/cbom/certs/gitlab-ca.pem"
scan_groups:
  - "engineering"
  - "security"
scan_name: GitLabSelfManagedDiscovery

6.3 Single Project — Project Access Token

sensor: Discover_SourceCode
platform: gitlab
gitlab_url: "https://gitlab.com"
private_token: "glpat-xxxxxxxxxxxxxxxxxxxx"
scan_projects:
  - "my-org-group/my-repository"
scan_name: GitLabProjectDiscovery

7. Validation

After configuring the sensor:

7.1 Check Task Logs

Run the source code discovery task from the CBOM interface
Open the task log and confirm: Task status shows completed or running without authentication errors Repository file trees are being enumerated * No 401 Unauthorized or 403 Forbidden errors appear

7.2 Verify Token Last-Used Timestamp in GitLab UI

In GitLab, go to your avatar → Edit profile → Access Tokens
Locate the cbom-source-discovery token
Confirm the Last Used column shows a recent timestamp matching the discovery run

7.3 Direct API Verification via curl

Verify token access to the API:

curl -s --header "PRIVATE-TOKEN: glpat-xxxxxxxxxxxxxxxxxxxx" \
  "https://gitlab.com/api/v4/projects?membership=true&per_page=5"

Verify repository read access for a specific project:

curl -s --header "PRIVATE-TOKEN: glpat-xxxxxxxxxxxxxxxxxxxx" \
  "https://gitlab.com/api/v4/projects/<project_id>/repository/tree"

A successful response returns a JSON array of files and directories. A 401 or 403 response indicates a token or permission issue.

8. Common Errors and Resolution

Error: 401 Unauthorized

HTTP 401: {"message": "401 Unauthorized"}

Cause:

The token value is incorrect or has been revoked
The token has expired

Resolution:

Verify the token value in the sensor YAML matches the generated token exactly
Check the token's expiry date in GitLab → Settings → Access Tokens
Regenerate the token if necessary and update the sensor configuration

Error: 403 Forbidden

HTTP 403: {"message": "403 Forbidden"}

Cause:

The token has the correct value but lacks required scopes (read_api or read_repository)
For Project Access Tokens: the assigned role is below Reporter
The target group or project has additional access restrictions

Resolution:

Delete the existing token and create a new one with both read_api and read_repository scopes
For Project Access Tokens, ensure the Reporter role (or higher) is selected
Confirm the GitLab user or service account has at least Reporter access to the target namespace

Error: SSL Certificate Verify Failed

SSLError: certificate verify failed: unable to get local issuer certificate

Cause:

The self-managed GitLab instance uses a certificate signed by a private or internal CA
The CA certificate is not trusted by the CBOM Collector service

Resolution:

Obtain the CA certificate PEM file from your PKI or GitLab administrator
Set the ssl_ca_cert field in the sensor YAML to the absolute path of the CA PEM file
Ensure the Collector service process has read access to the CA certificate file

9. Security Recommendations

For production environments:

Use a dedicated service account: Create a dedicated GitLab user (e.g., cbom-scanner) rather than using a personal developer account; this isolates token revocation and audit trail
Restrict token scopes: Grant only read_api and read_repository — do not grant api (full access) or any write scopes
Rotate tokens periodically: Set a token expiry date and establish a rotation process; update the sensor YAML when tokens are rotated
Use IP allowlists: On self-managed GitLab instances, configure token IP restrictions (GitLab EE feature) to limit token use to the CBOM Collector's IP address
Review GitLab audit logs: Periodically review GitLab's audit event log (Admin → Monitoring → Audit Events) to confirm the service account activity matches expected discovery schedules

10. Conclusion

Following this guide ensures that the CBOM Source Code Discovery Sensor operates with:

Least-privilege access using only read_api and read_repository scopes
Read-only repository access with no ability to modify code or settings
Full compatibility with both GitLab SaaS and self-managed GitLab instances
Proper TLS trust configuration for internal certificate authorities

CBOM Secure

GitLab Setup Guide for CBOM Source Code Discovery Sensor

1. Purpose

2. Prerequisites

3. Create a Personal Access Token

3.1 Open User Settings

3.2 Configure Token Details

3.3 Create the Token

3.4 CLI Alternative — Create Token via GitLab API

4. Create a Project Access Token (Single-Project Scoping)

4.1 Open Project Settings

4.2 Configure Project Token Details

4.3 Create the Project Token

5. Self-Managed GitLab — URL Configuration

5.1 Confirm API Base URL

5.2 TLS CA Certificate Handling

6. Configure the CBOM Sensor YAML

6.1 GitLab SaaS — Personal Access Token

6.2 Self-Managed GitLab — Personal Access Token

6.3 Single Project — Project Access Token

7. Validation

7.1 Check Task Logs

7.2 Verify Token Last-Used Timestamp in GitLab UI

7.3 Direct API Verification via curl

8. Common Errors and Resolution

Error: 401 Unauthorized

Error: 403 Forbidden

Error: SSL Certificate Verify Failed

9. Security Recommendations

10. Conclusion

On this Page: