Setting Up the Panther GitHub App (Beta)

Overview

Installing the Panther GitHub App on your detection content repository allows Panther to open pull requests in your repository on your behalf. Once the app is installed, edits to supported detection types in the Panther Console produce pull requests in your repository instead of writing directly to Panther—see Creating a GitHub pull request from the Panther Console for the list of supported types.

The setup process involves two roles, which may be filled by two different people or by the same person:

• A Panther user with the Edit Settings & SAML Preferences permission, who configures the git repository in the Panther Console and generates a registration link.

• A GitHub organization owner, who opens the registration link and completes the app registration and installation on GitHub. This person does not need a Panther account.

The Panther user generates the link and shares it—along with the name of the target repository—with the GitHub organization owner (by email, Slack, or any other channel). The link is valid for 24 hours and can only be used once. Generating a new link invalidates the previous one.

Prerequisites

• All of your Panther detection content is in a single GitHub repository. The Panther GitHub App does not support integrating with multiple repositories at this time.

• The person who opens the registration link must be an owner of the GitHub organization that contains your detection repository. GitHub does not allow non-owners to register an app on behalf of the organization.

Step 1: Configure the repository and generate a registration link (Panther user)

1. In the Panther Console, click the gear icon in the upper-right corner and select General.

2. Click the Developer Workflow tab.

   
3. In the Git Sync section, fill in the fields:

   • GitHub Organization: the name of the GitHub organization that owns your detection repository.

   • Repository Name: the name of the repository that contains your Panther detection content.

   • Branch Name: the branch that Panther should submit pull requests against for Console-originated changes—typically main or master.

4. Click Save Repository. The GitHub App Registration section appears below, and Edit Connection and Disconnect buttons appear next to the configuration fields. You can use these buttons at any time—see Editing or removing the integration for the effect of each.

   

   Before clicking Generate Registration Link in the next step, confirm that a GitHub organization owner is available to complete the registration on GitHub within 24 hours—that's how long the generated link stays valid.

5. Click Generate Registration Link. Panther displays the full URL in the Registration Link field.

   
6. Click Copy and share two pieces of information with the GitHub organization owner:

   • The registration link.

   • The name of the target repository (from the Repository Name field above), so they can select it correctly when installing the app.

Step 2: Open the registration link (GitHub organization owner)

The GitHub organization owner opens the link in a browser. No Panther account is required.

The page shows the GitHub organization the app will be registered for and the link's expiry time. The GitHub organization owner clicks Continue to GitHub.

If an error appears instead of the registration details, see An error appears when first opening the link.

Step 3: Create the GitHub App on GitHub

GitHub displays a form with a pre-filled app name (e.g., {your-org}-panther-gh-app). The GitHub organization owner can change the name if they like, but it must be unique across all of GitHub.

The GitHub organization owner clicks Create GitHub App. If the registration succeeds, GitHub takes them to the app installation page. Otherwise, the browser lands on an error page—either GitHub's own error, or Panther's registration page with an error message:

• If GitHub rejects the app name, see The app name is already taken on GitHub.

• If the browser is redirected back to the Panther registration page with an error, see An error appears after clicking Create GitHub App or Install.

Step 4: Install the app on the target repository

On GitHub's installation page, the GitHub organization owner selects Only select repositories, chooses the target repository (the one shared by the Panther user in Step 1), and clicks Install.

If the installation succeeds, GitHub redirects the browser back to the Panther Console—if the GitHub organization owner is not logged in to Panther (the typical case), they land on the Panther login page. They can close the tab; their involvement ends here.

If an error occurs, the browser is redirected back to the Panther registration page with an error message—see An error appears after clicking Create GitHub App or Install.

Step 5: Review the result in the Panther Console (Panther user)

Panther automatically runs a connection test against your configured repository and delivers a notification in the Panther Console. Panther users with the Edit Settings & SAML Preferences permission receive this notification; it cannot be unsubscribed from.

If the installation succeeded and the app has access to the target repository, the Panther user receives a success notification:

You can also verify the connection on Settings > General > Developer Workflow. The Sync Status section displays the outcome of the most recent test, and the Test Configuration section shows whether the repository is accessible and the configured branch exists. You can re-run the test at any time by clicking Test Connection in the Test Configuration section:

Once you see a success notification, your git integration is fully configured. You can now create pull requests from the Panther Console when editing or creating detections.

If instead the notification is a warning or error, see:

• Warning: The app was installed on multiple repositories, including the target.

• Error: The app was installed, but Panther can't access the target repository.

Editing or removing the integration

The Panther user can edit the repository configuration or remove the integration entirely from the Git Sync section of Settings > General > Developer Workflow. Both options are available at any point after the configuration is first saved—including while a registration flow is in progress.

• Edit Connection opens the GitHub Organization, Repository Name, and Branch Name fields for editing. Editing the configuration does not affect a registration flow that is currently in progress.

