GitHub | Insights

Learn how to create a GitHub connector in BeyondTrust Identity Security Insights.

Insights uses GitHub audit logs to develop recommendations and detections.

Prerequisites

Before you configure the GitHub connector, ensure the following requirements are met.

GitHub access

• You are an organization owner in GitHub.
• You have access to the organization's Developer settings > GitHub Apps area.
• You can enable source IP disclosure in the organization's audit log settings.

Identity Security Insights access

• Administrator access to Identity Security Insights.
• Your Insights site is provisioned and active.

🚧

Important

Third-party documentation is subject to change. Updates might not be reflected in BeyondTrust documentation. For the most up-to-date information, visit the GitHub website.

Step 1: Create a GitHub app

1. Log in to GitHub as an organization owner.

2. In the upper-right corner, select your profile photo, and click Your organizations.

3. To the right of the organization where the Insights app will be installed, click Settings.

4. In the left sidebar, click Developer settings, and select GitHub Apps.

5. Click New GitHub App.

6. Provide the following information to create your new app:

   • GitHub App name: A unique name for your new application.
   • Homepage URL: https://app.beyondtrust.io

7. Under Webhook, uncheck Active.

8. Under Repository permissions, set the following resources to Read only:

   • Administration
   • Actions
   • Codespaces lifecycle admin
   • Metadata
   • Secret scanning alerts
   • Webhooks

9. Under Organization permissions, set the following resources to Read only:

   • Administration
   • Blocking users
   • Custom organization roles
   • Custom repository roles
   • Events
   • Members
   • Organization codespaces secrets
   • Organization dependabot secrets
   • Secrets
   • Self-hosted runners
   • Webhooks

ℹ️

Secret related permissions do not allow retrieval of the encrypted values.

10. Under Where can this GitHub App be installed?, select Only on this account.
11. Click Create GitHub App.

Step 2: Generate credentials and install the app

1. After creating the app, GitHub displays the app's settings page. Record the App ID. You will need it in the Final Step.
2. Under Private Keys, click Generate a private key.
3. A PEM file downloads to your local system. Save the contents of this file. You will need it in the Final Step.
4. In the left-hand menu, navigate to the Settings page, and click Install App.
5. Click Install. Review your settings and permissions, then click Install again.
6. Copy the URL string from your web browser's address bar. Save this URL. You will need it in the Final Step.

🚧

Important

Record all three values (App ID, PEM file contents, and Installed App URL) before proceeding. You will not be able to retrieve the PEM key contents again.

Step 3: Enable source IP disclosure in audit logs

Several detections rely on IP addresses being included in GitHub audit logs. Skipping this step will limit the effectiveness of Insights detections and recommendations.

IP addresses are only included in audit log events when:

• The actor is an organization member or owner
• The target is an organization-owned repository that is private or internal
• The target is an organization resource that is not a repository (such as a project).

To turn on audit logs:

1. Navigate to the settings area for your organization.
2. In the left sidebar, click Archive > Logs, and select Audit Log.
3. Select Settings from the top navigation section of the log area.
4. Check the box Enable source IP disclosure.
5. Click Save.

Final step: Create a GitHub connector

1. From Insights Home, select > Connectors.
   The Connectors page displays.
2. Click Total configured.
3. Click Create Connector and select GitHub from the list.

4. Enter a human-readable name for your GitHub connector.
5. Provide the following information from your GitHub app:
   • App ID: The app ID generated in step 11.
   • PEM Key: The contents of the PEM file downloaded in step 12.
   • Installed GitHub App URL: The URL string saved in step 15.
6. Click Create Connector.

Navigate to the Configured Connectors panel (Menu > Connectors > Configured) to confirm that connector creation was successful and review any connector settings.

Maintaining your connector

Upgrade permissions

If you installed the GitHub app before Insights version 24.08, upgrade your GitHub app with new permissions to enable enhanced detections and recommendations.

1. Go to your Installed GitHub Apps. Follow steps 1-4 to Configure a new GitHub app for detailed navigation steps.
2. Select the GitHub app configured for Insights and select Edit.
3. Select Permissions & events.
4. Under Repository permissions, set the following resources to Read only:
   • Administration
   • Actions (new)
   • Codespaces lifecycle admin
   • Metadata
   • Secret scanning alerts
   • Webhooks
5. Under Organization permissions, set the following resources to Read only:
   • Administration
   • Blocking users
   • Custom organization roles
   • Custom repository roles
   • Events
   • Members
   • Organization codespaces secrets
   • Organization dependabot secrets
   • Secrets
   • Self-hosted runners (new)
   • Webhooks

ℹ️

Secret related permissions do not allow retrieval of the encrypted values.

6. Select Save changes.
7. An Update Permissions Request email may be sent to the organization owner to review the changes. The changes can also be viewed here: https://github.com/settings/installations
8. The permission update must be reviewed and accepted for the changes to take effect.

Enable audit logs

If you did not enable source IP disclosure during initial setup, complete Step 3: Enable source IP disclosure in audit logs.