GitHub Security

By enabling the GitHub Security connector, you can analyze GitHub security alerts and incorporate this data into scorecards. Please refer to the API documentation below and our schema explorer to see what data DX imports—note that DX does not read or access your source code.

Before proceeding, please make sure that you have first enabled the GitHub connector by following the steps here. Each GitHub credential in DX should utilize a separate GitHub App ID and API token to avoid rate limit issues.

Prerequisites

To connect GitHub to DX, you need:

• a GitHub user account that is an Organization owner or Enterprise owner
• allowlist DX IP addresses if your GitHub instance is behind a firewall or has IP restrictions

Setup instructions

Follow the steps below to connect GitHub to DX.

Step 1

• If you are using GitHub Enterprise Cloud, browse to the URL below with ENTERPRISE_NAME replaced:

  https://github.com/enterprises/ENTERPRISE_NAME/settings/apps/new?public=false&members=read&url=https://getdx.com&metadata=read&webhook_active=false

• If you are using GitHub Enterprise Server or GitHub Team Edition, browse to the URL below with ORGANIZATION_NAME replaced:

  https://github.com/organizations/ORGANIZATION_NAME/settings/apps/new?public=false&members=read&url=https://getdx.com&metadata=read&webhook_active=false

Step 2

This will pre-populate settings and permissions, but you’ll need to manually enter a name for your GitHub App. We recommend naming your app [COMPANYNAME] DX - GitHub Security to avoid naming collisions with other GitHub Apps.

Dependabot, code scanning, and secret scanning alert imports are always enabled for every GitHub Security connection. GitHub Code Quality is imported only when its conditional schema is enabled.

Below are the read-only GitHub App permissions required by DX:

Step 3

Scroll to the bottom of the page and click the “Create GitHub App” button.

Step 4

The GitHub App ID will be shown at the top of the subsequent screen. Copy this ID down so it can be entered into DX later.

Step 5

On the same screen, scroll down to the “Private keys” heading and click “Generate a private key” which will initiate a download of a PEM file. Copy the contents of this file to be entered into DX later.

Step 6

Click on the “Install App” link in the sidebar navigation and then click “Install” beside your GitHub organization.

• To get your initial data imported as quickly as possible, please select only your most important repositories initially, then come back and select more later.
• By default, public repositories are not imported. If you would like public repositories to be imported, please contact DX Support.

Step 7

• Navigate to the connections page in DX and select “+ Connection” in the top right.
• Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.

Enable GitHub Code Quality

GitHub Code Quality ingestion is available as the GitHub Code Quality conditional schema. It requires an active GitHub Security connection to GitHub Cloud and is not available for GitHub Enterprise Server.

Before applying the schema, grant the GitHub App the repository-level Code quality: Read-only permission and have an organization owner approve the permission change for the installation. Then navigate to Admin → Data Cloud → Conditional Schemas and apply GitHub Code Quality.

When the schema is applied, DX verifies that each active credential on the GitHub Security connection has at least one active organization installation with Code quality read access. After activation, DX imports findings from repositories where GitHub Code Quality is enabled; repositories where the feature is not enabled are skipped without interrupting the rest of the import.

API reference

The table below lists the specific API endpoints that are used by DX.

Errors

The table below lists potential error codes when adding a connection in DX.

Curl commands

When connection verification fails

When DX verifies a GitHub Security connection, it checks app installations to ensure proper access with the required permissions. If your connection is failing, you can test these endpoints directly using the curl commands below to troubleshoot the issue.

Step 1: Generate JWT Token

First, create a bash script to generate a JWT token for authentication. Replace YOUR_GITHUB_APP_ID with your GitHub App ID and PRIVATE_KEY_FILE with your actual private key content:

APP_ID="YOUR_GITHUB_APP_ID"
PRIVATE_KEY_FILE="PRIVATE_KEY_FILE"

b64url() { base64 | tr -d '\n=' | tr '+/' '-_'; }

HEADER=$(printf '{"alg":"RS256","typ":"JWT"}' | b64url)
NOW=$(date +%s); EXP=$((NOW + 300))
PAYLOAD=$(printf '{"iat":%s,"exp":%s,"iss":"%s"}' "$NOW" "$EXP" "$APP_ID" | b64url)

tmp=$(mktemp)
tr -d '\r' < "$PRIVATE_KEY_FILE" > "$tmp"
SIG=$(printf '%s' "$HEADER.$PAYLOAD" | openssl dgst -sha256 -sign "$tmp" -binary | b64url)
rm -f "$tmp"

echo "$HEADER.$PAYLOAD.$SIG"

Note: The PRIVATE_KEY_FILE should contain your complete private key including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.

Run this script to generate your JWT token, then use that token in the curl commands below.

Step 2: Test App Installations

Use the JWT token from Step 1 to verify that your GitHub App can access installations:

curl -H 'Authorization: Bearer YOUR_JWT_TOKEN' -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/app/installations'

Step 3: Check Installation Permissions

For each installation ID returned above, check its permissions (replace YOUR_INSTALLATION_ID with an actual installation ID):

curl -H 'Authorization: Bearer YOUR_JWT_TOKEN' -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/app/installations/YOUR_INSTALLATION_ID'

The response includes a permissions object. The permission value must be read or write. DX always requires:

• members
• metadata
• vulnerability_alerts for Dependabot alerts
• security_events for code scanning alerts
• secret_scanning_alerts for secret scanning alerts

DX also requires code_quality when the GitHub Code Quality conditional schema is enabled. GitHub Code Quality uses the conditional-schema validation described above.

Data Cloud API

Once the initial connection is created successfully, credentials can be managed via the Data Cloud API. This connector uses the same credential fields as GitHub (settings.github_app_id and secrets.private_key_pem).

• credentials.create
• credentials.update
• credentials.info
• credentials.list
• credentials.delete