GitHub

What is GitHub? #

GitHub is a cloud-based platform that allows developers to store, track, and collaborate on software projects. GitHub is based on Git, an open-source version control tool that allows multiple people to make changes to source files at the same time.

Why Should You Use the GitHub Connector? #

The GitHub connector provides visibility into the users and repositories in your environment. You can use this visibility to:

• ensure assets are managed per your security policies
• derive relationships between assets, users, applications, and data

How Does This Connector Work? #

Meridian executes read-only requests to the GitHub REST API and ingests only meta-data about GitHib devices. Meridian does not retrieve any data stored on your assets.

Configuring the Connector in Meridian #

Source Documentation #

There are two ways to authenticate with GitHub. Both options are described below.

Creating an Application, App ID, and PEM Key for Meridian (Recommended) #

Before configuring the GitHub connector in Meridian, you must first create an application in GitHub. The application allows Meridian to securely communicate with GitHub. </,p>

For details on creating an application in GitHub, see https://docs.github.com/en/apps/creating-github-apps/writing-code-for-a-github-app/quickstart.

To find the App ID and the PEM key for the new application, see https://docs.github.com/en/apps/creating-github-apps/writing-code-for-a-github-app/quickstart#get-your-app-credentials-and-identifying-information.

To convert the .PEM file to a .JSON file:

jq -n --arg key "$(cat your-key.pem)" '{"private_key": $key}' > github-app-key.json </code?

Permissions for Application #

When creating the application, assign the following required permissions:

• Administration. Read only
• Code Scanning Alerts.  Read-only
• Contents = Read only
• Dependabot alerts. Read only
• Metadata. Mandatory
• Packages. Read only
• Email addresses. Read only
• Git SSH Keys. Read only
• Profile. Read and Write
• SSH signing keys. Read only
• Secret scanning alerts. Read only

Creating an API Token for GitHub (Legacy) #

Before configuring the GitHub connector in Meridian, you must first create an API Token. The Meridian connector uses the API token to access the GitHub API.

For details, see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic

1. From GitHub, Go to Settings -> Developer Settings -> Personal access token.

2. Generate a new token and then give the following read-only permissions:

   • read:packages

   • read:org

   • read:public_key

   • read:user

   • user:email

   • read:enterprise

3. To use a personal access token with an organization that uses SAML single sign-on (SSO), you must first authorize the token. For details, https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on.

4. To get the GitHub user email, the users must set their email addresses as “public”. In the user profile, select a primary email address to be “public”. If you do not set a public email address, then it will have a value of null.

API Documentation #

https://docs.github.com/en/rest?apiVersion=2022-11-28