GitHub Sensor User Guide

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

Key Features

• Organization-Wide Scanning: Scan all repositories in a GitHub organization in a single execution.

• Flexible Filtering: Use glob patterns 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.

What Gets Scanned

The sensor downloads repository archives from GitHub 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)

For more information about how sensors work and their data flow, see Sensors Architecture and Overview.

Prerequisites

GitHub Requirements

Supported Authentication Methods

The GitHub sensor supports token-based authentication

• Step 1: Generate a Fine-Grained Personal Access TokenLog in to GitHub

  1. Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens (or navigate tohttps://github.com/settings/personal-access-tokens/new)

  2. Click Generate new token

  3. Configure the token: - Token name: A descriptive name (e.g., "AgileSec Scanner") - Expiration: Set an appropriate expiration - Repository access: Select All repositories (or specific repos if preferred) - Permissions: Under Repository permissions, set: - Contents → Read-only - Metadata → Read-only

• Click Generate token

• Copy the token immediately - it will only be shown once

• Store the token securely

• Step 2: Verify Token

  Test the token to ensure it works:

  CODE

  # set your token
  export GITHUB_TOKEN="your-token-here"
  export GITHUB_URL="https://api.github.com"  # or your enterprise URL
  
  git clone https://oauth2:<token>@github.com/org/repo.git
  

Required Access Rights

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

Running the Sensor

The sensor can be executed using following methods:

1. Run Sensor on the Platform

2. Scan via the API

3. Run Remotely (Unified Sensor CLI)

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

Run Sensor on the Platform

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

Step 2: Configure Sensor Parameters

Fill in the required configuration parameters. See table below for detailed description of each configuration parameter:

Sensor Configuration Fields

Scan via the API

The following demonstrates how to initiate a scan programmatically using the Scan API, with an example request payload for a GitHub sensor configuration.

The examples illustrate the structure of the request body and how sensor-specific configuration is provided through the sensorConfig field. For complete field definitions, supported parameters, and error handling details, see Scan API.

Request Body for GitHub Sensor

The complete request body contains sensor configuration in the sensorConfig field, for example:

{
  "sensorName": "<sensor name>",
  "sensorType": "Github Sensor",
  "sensorConfig": {
     "url": "<github 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
}

Example Request Payload:

{
  "sensorName": "EJBCA Repo",
  "sensorType": "Github Sensor",
  "sensorConfig": {
     "branch": "main",
     "include_paths": ["Keyfactor/ejbca-ce"]
  },
  "incrementalScan": false
}

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_github
      - trigger_discover
      - export
    config:
      isg_github:
        plugin_config:
          include_paths:
            - "myorg" # Equivalent to "myorg/**"
  

• GitHub Enterprise (With Auth)

  CODE

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

• Scan Specific Branch

  CODE

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

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

Known Limitations

Rate Limiting

• Description: GitHub enforces API rate limits.

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

• Workaround: Always use a Personal Access Token, usually that has higher limits. Also, 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

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

• GitHub details (cloud vs enterprise, URL, version)