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 and code repository 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.

Generate GitHub authentication credentials

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

Sign in to your GitHub account.
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.
In the navigation menu, select Developer settings.
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
    - Packages: Read-only
    - Secret scanning alerts: Read-only
  - Organization: None.
  - Account: None.
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. This six-digit string, along with the private key, is required to authenticate the GitHub connector with Brinqa.

Scroll down to Private keys 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.

In the navigation menu, click Install App.
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.
Review the permissions and click Install.

note

For additional information, see GitHub documentation about Creating GitHub Apps, Install your own GitHub App, and Managing private keys.

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 Object	Required	Maps to Data Model
Code Repository	Yes	Code Repository
Open Source Finding	Yes	Open Source Finding
Open Source Finding Definition	Yes	Open Source Finding Definition
Package	No	Package
Secret Scanning Alert	Yes	Static Code Finding
Secret Scanning Alert Definition	Yes	Static Code Finding Definition
Static Code Finding	Yes	Static Code Finding
Static Code Finding Definition	Yes	Static 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

Click the tabs below to view the mappings between the source and the Brinqa data model attributes.

Repository
Package
Secret Scanning Alert
Security Advisory
Vulnerability Alert

Table 2: Repository attribute mappings

Source Field Name	Maps to Attribute
AUTO_MERGE_ALLOWED	Local variable
Created at	firstSeen
DESCRIPTION	description
HOME_PAGE_URL	Local variable
Is archived	Local variable
Is disabled	Local variable
Is empty	Local variable
Is fork	Local variable
Is in organization	Local variable
Is locked	Local variable
Is mirror	Local variable
Is private	Local variable
Is security policy enabled	Local variable
Is template	Local variable
Issues enabled	Local variable
Languages	Local variable
Last pushed	Local variable
LATEST_RELEASE	Local variable
LOCK_REASON	Local variable
Merge commit allowed	Local variable
Name	name
Organization ID	Local variable
Organization name	Local variable
Owner	owners
Parent	Local variable
Projects enabled	Local variable
Rebase merge allowed	Local variable
SSH url	Local variable
STARGAZER_COUNT	Local variable
Squash merge allowed	Local variable
Sys ID	uid
Topics	Local variable
Updated at	lastSeen
Url	Local variable

Table 3: Package attribute mappings

Source Field Name	Maps to Attribute
LATEST_VERSION	latestVersion
NAME	name
ORG_ID	Local variable
ORG_NAME	Local variable
PACKAGE_TYPE	tags, Local variable
REPO_ID	Local variable
REPO_NAME	Local variable
SYS_ID	uid

Table 4: Secret Scanning Alert attribute mappings

Source Field Name	Maps to Attribute
Alert number	Local variable
Created at	firstFound
Html url	Local variable
Locations url	Local variable
Organization ID	Local variable
Organization name	Local variable
PUSH_PROTECTION_BYPASSED_AT	Local variable
PUSH_PROTECTION_BYPASSED_BY	Local variable
Push protection bypassed	Local variable
RESOLVED_AT	lastFixed
RESOLVED_BY	Local variable
RESOLUTION	Local variable
Repository ID	targets
Secret	results(redacted)
Secret name	results
Secret type	results
Sys ID	uid
Updated at	Last found
Url	Local variable

Table 5: Security Advisory attribute mappings

Source Field Name	Maps to Attribute
CVE	cveIds, cveRecords
CVSS score	Use CVSS calculator (Qualys)
CVSS vector	Use CVSS calculator (Qualys)
CWE	cweIds, weaknesses
Description	description
GHSA ID	Local variable
Notifications permalink	references
Permalink	references
Published at	publishedDate
References	references
Severity	severity, severityScore
Summary	name
Sys ID	uid

Table 6: Vulnerability Alert attribute mappings

Source Field Name	Maps to Attribute
Created at	firstFound
GHSA ID	Local variable
Manifest file	results
Manifest path	results
Number	Local variable
Organization ID	Local variable
Organization name	Local variable
Package	targets
Patched version	Local variable
Repository ID	targets
Repository name	Local variable
Scope	Local variable
Security advisory ID	type
Severity	severity, severityScore
State	status, statusCategory
Sys ID	uid
Updated at	lastFound
URL	Local variable
Version requirements	Local variable
Vulnerable version	Local variable
VULNERABLE_MANIFEST_FILE	path
VULNERABLE_MANIFEST_PATH	path

info

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 both GitHub REST API endpoints and the GitHub GraphQL API, providing a flexible approach to retrieve your GitHub data.

GitHub REST API

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

Table 7: GitHub REST API Endpoints

Connector Object	API Endpoint
Static Code Finding	`GET https://api.github.com/repos/OWNER/REPO/code-scanning/alerts`
Static Code Finding Definition	`GET https://api.github.com/repos/OWNER/REPO/code-scanning/alerts`
Secret Scanning Alert	`GET https://api.github.com/repos/OWNER/REPO/secret-scanning/alerts`

GitHub GraphQL API

The GitHub connector also uses the GitHub GraphQL API. Specifically, it uses the https://api.github.com/graphql endpoint and the following queries:

