GitHub

GitHub

The Praetorian Guard Platform (PGP) provides comprehensive security scanning for GitHub repositories, helping organizations identify potential security risks like exposed secrets and misconfigurations. While PGP can scan any public repository without additional setup, you'll need to configure an integration to scan private repositories within your organization. In this page, we show how to integrate with GitHub by installing a GitHub App (recommended) or by using a Personal Access Token (PAT).

How the GitHub Integration Works

When you integrate with GitHub, PGP provides comprehensive security scanning capabilities powered by multiple advanced tools. All findings are triaged by expert security engineers who validate true positives, determine real-world impact, and identify when findings can be combined to lead to actual compromise.

PGP monitors repositories for public exposure changes, flagging newly created public repositories and private repositories that were recently made public within the last 24 hours.

For secrets detection, PGP uses Nosey Parker to scan repository history for exposed secrets including API keys, tokens, passwords, AWS credentials, database credentials, and other sensitive information patterns.

For GitHub Actions security, PGP leverages Gato and Gato-X to detect security risks such as self-hosted runner workflows, privilege escalation vulnerabilities (PwnRequest risks), injection vulnerabilities, and workflow misconfigurations. These tools can analyze cross-repository workflows and reusable actions, identifying issues that other scanners may miss. This helps prevent attackers from running malicious code in build pipelines, stealing credentials, or compromising self-hosted build machines.

Choosing an Authentication Method

We recommend installing the GitHub App for new integrations. Compared to a Personal Access Token, the GitHub App provides:

  • Granular, least-privilege permissions scoped to only what's needed for security scanning

  • Organization-level installation that doesn't depend on a single user's account or token expiration

  • Easier ongoing management — repository access can be modified at any time through GitHub's App settings

  • Better auditability and revocation through GitHub's native App controls

Use a Personal Access Token (PAT) only when installing a GitHub App is not possible in your environment.

Setup Instructions

Setting Up GitHub App Authentication in PGP (Recommended)

GitHub App authentication provides a more secure and granular way to integrate PGP with your GitHub organization compared to using Personal Access Tokens (PATs). This integration allows PGP to scan your repositories for security risks while maintaining proper access controls.

Prerequisites

  • A GitHub organization account

  • Admin access to your GitHub organization

  • A PGP account

Setup Steps

Access PGP Integrations

  • Log into your PGP account

  • Navigate to the Integrations page

  • Select "GitHub" from the "Source Code Managers" section

Initiate GitHub App Installation

  • Click the "Connect" button

  • In the popup dialog, select the "Install GitHub App" option

  • You'll be redirected to GitHub's App installation page

Configure GitHub App Access

  • Select your target organization from the list

Choose repository access level

  • All repositories

  • Only select repositories

  • Click "Authorize & Request"

Verify Integration

  • Verify the installation in your organization's GitHub Apps settings:

    • Go to Settings → Applications

  • Return to PGP

    • The integration status should show as successful in the integrations table

    • You can manage the app's access permissions anytime through your organization's GitHub settings

Required Permissions

The GitHub App requires the following permissions:

  1. Administration (Read)

    • Allows PGP to read repository settings and configuration

    • Used for security scanning and misconfiguration detection

  2. Code (Read)

    • Enables scanning of repository contents

    • Required for secret detection and code analysis

  3. Commit Statuses (Read)

    • Allows monitoring of commit statuses

    • Used for tracking security scan results

  4. Deployments (Read)

    • Enables monitoring of deployment activities

    • Used for CI/CD misconfiguration scanning

  5. Metadata (Read)

    • Provides access to repository metadata

    • Used for repository information and configuration analysis

  6. Pull Requests (Read)

    • Allows monitoring of pull request activities

    • Used for security review integration

  7. Repository Projects (Read)

    • Enables access to repository project boards

    • Used for security issue tracking and management

Managing Access

  • You can modify repository access at any time through GitHub's App settings

  • To remove access, you can uninstall the app from your organization's GitHub Apps settings

  • Access can be configured at the organization or repository level

Troubleshooting

If you encounter any issues during the integration process:

  • Verify you have the necessary permissions in your GitHub organization

  • Check that the GitHub App installation was completed successfully

  • Ensure all required permissions were granted during installation

  • Contact PGP support at support@praetorian.com for assistance

Security Considerations

  • The GitHub App uses OAuth for authentication

  • Access tokens are managed securely by PGP

  • Permissions are scoped to only what's necessary for security scanning

  • You can revoke access at any time through GitHub's settings

This setup provides a secure and maintainable way to integrate PGP with your GitHub organization while maintaining proper access controls and security practices.

GitHub PAT (Alternative)

If you can't install a GitHub App, you can integrate GitHub with PGP using a Personal Access Token (PAT). Start by visiting GitHub's Personal Access Tokens page and generating a new token.

Give the PAT a descriptive name and set an appropriate expiration period. Make sure to authorize the token for your target organization.

Choose the repository access for the token:

Under Repository Permissions, grant "Contents: Read-only" access to allow PGP to scan repository contents.

Click Generate token at the bottom of the page. Copy the token to your clipboard and navigate back to PGP.

Configuring the Integration in PGP

Navigate to the Integrations page and select GitHub from the "Source Code Managers" section.

Enter your GitHub organization's URL and paste your PAT in the provided fields, then click Connect to establish the integration.

Once integrated, PGP will scan your repositories for security risks, monitor for public exposure changes, and provide expert triage of all findings.