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​

Once you've created your GitHub App, you can now generate a private key for authentication. 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.createdAtfirstFound
alert.dismissedAtLocal variable
alert.dismissedByLocal variable
alert.dismissedReasonLocal variable
alert.fixedAtlastFixed
alert.htmlUrlLocal variable
alert.mostRecentInstance.analysisKeyLocal variable
alert.mostRecentInstance.commitShaLocal variable
alert.mostRecentInstance.environmenttags
alert.mostRecentInstance.locationpath
alert.mostRecentInstance.messageresults
alert.mostRecentInstance.refLocal variable
alert.mostRecentInstance.statestatus, sourceStatus, statusCategory
alert.numberLocal variable
alert.repoIdtargets
alert.repoNameLocal variable
alert.rule.idtype, uid
alert.updatedAtlastFound, sourceLastModified
alert.urlurl
alertInfo.getAlertUiduid
installation.account.idLocal variable
installation.account.loginLocal variable
alert.tool.guidLocal variable
alert.tool.nameLocal variable
alert.tool.versionLocal variable
Code Scanning Alert Definition

Table 3: Code Scanning Alert Definition attribute mappings

Source Field NameMaps to Attribute
alert.rule.description/alert.rule.namename
alert.rule.fullDescriptiondescription
alert.rule.helprecommendation
alert.rule.securitySeverityLevelseverity, severityScore, sourceSeverity
alert.rule.severityLocal variable
alert.rule.idtype, uid
rule.tagscweIds, weaknesses, tags
Dependabot Alert

Table 4: Dependabot Alert attribute mappings

Source Field NameMaps to Attribute
ai.getAlertUiduid
alert.createdAtfirstFound
alert.dependency.manifestPathpath
alert.dependency.scopeLocal variable
alert.dismissedAtLocal variable
alert.dismissedByLocal variable
alert.dismissedReasonLocal variable
alert.htmlUrlLocal variable
alert.numberLocal variable
alert.repoIdtargets
alert.repoNameLocal variable
alert.statestatus, sourceStatus, statusCategory
alert.updatedAtlastFound
alert.urlurl
alert.vulnerabilityrecommendation, results
alert.vulnerability._packageLocal variable
alert.vulnerability.firstPatchedVersionLocal variable
alert.vulnerability.vulnerableVersionRangeLocal variable
installation.account.idLocal variable
installation.account.loginLocal variable
Dependabot Alert Definition

Table 5: Dependabot Alert Definition attribute mappings

Source Field NameMaps to Attribute
advisory.cvssUse CVSS calculator
advisory.cveIdcveIds, cveRecords
advisory.cwescweIds, weaknesses
advisory.descriptiondescription
advisory.ghsaIdLocal variable
advisory.publishedAtpublishedDate
advisory.references.urlreferences
advisory.severityseverity, severityScore, sourceSeverity
advisory.summaryname
advisory.withdrawnAtLocal variable
alert.advisory.ghsaIdtype, Local variable / uid
info

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.

Repository

Table 6: Repository attribute mappings

Source Field NameMaps to Attribute
categoriescategories
installation.account.idLocal variable
installation.account.loginLocal variable
repo._privateLocal variable
repo.archivedLocal variable
repo.createdAtfirstSeen, sourceCreatedDate
repo.defaultBranchLocal variable
repo.descriptiondescription
repo.disabledLocal variable
repo.forkLocal variable
repo.forkCountLocal variable
repo.hasDiscussionsLocal variable
repo.hasDownloadsLocal variable
repo.hasIssuesLocal variable
repo.hasPagesLocal variable
repo.hasProjectsLocal variable
repo.hasWikiLocal variable
repo.homepageLocal variable
repo.htmlUrlLocal variable
repo.isTemplateLocal variable
repo.languagelanguages
repo.licenseLocal variable
repo.namename
repo.nodeIduid
repo.openIssuesCountLocal variable
repo.ownerowner
repo.pushedAtlastSeen, sourceLastModified, Local variable
repo.securityAnalysis.advancedSecurityLocal variable
repo.securityAnalysis.dependabotSecurityUpdatesLocal variable
repo.securityAnalysis.secretScanningLocal variable
repo.securityAnalysis.secretScanningNonProviderPatternsLocal variable
repo.securityAnalysis.secretScanningPushProtectionLocal variable
repo.securityAnalysis.secretScanningValidityChecksLocal variable
repo.sizeLocal variable
repo.stargazersCountLocal variable
repo.topicsLocal variable
repo.updatedAtlastSeen, sourceLastModified
repo.urlurl
repo.visibilityLocal variable
repo.watchersCountLocal variable
repo.webCommitSignoffRequiredLocal variable
Secret Scanning Alert

Table 7: Secret Scanning Alert attribute mappings

Source Field NameMaps to Attribute
alert.createdAtfirstFound, sourceCreatedDate
alert.htmlUrlLocal variable
alert.locationsUrlLocal variable
alert.numberLocal variable
alert.pushProtectionBypassedLocal variable
alert.pushProtectionBypassedAtLocal variable
alert.pushProtectionBypassedBy.loginLocal variable
alert.repoIdtargets
alert.repoId, alert.repoNameLocal variable
alert.repoNameLocal variable
alert.resolutionLocal variable
alert.resolutionCommentLocal variable
alert.resolvedAtlastFixed
alert.resolvedBy.loginLocal variable
alert.secretresults, Local variable
alert.secretTyperesults, Local variable
alert.secretTypeDisplayNameresults, Local variable
alert.statestatus, sourceStatus, statusCategory
alert.updatedAtlastFound, sourceLastModified
alert.urlurl
alert.validityLocal variable
installation.account.idLocal variable
installation.account.loginLocal variable
uiduid
Secret Scanning Alert Definition

Table 8: Secret Scanning Alert Definition attribute mappings

Source Field NameMaps to Attribute
descriptiondescription
namename
recommendationrecommendation
typetype, uid, cweIds, weaknesses
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.

APIs​

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

Table 9: GitHub REST API Endpoints

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

Changelog​

The GitHub connector has undergone the following changes:

4.0.5

  • Added the following attributes to the Dependabot Alert object:

    • DISMISS_REASON
    • DISMISSED_AT
    • DISMISSED_BY

4.0.4

  • Added the SCOPE attribute to the Dependabot Alert object to help indicate whether a dependency is used at runtime or during development.

4.0.3

  • Added the HTML_URL attribute to the Repository object to display the GitHub web link. This provides a clearer reference to the repository location.

4.0.2

  • Changed the ADVANCED_SECURITY and DEPENDABOT_SECURITY_UPDATES attribute types on the Code Repository object from string to boolean.

4.0.1

  • Added the HTML_URL attribute to the Dependabot Alert object.

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

Last updated on