Skip to main content

GitHub

GitHub is a version control and collaboration platform that allows developers to host their own source code. It provides features such as issue tracking, code review, and integration with various tools and services. You can bring code, dependabot, repository, and scan data from GitHub into Brinqa to enhance your organization's security and risk management capabilities.

This document details the information you must provide for the connector to authenticate with GitHub and how to obtain that information from GitHub. See create a data integration for step-by-step instructions on setting up the integration.

Required connection settings

When setting up a data integration, select GitHub from the Connector drop-down. If you cannot find the connector in the drop-down, make sure that you have installed it first. You must provide the following information to authenticate GitHub with Brinqa:

  • API URL: The GitHub API URL. The default URL is https://api.github.com.

  • App ID: The GitHub App identifier. The app ID is associated with the GitHub App used to access the GitHub API. The app ID is a six-number string such as 123456.

  • Private key: The private key associated with the GitHub App, which must have permissions to log in to the API server and return data.

Create a GitHub App

You must register a new GitHub App for the connector to authenticate and access the GitHub API. To create a new GitHub App, follow these steps:

  1. Sign in to your GitHub account.

  2. Click the profile photo in the upper-right corner of the page, and then click Settings.

    • If you want to limit the GitHub connector's access to a specific organization rather than a personal account, click Your organizations in the drop-down instead of Settings. Then, to the right of the organization, click Settings. Follow the same steps outlined below for further configuration.
  3. In the navigation menu, select Developer settings.

  4. Click GitHub Apps, then New GitHub App, and complete the following fields. The fields not mentioned can be left as is.

    • GitHub App name: The name of your GitHub App.

    • Homepage URL: The full URL to your app's website. For example, https://www.example.com/github-app. www.example.com represents the domain of your company or developer who created the GitHub App, and /github-app is a specific page within your website dedicated to providing information about the app.

      • If you lack a specific URL and your application's source code is located in a public repository, you may use the repository URL. Alternatively, you can use the URL belonging to the organization or individual who owns the application. For example, https://github.com/yourusername/your-github-app. yourusername represents the GitHub username of the person or organization who created the app, and your-github-app is the name of the repository containing the app's source code and documentation.
    • Permissions: Add the following permissions required by the connector:

      • Repository:

        • Code scanning alerts: Read-only
        • Contents: Read-only
        • Dependabot alerts: Read-only
        • Issues: Read-only
        • Metadata: Read-only
        • Secret scanning alerts: Read-only
      • Organization: None.

      • Account: None.

  5. Click Create GitHub App.

If the registration is successful, the page reloads and displays information about your new GitHub App. You can find the App ID under the "About" section at the top of the page.

GitHub App ID

This six-digit string, along with the private key, is required to authenticate the GitHub connector with Brinqa.

note

If you do not have permissions to create a GitHub App, contact your GitHub administrator. For additional information, see GitHub documentation.

Generate a GitHub private key

To obtain the private key, follow these steps:

  1. While on the same page as your GitHub app information, scroll down to the Private keys section and click Generate a private key.

    GitHub generates a new private key and downloads it to your local storage as a .pem file. Copy the private key and save the .pem file in a secure location.

  2. In the navigation menu, click Install App.

  3. Click Install next to the account where you want to install the GitHub App on. You are presented with two options:

    • All repositories: The GitHub App has access to all existing and any future repositories that are owned by the account. This includes public repositories, but the app can only read their contents, not make changes.

    • Only select repositories: Click the "Select repositories" drop-down and select the repositories you want to install the GitHub App to. This also includes read-only public repositories.

  4. Review the permissions and click Install.

note

If you do not have permissions to generate a private key or install a GitHub App, contact your GitHub administrator. For additional information, see GitHub documentation about Managing private keys, and Installing your own GitHub App.

Additional settings

The GitHub connector contains an additional option for specific configuration:

  • Code Repository custom properties: A comma-separated list of custom property names used by the Code Repository object on Github. These names are case-insensitive and will be created as attributes in the source data model.

  • Page size: The maximum number of records to get per API request. The default setting is 100. It is not recommended to go over 100.

Types of data to retrieve

The GitHub connector can retrieve the following types of data from the GitHub API:

Table 1: Data retrieved from GitHub

Connector ObjectRequiredMaps to Data Model
Code Scanning AlertYesStatic Code Finding
Code Scanning Alert DefinitionYesStatic Code Finding Definition
Dependabot AlertYesOpen Source Finding
Dependabot Alert DefinitionYesOpen Source Finding Definition
RepositoryYesCode Repository
Secret Scanning AlertYesStatic Code Finding
Secret Scanning Alert DefinitionYesStatic Code Finding Definition
info

The GitHub connector does not currently support operation options for the types of data it retrieves.

For detailed steps on how to view the data retrieved from GitHub in the Brinqa Platform, see How to view your data.

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes.

Code Scanning Alert

Table 2: Code Scanning Alert attribute mappings

Source Field NameMaps to Attribute
ALERT_NUMBERLocal variable
ANALYSIS_KEYLocal variable
CLASSIFICATIONScategories
COMMIT_SHALocal variable
CREATED_ATfirstFound
DISMISS_REASONLocal variable
DISMISSED_ATLocal variable
DISMISSED_BYLocal variable
END_COLUMNpath
END_LINEpath
ENVtags (Environment:ENV)
HTML_URLLocal variable
INSTANCE_REFLocal variable
MESSAGELocal variable
ORG_IDLocal variable
ORG_NAMELocal variable
PATHpath
REPO_IDLocal variable
REPO_NAMEtargets
RULE_IDuid
START_COLUMNpath
START_LINEpath
STATEstatus(normalized), statusCategory
SYS_IDuid
TOOL_GUIDLocal variable
TOOL_NAMELocal variable
TOOL_VERSIONLocal variable
UIDuid
UPDATED_ATlastFound, sourceLastModified
URLurl
Code Scanning Alert Definition

Table 3: Code Scanning Alert Definition attribute mappings

Source Field NameMaps to Attribute
CLASSIFICATIONScategories
RULE_DESCRIPTIONdescription
RULE_IDtype
RULE_NAMEname
RULE_SECURITY_SEVERITYLocal variable
RULE_SEVERITYseverity(normalized), sourceSeverity, severityScore
RULE_TAGStags
Dependabot Alert

Table 4: Dependabot Alert attribute mappings

Source Field NameMaps to Attribute
CREATED ATfirstFound
GHSA IDLocal variable
MANIFEST FILEresults
MANIFEST PATHresults
NUMBERLocal variable
ORGANIZATION IDLocal variable
ORGANIZATION NAMELocal variable
PACKAGEtargets
PATCHED VERSIONLocal variable
REPOSITORY IDtargets
REPOSITORY NAMELocal variable
SCOPELocal variable
SECURITY ADVISORY IDtype
SEVERITYseverity(normalized), sourceSeverity, severityScore
STATEstatus(normalized), statusCategory
SYS IDuid
UPDATED ATlastFound
URLLocal variable
VERSION REQUIREMENTSLocal variable
VULNERABLE VERSIONSLocal variable
VULNERABLE_MANIFEST_FILEpath
VULNERABLE_MANIFEST_PATHpath
Dependabot Alert Definition

Table 5: Dependabot Alert Definition attribute mappings

Source Field NameMaps to Attribute
CVEcveIds, cveRecord
CVSS SCOREuseCvssCalculator, referQualys
CVSS VECTORuseCvssCalculator, referQualys
CWEcweIds, weaknesses
DESCRIPTIONdescription
GHSA IDLocal variable
NOTIFICATIONS PERMALINKreferences
PERMALINKreferences
PUBLISHED ATpublishDate
REFERENCESreferences
SEVERITYseverity(normalized), sourceSeverity, severityScore
SUMMARYname
SYS IDuid
Repository

Table 6: Repository attribute mappings

Source Field NameMaps to Attribute
AUTO_MERGE_ALLOWEDLocal variable
Created atfirstSeen
DESCRIPTIONdescription
HOME_PAGE_URLLocal variable
Is archivedLocal variable
Is disabledLocal variable
Is emptyLocal variable
Is forkLocal variable
Is in organizationLocal variable
Is lockedLocal variable
Is mirrorLocal variable
Is privateLocal variable
Is security policy enabledLocal variable
Is templateLocal variable
Issues enabledLocal variable
LanguagesLocal variable
Last pushedLocal variable
LATEST_RELEASELocal variable
LOCK_REASONLocal variable
Merge commit allowedLocal variable
Namename
Organization IDLocal variable
Organization nameLocal variable
Ownerowners
ParentLocal variable
Projects enabledLocal variable
Rebase merge allowedLocal variable
SSH urlLocal variable
STARGAZER_COUNTLocal variable
Squash merge allowedLocal variable
Sys IDuid
TopicsLocal variable
Updated atlastSeen
UrlLocal variable
Secret Scanning Alert