Table 8: GitHub GraphQL API queries

Connector Object	GraphQL Query
Code Repository	Code Repository GraphQL queries
Open Source Finding	Open Source Finding GraphQL query
Open Source Finding Definition	Open Source Finding Definition GraphQL query
Package	Package GraphQL query

Code repository GraphQL queries

The following GraphQL query retrieves details about your organization, such as repositories, metadata, languages uses, repository topics, and more:

   query {
  organization(login: "organization-login") {
    id
    name
    repositories(first: 100, after: null) {
      nodes {
        id
        name
        description
        url
        homepageUrl
        sshUrl
        stargazerCount
        hasIssuesEnabled
        hasProjectsEnabled
        isArchived
        isDisabled
        isEmpty
        isInOrganization
        isLocked
        lockReason
        isMirror
        isPrivate
        isFork
        isSecurityPolicyEnabled
        isTemplate
        mergeCommitAllowed
        squashMergeAllowed
        rebaseMergeAllowed
        owner {
          id
          login
        }
        parent {
          id
          name
          url
        }
        latestRelease {
          id
          name
          isLatest
          publishedAt
          tag {
            id
            name
          }
          author {
            id
            login
          }
        }
        licenseInfo {
          id
          key
        }
        languages(first: 100) {
          nodes {
            id
            name
          }
          pageInfo {
            startCursor
            endCursor
            hasNextPage
            hasPreviousPage
          }
          totalCount
        }
        repositoryTopics(first: 100) {
          nodes {
            id
            topic {
              id
              name
            }
          }
        }
        pushedAt
        createdAt
        updatedAt
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
      totalCount
    }
  }
}

The following GraphQL query retrieves information about your organization and its packages. It retrieves the first 100 packages, along with their details such as ID, name, package type, latest version, and associated repository. The pageInfo and totalCount fields provide pagination information and the total number of packages in the organization:

query {
  organization(login: "organization-login") {
    id
    name
    packages(first: 100, after: null) {
      nodes {
        id
        name
        packageType
        latestVersion {
          version
        }
        repository {
          id
          name
        }
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
      totalCount
    }
  }
}

Open source finding GraphQL query

The following GraphQL query retrieves information about a specific repository and its vulnerability alerts. It retrieves the first two vulnerability alerts, along with their details such as ID, number, creation timestamp, dependency scope, dismiss reason, and other related information about the security vulnerability and its state. The pageInfo and totalCount fields provide pagination information and the total number of vulnerability alerts in the repository:

query {
  repository(name: "repository-name", owner: "organization-name") {
    id
    name
    vulnerabilityAlerts(first: 2, after: null) {
      nodes {
        id
        number
        createdAt
        dependencyScope
        dismissReason
        dismissedAt
        dismisser {
          id
          login
        }
        fixedAt
        securityAdvisory {
          id
          ghsaId
        }
        securityVulnerability {
          firstPatchedVersion {
            identifier
          }
          package {
            name
          }
          severity
          updatedAt
          vulnerableVersionRange
        }
        state
        vulnerableManifestFilename
        vulnerableManifestPath
        vulnerableRequirements
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
      totalCount
    }
  }
}

Open source finding definition GraphQL query

The following query retrieves a list of security advisories updated since "2022-09-22T18:21:40Z". It retrieves the first 100 security advisories, along with their details such as CVSS score, CWEs, description, identifiers, origin, references, severity, summary, and related timestamps. The pageInfo and totalCount fields provide pagination information and the total number of security advisories:

query {
  securityAdvisories(updatedSince: "2022-09-22T18:21:40Z", first: 100, after: null) {
    nodes {
      cvss {
        score
        vectorString
      }
      cwes(first: 100) {
        nodes {
          id
          cweId
        }
      }
      description
      ghsaId
      id
      identifiers {
        type
        value
      }
      origin
      publishedAt
      references {
        url
      }
      severity
      summary
      notificationsPermalink
      permalink
      updatedAt
      withdrawnAt
    }
    pageInfo {
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
    totalCount
  }
}

Package GraphQL query

The following query retrieves details about your organization, such as its unique identifier, name, and associated packages, along with information about their latest versions and related repositories:

query {
  organization(login: "organization-name") {
    id
    name
    packages(first: 100, after: null) {
      nodes {
        id
        name
        packageType
        latestVersion {
          version
        }
        repository {
          id
          name
        }
      }
      pageInfo {
        startCursor
        endCursor
        hasNextPage
        hasPreviousPage
      }
      totalCount
    }
  }
}

Changelog

The GitHub connector has undergone the following changes:

3.0.10

Added a new setting for custom properties in the Code Repository object.

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

Initial Integration+ release.

Required connection settings​

Generate GitHub authentication credentials​

Additional settings​

Types of data to retrieve​

Attribute mappings​

APIs​

GitHub REST API​

GitHub GraphQL API​

Code repository GraphQL queries​

Open source finding GraphQL query​

Open source finding definition GraphQL query​

Package GraphQL query​

Changelog​