• Disconnect is the clean uninstall path. Clicking Disconnect removes the repository configuration entirely and uninstalls the Panther GitHub App from your repository. This also invalidates any in-progress registration link, and returns the Panther Console to its default detection-save behavior (no longer routing edits through Create PR). Existing pull requests in GitHub are unaffected and remain open.

To set up the integration again after disconnecting, restart from Step 1.

Troubleshooting

An error appears when first opening the link

If the GitHub organization owner opens the registration link and immediately sees an error instead of the registration details:

The most likely causes are:

• The link was copied incorrectly. If the link was shared over a channel that truncated or mangled the URL (for example, a chat client that split it across lines), copy the link again from the Panther Console and re-share it.

• The link has expired. Registration links are valid for 24 hours from the time they are generated.

To recover, the Panther user returns to Step 1 and generates a fresh registration link, then shares it—along with the repository name—with the GitHub organization owner. The GitHub organization owner then restarts the flow from Step 2.

An error appears after clicking Create GitHub App or Install

If the GitHub organization owner successfully loads the registration page, clicks through to GitHub, and completes either Create GitHub App or Install, but is then redirected back to the Panther registration page with an error message:

The most likely causes are:

• The link expired during the flow. The GitHub steps took longer than 24 hours to complete, so the server-side expiry check failed.

• The link was superseded. A Panther user generated a new registration link while the flow was in progress. Generating a new link invalidates any earlier link, even one that is currently being used.

• A validation error occurred on Panther's side when exchanging credentials with GitHub.

A GitHub App may already exist in the GitHub organization at this point, depending on how far the flow progressed before the error.

To recover:

1. The GitHub organization owner opens the GitHub organization in a browser, clicks Settings, then in the left sidebar expands Developer settings and clicks GitHub Apps:

   

   The page lists the GitHub Apps registered to the organization. If a partially registered Panther app is present, click Edit on its row:

   

   In the app's settings, open the Advanced tab and scroll to the Danger zone section, then click Delete GitHub App:

   

   Read the confirmation dialog carefully, then type the GitHub App name into the confirmation field:

   

   Once the name matches, the I understand the consequences, delete this GitHub App button becomes active. Click it to delete the app:

   
2. The Panther user returns to Step 1 and generates a fresh registration link, then shares it—along with the repository name—with the GitHub organization owner.

3. The GitHub organization owner restarts the flow from Step 2.

The GitHub organization owner is not actually an organization owner

GitHub requires that the person completing the app registration is an owner of the target organization. If the person opening the link is a member but not an owner, GitHub displays a banner at the top of the Create GitHub App page in Step 3 explaining that they don't have permission:

To recover, have a GitHub organization owner open the registration link. If the original link is still within its 24-hour window, it can be reused—no need to generate a new one.

The app name is already taken on GitHub

GitHub App names must be unique across all of GitHub. If the pre-filled name is already taken, clicking Create GitHub App in Step 3 surfaces a "Name is already taken" error tooltip on the GitHub App name field:

To recover, the GitHub organization owner edits the GitHub App name field to a unique value and clicks Create GitHub App again. The rest of the flow is unaffected.

The app was installed, but Panther can't access the target repository

This happens in two scenarios:

• The app was installed on a single repository that is not the target repository. The Panther user receives this error notification:

  
• The app was installed on multiple repositories, none of which is the target repository. The Panther user receives this error notification:

  

In both cases, the integration will not work until the installation is updated. To recover, follow the steps in Updating the app's repository access on GitHub to set the target repository as the only repository the app can access.

The Panther user can confirm the fix worked by returning to Settings > General > Developer Workflow and clicking Test Connection under the Test Configuration section. After a successful test, the section displays green checkmarks next to Repository accessible and Branch [name] exists:

The app was installed on multiple repositories, including the target

If the app is installed on multiple repositories and the target repository is among them, the integration will work—but the app has more access than Panther needs. The Panther user receives a warning notification recommending that access be restricted to only the detection repository:

To follow the principle of least privilege, the GitHub organization owner can restrict the installation by following the steps in Updating the app's repository access on GitHub. Because the connection test already passes in this scenario, Panther cannot detect the change—the Panther user should confirm directly with the GitHub organization owner that the unrelated repositories have been removed.

Updating the app's repository access on GitHub

The GitHub organization owner can update which repositories the Panther GitHub App can access at any time, without going through the registration flow again. Use these steps to add the target repository to the installation, remove repositories the app shouldn't have access to, or both.

1. Open the GitHub organization in a browser, click Settings, then in the left sidebar under Third-party Access click GitHub Apps:

   
2. On the Installed GitHub Apps page, find the Panther app and click Configure:

   
3. Scroll to the Repository access section. With Only select repositories chosen, click the repository selector to add or remove repositories:

   
4. Adjust the selection so that the target repository is listed and any unrelated repositories are removed. Click Save: