Documentation Index

Fetch the complete documentation index at: https://help.nucleussec.com/llms.txt

Use this file to discover all available pages before exploring further.

GitHub Advanced Security

  • 4 minute(s) read
Prev Next

Overview

Nucleus enables you to ingest vulnerabilities directly from GitHub Advanced Security into the Nucleus console using an automated connector. The connector integrates seemlessly with your GitHub organisation by leveraging a GitHub App to seamlessly query and ingest data into Nucleus so that you can easily manage your data from Github at scale.

The GitHub connector currently supports ingesting

  • CodeQL analyses from GitHub Code Scanning
  • alerts on open source dependencies from Dependabot
  • secrets from GitHub Secrets Scanning

Connector setup

Important!

The user setting up the GitHub connector needs permissions in Nucleus (Project Admin) to create the connector and permissions in GitHub to create Apps (Admin).

Connector Setup Checklist

Follow the steps in this checklist to successfully setup this connector:

  1. Create the GitHub App
    Create the Nucleus GitHub app in your GitHub organization.

  2. GitHub App Installation
    Install and configure the app within the organization.

  3. Vulnerability Scan Data Ingestion
    Create one or more vulnerability scan ingest rules to ingest data from GitHub.

1. Create the GitHub App

  1. In Nucleus, go to Integration Hub> Connector Setup.

  2. Under the Scanners section, click the GitHubb App icon.

  3. In the Setup GitHub Connector popup, complete the following fields:

Field Description
Name Enter a short unique name for the connector, such as "GitHub Org name"
Description Optionally, enter a description for the connector
Organization Enter the name of the organization you want to install the app into, for example 'nucleus-security'
image.png

  1. Click the Install GitHub App button. This will open a new browser tab, directing to you create a GitHub App.

  2. Enter a name for the GitHub App such as Nucleus Connector:


    image.png

  1. Click Create GitHub App for org-name

  2. The app is now created and you should now be redirected to the final setup page in Nucleus. You should be presented with the following screen:

image.png

Next Steps

The connector setup is not yet complete! The Nucleus GitHub App has been created but still needs to be installed. Follow the steps in the next section to install the app.

2. GitHub App Installation

  1. Find your Organization where you just installed the GitHub app.
  2. Go to its Settings page.
  3. In the lefthand navbar find Developer Settings > GitHub Apps

image.png

  1. Find your new app in the list ("Test-App-Nucleus" from our example above).
  2. Click Edit on this app.

image.png

  1. In the lefthand navbar, click Install App.
  2. Find your organizations where you want to install the app and click "Install".
  3. You'll see options to select repositories to enable for the app:

image.png

Take heed!

If you chose "Only select repositories" from this page, then Nucleus will not be able to see new repositories as they are created in this organization.
If you want to sync everything from GitHub into Nucleus - including future repositories - we recommend selecting "All repositories". Otherwise you will need to periodically enable new repositories for Nucleus to sync.

  1. Click Install

  2. Now go back to your Nucleus connector and click Verify Connection to make sure the app is working correctly.

  3. Click Save & Finish to finish connector configuration.

3. Vulnerability Scan Data Ingestion

  1. Go to Integration Hub > Import via Connector.
  2. Select the GitHub connector you just created.
  3. Choose the source (Code Scanning, Dependabot or Secrets Scanning if enabled for your organization) and import method:

image.png

  1. Click Next and select what you want to import.
  2. Select the import frequency as a one-time import, or auto-imported on a schedule.
  3. Click Save & Finish.

The data will now be synced based on the schedule you set up!

Connector Behaviour

Finding Statuses

Nucleus maps statuses from GitHub Advanced Security for both Dependabot and CodeQL findings to finding statuses in Nucleus. Status changes appear in Nucleus the next time a new scan is ingested for each respective asset.

CodeQL

Dismissed reason in CodeQL Status in Nucleus
false positive False Positive
used in tests False Positive
won't fix Accepted Risk

Dependabot

Dismissed reason in Dependabot Status in Nucleus
Risk is tolerable to this project Accepted Risk
This alert is inacurate or incorrect False Positive
Vulnerable code is not actually used False Positive
A fix has already been started In Progress
No bandwidth to fix this Exception Granted
Blank / No message provided Accepted Risk

Additional Metadata

Nucleus pulls in all the associated information about each GitHub repository as Additional Metadata. All of these fields can be used for filtering, automation, and reporting throughout the Nucleus application.

image.png

One of the primary uses of this is to automatically create Nucleus Asset groups dynamically based on the GitHub custom field data, such as "github.teams".

Custom Properties

Github Repository Custom Properties are currently ingested by Secrets Scanning only and are not supported in the Dependabot or CodeQL integrations. To ingest custom properties for Dependabot or CodeQL, please setup a Secrets Scanning ingestion job so that these properties are ingested and updated.

FAQ

Q: Can we set up Github as an enterprise vs. an organization?
A: No, we can only set it up per Org due to Github authentication requirements.