GitLab Sensor User Guide

The GitLab Sensor integrates GitLab (cloud or self-hosted) with Keyfactor's AgileSec Platform. It allows you to discover, inventory, and analyze cryptographic assets across multiple repositories within a GitLab organization or group.

Overview

Key Features

• Organization-Wide Scanning: Scan all repositories in a GitLab group or organization in a single execution.

• Flexible Filtering: Use glob patterns (including ** globbing) to include or exclude specific repositories.

• Deep Cryptographic Discovery: Automatically identifies certificates, private keys, keystores, and cryptographic libraries embedded in source code.

• Incremental Scanning: Efficiently scans only new or modified files in subsequent runs.

• Cloud and Self-Hosted Support: Works with GitLab.com and self-hosted GitLab instances.

What Gets Scanned

The sensor downloads repository archives from GitLab and analyzes all files to discover:

• X.509 Certificates: SSL/TLS certificates, code signing certificates, client authentication certificates

• Private Keys: RSA, DSA, EC private keys in PEM, DER, and PKCS8 formats

• Java Keystores: JKS, JCEKS, PKCS12 keystores

• Tokens: JWT and JWE tokens

• Cryptographic Libraries: OpenSSL, BouncyCastle, cryptography.io, and other crypto implementations

• Container Images: Certificates and keys embedded in Docker/OCI images

• Code Artifacts: Embedded certificates in compiled code (JAR, WAR, EAR files)

• Source Code: Use of cryptographic algorithms and libraries in source code

Prerequisites

GitLab Requirements

Supported Authentication Methods

The Gitlab sensor supports token-based authentication

• Step 1: Generate a Personal Access Token

  1. Log in to GitLab

  2. Go to User Settings → Access Tokens (or navigate to https://gitlab.com/-/user_settings/personal_access_tokens)

  3. Create a new token with the following scopes: - read_api — Required for listing repositories - read_repository — Required for downloading repository archives

  4. Copy the token immediately — it will only be shown once

  5. Store the token securely

• Step 2: Verify Token

  Test the token to ensure it works:

  CODE

  # set your token
  export GITLAB_TOKEN="your-token-here"
  export GITLAB_URL="https://gitlab.com"  # or your self-hosted URL
  
  # test authentication
  curl -H "PRIVATE-TOKEN: ${GITLAB_TOKEN}" \
  "${GITLAB_URL}/api/v4/projects?per_page=1"
  
  # expected: json array with project info

Required Access Rights

The GitLab access token must have the following permissions to successfully authenticate:

Running the Sensor

The sensor can be executed from the Platform UI, through the Scan API, or remotely using the Unified Sensor CLI.

Run from the Platform UI

Refer to Sensors Architecture and Overview for additional details on how to configure sensor through UI.

Platform Scan Configuration

Step 1: Navigate to the Sensor Setup page: Scan → Sensors → Choose a Sensor → Git Sensor

Step 2: Configure the sensor parameters.

Fill in the required configuration parameters:

Platform Scan Configuration Fields

Scan Execution Using API

For complete field definitions, supported parameters, and error handling details, see Scan API.

Request Body

The complete request body contains sensor configuration in the sensorConfig field, i.e:

{
  "sensorName": "<sensor name>",
  "sensorType": "Gitlab Sensor",
  "sensorConfig": {
     "url": "<gitlab api url>",
     "branch": "<branch name>",
     "token": "<personal access token>",
     "include_paths": "<include patterns>",
     "exclude_paths": "<exclude patterns>"
  },
  "callbackId": "<callback id>",
  "labels": [
      {
          "<label name>": "<label value>"
      }
  ],
  "priority": "<priority>",
  "incrementalScan": true,
  "autoResolutionInterval": 5
}

API Field Descriptions

For API fields and descriptions, see Scan API.

Run Remotely (Unified Sensor CLI)

Use following config for running sensor through the unified sensor CLI:

• Scan All Repos in an Org (Public)

  CODE

  scan_config:
    plugins:
      - isg_gitlab
      - trigger_discover
      - export
    config:
      isg_gitlab:
        plugin_config:
          include_paths:
            - "myorg" # Equivalent to "myorg/**"
  

• Self-Hosted GitLab (With Auth)

  CODE

  scan_config:
    plugins:
      - isg_gitlab
      - trigger_discover
      - export
    config:
      isg_gitlab:
        plugin_config:
          url: "https://git.mycompany.com"
          token: "${env:GITLAB_TOKEN}"
          include_paths:
            - "internal-team/**"
          exclude_paths:
            - "internal-team/archived-*"
  

• Scan Specific Branch

  CODE

  scan_config:
    plugins:
      - isg_gitlab
      - trigger_discover
      - export
    config:
      isg_gitlab:
        plugin_config:
          url: "https://gitlab.com"
          token: "${env:GITLAB_TOKEN}"
          branch: "develop"
          include_paths:
            - "myorg/myrepo"
  

The remote sensor contains an example configuration file in the directory config/sample-configs/gitlab.yml.

Known Limitations

Rate Limiting

• Description: Gitlab enforces API rate limits.

• Impact: Large organizations with many repositories may hit rate limits.

• Workaround: For individual repositories you can use the Git Sensor.

Binary Files

• Description: While the sensor scans files, opaque binary blobs without recognized headers may not be deeply analyzed.

Troubleshooting

Common Errors

• 401 Unauthorized

  • Cause: Invalid or expired Personal Access Token.

  • Fix: Verify the token is correct and has not expired. Regenerate if necessary.

• 403 Forbidden

  • Cause: Token lacks required scopes (read_api, read_repository).

  • Fix: Generate a new token with the correct scopes.

• 404 Not Found

  • Cause: Repository or group does not exist, or token doesn't have access.

  • Fix: Verify the include patterns are correct and the token has access to the target repositories.

• unable to access (Connection Refused)

  • Cause: Network connectivity issue.

  • Fix: Ensure the machine running the sensor can reach the GitLab server URL. Check firewalls and proxies.

• could not find remote branch

  • Cause: The specified branch does not exist on the remote.

  • Fix: Verify the branch name matches exactly (case-sensitive), or leave blank to use the default branch.

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens)

• Log output

• GitLab details (cloud vs self-hosted, URL, version)