GitLab Sensor User Guide

The GitLab Sensor User Guide provides instructions for deploying and operating the GitLab Sensor within the Keyfactor AgileSec Platform. This guide covers supported authentication methods, execution methods, configuration options, and troubleshooting.

Refer to Sensors Architecture and Overview for additional details on sensor architecture, data flows, incremental scanning, and auto-resolution.

Overview

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

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 http://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

• 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

Remote Execution Requirements

If running the unified sensor remotely using CLI:

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:

  # 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 GitLab Sensor supports these execution flows:

1. Platform Scan Execution: Configure and execute scans directly though the Keyfactor AgileSec web UI with on-demand or scheduled execution options.

2. Using API: Programmatically trigger scans through REST API calls, enabling integration with CI/CD pipelines and automation workflows.

3. Remote Scan Execution: Deploy and run the sensor via CLI on customer-managed infrastructure for scenarios such as:

   1. Scanning air-gapped or internal instances the platform cannot directly reach

   2. Customers wanting to manage their own scheduling and execution environment.

Refer to Sensors Architecture and Overview: Running the Sensor for additional execution and flow details.

Platform Scan Execution

Running the sensor through the user interface is the simplest and fastest way to get started. The platform enables running on-demand or scheduled scans in a dedicated environment.

Platform Scan Configuration

Step 1: Navigate to Sensors Setup Page

1.1 Open your browser and navigate to the Keyfactor AgileSec Platform Web URL

1.2 Log in with your credentials

1.3 Click on "Sensors" in the navigation bar.

Step 2: Select the GitLab Sensor

1. Click the "Choose a Sensor" button.

   

2. Browse or search for "Gitlab".

3. Click on the Gitlab sensor card.

This will open the sensor configuration interface.

Step 3: Configure Sensor Parameters

Fill in the required configuration parameters:

Platform Scan Configuration Fields

Scan Execution Using API

Scans may be programmatically triggered through REST API calls, enabling seamless integration with CI/CD pipelines, automation workflows, and custom applications. API execution provides flexibility for developers to incorporate cryptographic scanning into their existing development and deployment processes.

Note: For complete API reference, see the API document.

API Access Token

1. Open your browser and navigate to the AgileSec Platform UI.

2. Log in with your Keyfactor credentials.

3. Click "Access Tokens" in the main navigation menu.

4. Click "Generate Token".

5. Set Token Type to API Token and provide the required details.

6. Click "Generate" and copy the generated token.

API Endpoint

POST https://<platform-url>/v3/scan/create

Request Format

Headers

Content-Type: application/json
isg-api-token: <your-api-token>

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

See Platform Scan Configuration Fields.

Remote Scan Execution

Remote Execution Flow allows you to run the sensor on a host using the Unified Sensor binary.

Remote Scan Execution Configuration

Step 1: Download Unified Sensor

1.1 Navigate to AgileSec Platform UI → Sensors → Remote Scan.

1.2 Download the sensor binary for your operating system.

Step 2: Generate Remote Sensor Token

2.1 In the Remote Scan UI, click "Generate Token".

2.2 Copy the generated token.

2.3 Store the token securely in an environment variable or set it in the sensor config:

  export SENSOR_TOKEN="your-generated-token"

Step 3: Create Configuration File

Create a YAML configuration file (e.g., gitlab-config.yml) with your scan settings. An example configuration can be found in config/sample-configs/gitlab.yml.

Step 4: Run the Sensor

Execute the sensor with your configuration file:

• Linux/macOS

  BASH

  # Set environment variables
  export SENSOR_TOKEN="your-sensor-token"
  export GITLAB_TOKEN="your-gitlab-token"
  
  # Run sensor
  ./unified_sensor_linux -c gitlab-config.yml

• Windows (PowerShell)

  POWERSHELL

  # Set environment variables
  $env:SENSOR_TOKEN = "your-sensor-token"
  $env:GITLAB_TOKEN = "your-gitlab-token"
  
  # Run sensor
  .\\unified_sensor_windows.exe -c .\\gitlab-config.yml

Remote Scan Execution Configuration Examples

• Scan All Repos in an Org (Public)

  YAML

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

• Self-Hosted GitLab (With Auth)

  YAML

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

• Scan Specific Branch

  YAML

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

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 does not 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)

Contact Support:

• Portal: https://support.keyfactor.com