Github

8/2023

Overview

Oort can connect to Github Enterprise tenants and provide insights into user identities and activity on that platform.

This document will walk you through the process of setting up access from Oort to Github Enterprise.

Requirements

The following requirements are necessary for the Github integration -

1. Github Enterprise subscription

2. A Github Enterprise admin account capable of creating Personal Access Tokens (classic)

Github API Permission Structure

Enterprise vs. Org

Oort has chosen to connect to Github environments at the Enterpise level rather than per Organization. This allows for the use of one API token for an entire customer environment, instead of an API token being required for each Org.

Therefore, an Enterprise Admin account or a Enterprise service account is required.

Excluding Specific Github Orgs

You may want to collect identity data for only certain orgs under your Github Enterprise tenant. To do that, you will need to follow this approach:

1. Create an Oort service account at the Enterprise level

2. Make it a member of the orgs where you want Oort to ingest data

3. Do NOT make the account a member or give it access to orgs where you do not want Oort to collect data

4. Create PAT as described below

5. Authorize SSO for the PAT to the desired orgs

Fine-grained vs Classic PAT

Oort leverages the Audit Log API methods to obtain necessary information. At this time, this portion of the API is only available when using PAT (classic) tokens. (Github article)

These endpoints only support authentication using a personal access token (classic). For more information, see "Managing your personal access tokens."

Compatible Checks

Currently, 9 security posture and threat detection Checks are compatible with the Github integration. Oort is continuously adding to this list, based on customer requests and also new and emerging identity-based threats for Github.

Github Configuration Steps

1. Login to Github with an Enterprise admin account. If you navigate to github.com/settings/enterprises, it should look something like the following:
2. Enable displaying IP addresses in the Github Audit Log for your enterprise tenant as described in this article

3. Follow the steps for creating a classic PAT as outlined in this Github article - https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic

4. In step 8, grant the following scopes to the token: read:audit_log read:enterprise read:org repo:invite user:email (NEW)

5. Click Generate Token and copy it to a secure location for use in the next section

6. Important - Ensure that the PAT has SSO authorization to all of the Github orgs under your Enterprise tenant, if SSO is in use. If at any point, you update the scopes associated with the token, be sure to reauthorize the token for the SSO enabled orgs within the enterprise tenant.
7. Note the slug for your Enterprise Github tenant. This can be found under your entprise profile tab.

Oort Configuration Steps

Sign in to your Oort tenant and perform the following steps:

1. From the Integrations page, click Add Integration and select Github

2. Enter a display name for the integration, such as Github customername.

3. Enter the value of your Github Enterprise slug, obtained above

4. Enter the Github PAT value
5. Click Save.

Test the Configuration

To test the configuration and start the initial data collection -

1. Click the 3 dots at the right of the new Github integration and select Test Connectivity.
2. Once successful, click the 3 dot menu again and select Collect Now. Collection may take some time, depending on the size of the environment.

Updating the PAT

If the PAT is due to expire or needs to be rotated, follow these steps:

1. After creating the new PAT (classic) with the necessary scopes, log in to Oort

2. In the Oort console, click the 3 dot menu for the Github integration and select Edit Settings.

3. Select Reset Credentials. Then enter the new PAT value and click Save.
4. Test connectivity to ensure a successful connection.