GitHub

Configure a new GitHub app

ℹ️

Note

A GitHub organization owner is required to install a new 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
   • 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
   • Webhooks

ℹ️

Note

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.
    • GitHub generates a new App ID. Save this for use when creating your Insights GitHub connector.
12. Under Private Keys, click Generate a private key.
    • A PEM file downloads to your local system. Save the contents of this file for use when creating your Insights GitHub connector.
13. In the left-hand menu, navigate to the Settings page, and click Install App.
14. Click Install. Review your settings and permissions, then click Install again.
15. Copy the URL string from your web browser's address bar. Save this for use when creating your Insights GitHub connector.
16. Navigate to the settings area for your organization.
17. In the left sidebar, click Archive > Logs, and select Audit Log.
18. Select Settings from the top navigation section of the log area.
19. Check the box Enable source IP disclosure and click Save.

Insights supports GitHub and uses the GitHub audit logs to develop recommendations and detections content. Several of these detections rely on the inclusion of IP addresses in the GitHub audit logs, which are not enabled by default. Note that IOP addresses are only included for an event if the actor is an organization member or owner or if the target is either an organization-owned repository that is private or internal, or an organization resource that is not a repository, such as a project.

Add a GitHub connector

1. Within the Insights Tenant dashboard, navigate to Menu > Connectors > Available and click Create Connector beside GitHub.
2. In the connection panel, enter a human-readable name for your GitHub connector.
3. 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.
4. Click Create Connector.

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

Upgrade GitHub Identity Security Insights app

Update Permissions

If you installed the GitHub app before Insights version 24.08, follow these steps to upgrade your GitHub app with new permissions that enable future 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
   • Codespaces lifecycle admin
   • Metadata
   • Secret scanning alerts (new)
   • 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 (new)
   • Organization dependabot secrets (new)
   • Secrets (new)
   • Webhooks

ℹ️

Note

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

1. Select Save changes.
2. An Update Permissions Request email may be sent to review the changes made to the app.
3. The changes can also be viewed here: https://github.com/settings/installations
4. The permission update to the app must be reviewed and accepted for the changes to take effect.

Enable Audit Logs

Insights now supports GitHub and uses the GitHub audit logs to develop recommendations and detections content. Several of these detections rely on the inclusion of IP addresses in the GitHub audit logs, which are not enabled by default. Note that IOP addresses are only included for an event if the actor is an organization member or owner or if the target is either an organization-owned repository that is private or internal or an organization resource that is not a repository, such as a project. Follow these steps to enable Audit logs for this feature.

1. In Github, 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 and click Save.