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 -
Github Enterprise subscription
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:
Create an Oort service account at the Enterprise level
Make it a member of the orgs where you want Oort to ingest data
Do NOT make the account a member or give it access to orgs where you do not want Oort to collect data
Create PAT as described below
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
Enable displaying IP addresses in the Github Audit Log for your enterprise tenant as described in this article
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
In step 8, grant the following scopes to the token: read:audit_log read:enterprise read:org repo:invite user:email (NEW)
Click Generate Token and copy it to a secure location for use in the next section
Oort Configuration Steps
Sign in to your Oort tenant and perform the following steps:
From the Integrations page, click Add Integration and select Github
Enter a display name for the integration, such as Github customername.
Enter the value of your Github Enterprise slug, obtained above
Click Save.
Test the Configuration
To test the configuration and start the initial data collection -
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:
After creating the new PAT (classic) with the necessary scopes, log in to Oort
In the Oort console, click the 3 dot menu for the Github integration and select Edit Settings.
Test connectivity to ensure a successful connection.
Last updated