Table 7: Secret Scanning Alert attribute mappings

Source Field NameMaps to Attribute
Alert numberLocal variable
Created atfirstFound
Html urlLocal variable
Locations urlLocal variable
Organization IDLocal variable
Organization nameLocal variable
PUSH_PROTECTION_BYPASSED_ATLocal variable
PUSH_PROTECTION_BYPASSED_BYLocal variable
Push protection bypassedLocal variable
RESOLVED_ATlastFixed
RESOLVED_BYLocal variable
RESOLUTIONLocal variable
Repository IDtargets
Secretresults(redacted)
Secret nameresults
Secret typeresults
Sys IDuid
Updated atLast found
UrlLocal variable
note

Local variable indicates that the field is processed within a specific context, such as a particular workflow or calculation. Unlike other attributes, local variables aren't mapped to the unified data models. They only exist on the source data model.

Use CVSS calculator indicates that the CVSS (Common Vulnerability Scoring System) vectors and scores aren't directly mapped to a specific attribute on the UDM. Instead, a specialized library calculates the CVSS scores from the provided CVSS vector strings.

APIs

The GitHub connector uses the GitHub REST API. Specifically, it uses the following endpoints:

Table 7: GitHub REST API Endpoints

Connector ObjectAPI Endpoints
Code Scanning AlertGET /orgs/{org}/code-scanning/alerts
Code Scanning Alert DefinitionGET /orgs/{org}/code-scanning/alerts
Dependabot AlertGET /enterprises/{enterprise}/dependabot/alerts
Dependabot Alert DefinitionGET /enterprises/{enterprise}/dependabot/alerts
RepositoryGET /orgs/{org}/repos
Secret Scanning AlertGET /enterprises/{enterprise}/secret-scanning/alerts
Secret Scanning Alert DefinitionGET /enterprises/{enterprise}/secret-scanning/alerts

Changelog

The GitHub connector has undergone the following changes:

4.0.0

  • Transitioned the GitHub connector to fully use the GitHub REST API to enhance performance and reliability.

  • Renamed the following objects to better align with GitHub terminology:

    • Code Repository -> Repository
    • Open Source Finding -> Dependabot Alert
    • Open Source Finding Definition - Dependabot Alert Definition
    • Static Code Finding -> Code Scanning Alert
    • Static Code Finding -> Code Scanning Alert Definition
  • Removed the Package object as it was deemed unnecessary for the connector's functionality.

  • Updated the Repository object with new attributes while removing some that are no longer available or relevant in the GitHub REST API.

  • Enhanced the details and recommendations provided by Code Scanning Alerts to offer more comprehensive information.

3.0.14

  • Fixed an issue where the Code Repository sync was returning a 406 error.

3.0.13

  • Changed the PUSH_PROTECTION_BYPASSED attribute type on the Secret Scanning Alert object from string to boolean.

3.0.12

  • Added a rate limiter to allow for a max of 30 API calls per second.

  • Added the following attributes to the Secret Scanning Alert object:

    • SECRET
    • SECRET_NAME
    • SECRET_TYPE
  • Added the following attributes to the Code Repository object:

    • SOURCE_CREATED_DATE
    • SOURCE_LAST_MODIFIED
  • Now uses pushedAt and updatedAt to compute LAST_SEEN for the Code Repository object.

  • Added the following attributes to the Open Source Finding object:

    • PACKAGE_NAME
    • RECOMMENDATION

3.0.11

  • Fixed an issue where the RESULTS attribute on Open Source Finding object was returning as a multi-value attribute.

3.0.10

3.0.9

  • Made the Package object optional.

3.0.8

  • Fixed an issue where Code Repository records weren't getting synced.

3.0.7

  • Updated dependencies.

3.0.6

  • Fixed a data integration failure when attempting to sync Secret Scanning Alert, Static Code Finding, or Static Code Finding Definition objects.

3.0.5

  • Added a VALIDITY attribute to the Secret Scanning Alert object.

3.0.4

  • Changed the 'AUTO_DISMISSED' status to 'Fixed' in the Open Source Finding and Static Code Finding objects.

3.0.3

  • Enhanced to retrieve all statuses of the Open Source Finding object.

3.0.2

  • Fixed an issue on the CATEGORIES attribute that caused data integration to fail.

3.0.1

  • Removed the use of ImmutableSet.

3.0.0