Git Sensor User Guide

The Git Sensor integrates any Git-based version control system (GitHub, GitLab, Bitbucket, Azure DevOps, etc.) with Keyfactor AgileSec Platform. It allows you to discover, inventory, and analyze cryptographic assets across your source code repositories.

Overview

Key Features

• Universal Git Support: Works with any standard Git repository (cloud or on-premise).

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

• Archive Scanning: Extracts and scans archives (ZIP, TAR, etc.) found within the repository.

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

• Flexible Authentication: Supports username/password and token based authentication.

What Gets Scanned

The sensor clones the target repository (or specific branch) 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)

Refer to Sensors Architecture and Overview for additional details on how sensors work and their data flow.

Prerequisites

Git Provider Requirements

Supported Authentication Methods

The Git sensor supports the following authentication methods:

• Username/Password Authentication: Authenticate using Git provider credentials with a username and password combination. Suitable for basic authentication scenarios and legacy systems.

• Token-based Authentication: Authenticate using personal access tokens (PAT), OAuth tokens, or API tokens provided by the Git provider. Recommended for enhanced security, fine-grained access control, and automated workflows.

Note: If password is provided but username is omitted, the sensor defaults to using "oauth2" as the username.

It is recommended to test your credentials before setting up the sensor:

  git clone https://<username>:<password>@github.com/org/repo.git

or

  git clone https://oauth2:<token>@github.com/org/repo.git

Required Access Rights

The Git account must have the following permissions to successfully authenticate to a private repository:

Running the Sensor

The sensor can be executed using following methods:

1. Run from the Platform UI

2. Using via the API

3. Run Remotely (Unified Sensor CLI)

Refer to Sensors Architecture and Overview for additional details on how to run sensors. The following sections focus on sensor-specific configuration details.

Run from the Platform UI

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

Refer to Scan API doc for additional details on how use the API.

Request Body for Git Sensor

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

  {
    "sensorName": "<sensor name>",
    "sensorType": "GIT Sensor",
    "sensorConfig": {
        "giturl": "<git repository url>",
        "branch": "<branch>",
        "username": "<optional username>",
        "password": "<password or token>"
    },
    "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 remote sensor config for running GitHub sensor through unified sensor CLI

• Scan All Repos in an Org (Public)

  CODE

  scan_config:
    plugins:
      - isg_git
      - trigger_discover
      - export
    config:
      isg_git:
        plugin_config:
          url: "https://github.com/myorg/public-repo.git"
          branch: "main"
  

• Private Repository (With Auth)

  CODE

  scan_config:
    plugins:
      - isg_git
      - trigger_discover
      - export
    config:
      isg_git:
        plugin_config:
          url: "https://github.com/myorg/public-repo.git"
          branch: "main"
          username: "myuser"
          password: "${env:GIT_PASS}"
  

• Gitlab Example

  CODE

  scan_config:
    plugins:
      - isg_git
      - trigger_discover
      - export
    config:
      isg_git:
        plugin_config:
          url: "https://gitlab.com/myorg/myrepo.git"
          branch: "develop"
          username: "myuser"
          password: "${env:GIT_PASS}"
  

An example configuration can be found in config/sample-configs/git.yml

Known Limitations

Binary Scan Limitations

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

Troubleshooting

Common Errors

• repository not found (404)

  • Cause: The URL is incorrect, OR the credentials provided do not have access to the private repository.

  • Fix: Check the URL.

• authentication failed (401)

  • Cause: Invalid credentials.

  • Fix: Verify the credentials are correct by testing with a manual git clone command.

• unable to access (402/Connection Refused)

  • Cause: Network connectivity issue.

  • Fix: Ensure the machine running the sensor can reach the Git 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).

Getting Support

Collect diagnostic information:

• Sensor version

• Configuration file (redact tokens)

• Log output

• Git provider details (type, URL, version)

Contact Support:

• Email: support@keyfactor.com

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