Knowledge BaseRelease NotesRequest Demo

GitHub Logs

Panther supports pulling GitHub logs directly and audit log streaming

Overview

Panther supports the following methods of ingesting logs from GitHub:

If you have GitHub Enterprise Cloud, using the audit log streaming method to ingest logs is recommended, as it permits you to collect logs from your entire enterprise with a single integration. The API method can fetch logs for just one GitHub organization.

How to onboard GitHub Organization logs to Panther

Your Github Organization needs to be part of a Github Enterprise Cloud deployment. The Github Enterprise Server self-hosted option is not yet supported.

Step 1: Authorize Panther in GitHub

There are two different options to authorize Panther to receive GitHub audit logs:

  • Create a new OAuth App in GitHub and provide the app credentials to Panther

  • Generate a Personal Access Token in GitHub and provide credentials to Panther

Option 1: Create a new OAuth App

The steps below can only be performed if you have organization owner permission in your GitHub organization and a GitHub Enterprise subscription. If you need to configure multiple integrations for different GitHub Organizations using the same credentials, you can either use a Personal Access Token or an OAuth2 App that is created on the user account, instead of the Organization account. If any Organizations have enabled OAuth2 App Access Restrictions, the app must be first approved by an Organization admin.

  1. Log in to your GitHub Enterprise account.

  2. On the homepage of your organization's account, click on the Settings tab.

  3. Scroll to the bottom of the page and click on Developer Settings and then OAuth Apps.

  4. Click on Register an application. Fill in the form:

    • Enter a memorable application name into the Name field e.g. Panther Integration.

    • Enter your Panther instance's primary URL into the Homepage URL field e.g. https://test.runpanther.xyz

    • Copy the Redirect URL from Panther and paste into the Authorization Callback URL field.

      • To do this, you will need to log into Panther and set up GitHub as a log source by following the directions below. Once you've made it to the step where you see a Redirect URL, you can copy it and continue setting up your GitHub app.

  5. Once all necessary fields are filled in, click Register Application.

  6. Once the application is registered, you can view the Client ID and generate a new Client Secret. Store them in a secure location – you will need them in the next steps.

Step 2: Create a new GitHub API source in Panther

  1. In the lefthand navigation bar of your Panther Console, click Configure > Log Sources.

  2. Click Create New.

  3. Search for “GitHub API,” then click its tile.

  4. On the slide-out panel, click Start Setup.

  5. On the next screen, enter a descriptive name for the source (for example, My Github Audit logs) and the name of the Github organization you want to monitor.

  6. Click Setup.

  7. Authorize Panther to receive logs from GitHub - depending on the option you chose above, follow the steps below:

    • Use OAuth2 Authorization Flow: Enter the App Client ID and the Client Secret that you acquired from Github. You can find this information on the details page of the OAuth app in your Github account once you register the application.

    • Use a Personal Access Token: Copy the personal access token key and paste it into Personal Access token field.

  8. Click Setup.

  9. You will be presented with the option to Grant Access.

  10. Click Authorize.

  11. You will be directed to a success screen:

    The success screen reads, "Everything looks good! Panther will now automatically pull & process logs from your account"

    • You can optionally enable one or more Detection Packs.

    • The Trigger an alert when no events are processed setting defaults to YES. We recommend leaving this enabled, as you will be alerted if data stops flowing from the log source after a certain period of time. The timeframe is configurable, with a default of 24 hours.

      The "Trigger an alert when no events are processed" toggle is set to YES. The "How long should Panther wait before it sends you an alert that no events have been processed" setting is set to 1 Day

How to onboard GitHub logs via audit log streaming to Panther

There are two steps to configure GitHub audit log streaming with Panther:

  1. Set up audit log streaming from GitHub to a storage destination.

  2. Create a new GitHub Audit Log Streaming source in Panther.

Prerequisite

  • Audit log streaming must be configured in GitHub by your GitHub enterprise owner.

Step 1: Set up audit log streaming from GitHub to a storage destination

Panther supports ingesting GitHub audit log streaming data from two storage destinations. Choose one of the storage destinations below:

Step 2: Create a new GitHub audit log streaming source in Panther

  1. In the lefthand navigation bar of the Panther Console, click Configure > Log Sources.

  2. Click Create.

  3. Search for GitHub. Select the GitHub Audit Log Streaming tile.

    In the Panther Console, the Configure > Log Sources > Add New Sources screen shows a search for 'github.' Two tiles are populated, GitHub API and GitHub Audit Log Streaming. There is a red selector box around the latter.

  4. Select either S3 or GCS, depending on the transport method you chose.

  5. Follow the onboarding process for your chosen destination method:

How to onboard GitHub webhook events

Panther supports ingesting GitHub webhook events directly via HTTP.

GitHub webhook event ingestion is in open beta starting with Panther version 1.79, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.

Step 1: Create a GitHub Webhooks source in Panther

  1. In the left-hand navigation bar of your Panther Console, click Configure > Log Sources.

  2. Click Create New.

  3. Search for “GitHub Webhooks,” then click its tile.

  4. In the slide-out panel, the Transport Mechanism dropdown in the upper right corner will be pre-populated with the HTTP option.

    • Click Start Setup.

  5. Follow Panther's instructions for configuring an HTTP Source, beginning at Step 5.

    • During setup, for Logs Stream Type, choose JSON.

    • During setup, the Auth method will be preset to HMAC, and the HMAC Header Name will be preset to X-Hub-Signature-256.

      • Save the Secret Key Value you enter, as you'll need it in the next step.

Step 2: Create the webhook in GitHub

See detailed instructions for creating a GitHub webhook in GitHub's Creating webhooks documentation.

  1. In GitHub, navigate to your organization.

  2. In the left-hand navigation bar, click Webhooks. GitHub General settings are shown. In the left-hand sidebar, the Webhooks tab is circled.

  3. Click Add Webhook.

  4. Enter values for the following fields:

    • Content Type: Set to to application/json.

    • Payload URL: Set to the HTTP Source URL you generated in Panther in Step 1.

    • Secret value: Set this as the value you used during HTTP source creation in Step 1.

  5. Choose which events you want Panther to receive. All event types are supported, but not all of them have security value.

  6. Click Add Webhook.

Panther-managed detections

See Panther-managed rules for GitHub in the panther-analysis GitHub repository.

All Panther-managed GitHub detections include the filter_include_event helper function. You can customize this function to include or exclude certain logs based on a field value. This filter may be useful if you're using audit log streaming to ingest GitHub enterprise logs, but you'd like to filter out certain organizations. As an example, see it in use in the GitHub.Action.Failed detection.

Querying logs in Data Explorer

To see examples of querying GitHub logs in Panther's Data Explorer, see Github Audit logs queries.

Supported log types

Required fields in the schema are listed as "required: true" just below the "name" field.

GitHub.Webhook

GitHub webhooks emit notifications for any event generated within your GitHub organization or repository. For more information, see GitHub's webhook documentation.

Github.Audit

The audit log allows organization administrators to quickly review actions performed by members of your organization. For more information, see GitHub's documentation on accessing audit logs.

PreviousGCP LogsNextGitLab Logs

Last updated

Was this helpful?