Skip to main content
Prowler supports multiple methods to authenticate with GitHub. These include: This flexibility enables scanning and analysis of GitHub accounts, including repositories, organizations, and applications, using the method that best suits the use case.

​
Personal Access Token (PAT)

Personal Access Tokens provide the simplest GitHub authentication method, but it can only access resources owned by a single user or organization.
Classic Tokens DeprecatedGitHub has deprecated Personal Access Tokens (classic) in favor of fine-grained Personal Access Tokens. We recommend using fine-grained tokens as they provide better security through more granular permissions and resource-specific access control.
  1. Navigate to GitHub Settings
    • Open GitHub and sign in
    • Click the profile picture in the top right corner
    • Select “Settings” from the dropdown menu
  2. Access Developer Settings
    • Scroll down the left sidebar
    • Click “Developer settings”
  3. Generate Fine-Grained Token
    • Click “Personal access tokens”
    • Select “Fine-grained tokens”
    • Click “Generate new token”
  4. Configure Token Settings
    • Token name: Give your token a descriptive name (e.g., “Prowler Security Scanner”)
    • Expiration: Set an appropriate expiration date (recommended: 90 days or less)
    • Repository access: Choose “All repositories” or “Only select repositories” based on your needs
    Public repositoriesEven if you select ‘Only select repositories’, the token will have access to the public repositories that you own or are a member of.
  5. Configure Token Permissions To enable Prowler functionality, configure the following permissions:
    • Repository permissions:
      • Administration: Read-only access
      • Contents: Read-only access
      • Metadata: Read-only access
      • Pull requests: Read-only access
    • Organization permissions:
      • Administration: Read-only access
      • Members: Read-only access
    • Account permissions:
      • Email addresses: Read-only access
  6. Copy and Store the Token
    • Copy the generated token immediately (GitHub displays tokens only once)
    • Store tokens securely using environment variables
GitHub Personal Access Token Permissions
Security RiskClassic tokens provide broad permissions that may exceed what Prowler actually needs. Use fine-grained tokens instead for better security.
  1. Navigate to GitHub Settings
    • Open GitHub and sign in
    • Click the profile picture in the top right corner
    • Select “Settings” from the dropdown menu
  2. Access Developer Settings
    • Scroll down the left sidebar
    • Click “Developer settings”
  3. Generate Classic Token
    • Click “Personal access tokens”
    • Select “Tokens (classic)”
    • Click “Generate new token”
  4. Configure Token Permissions To enable Prowler functionality, configure the following scopes:
    • repo: Full control of private repositories (includes repo:status and repo:contents)
    • read:org: Read organization and team membership
    • read:user: Read user profile data
    • security_events: Access security events (secret scanning and Dependabot alerts)
    • read:enterprise: Read enterprise data (if using GitHub Enterprise)
  5. Copy and Store the Token
    • Copy the generated token immediately (GitHub displays tokens only once)
    • Store tokens securely using environment variables

​
OAuth App Token

OAuth Apps enable applications to act on behalf of users with explicit consent.

​
Create an OAuth App Token

  1. Navigate to Developer Settings
    • Open GitHub Settings → Developer settings
    • Click “OAuth Apps”
  2. Register New Application
    • Click “New OAuth App”
    • Complete the required fields:
      • Application name: Descriptive application name
      • Homepage URL: Application homepage
      • Authorization callback URL: User redirection URL after authorization
  3. Obtain Authorization Code
    • Request authorization code (replace {app_id} with the application ID):
    https://github.com/login/oauth/authorize?client_id={app_id}
  4. Exchange Code for Token
    • Exchange authorization code for access token (replace {app_id}, {secret}, and {code}):
    https://github.com/login/oauth/access_token?code={code}&client_id={app_id}&client_secret={secret}

​
GitHub App Credentials

GitHub Apps provide the recommended integration method for accessing multiple repositories or organizations.

​
Create a GitHub App

  1. Navigate to Developer Settings
    • Open GitHub Settings → Developer settings
    • Click “GitHub Apps”
  2. Create New GitHub App
    • Click “New GitHub App”
    • Complete the required fields:
      • GitHub App name: Choose a unique, descriptive name (e.g., “Prowler Security Scanner”)
      • Homepage URL: Enter your organization’s website or the Prowler documentation URL (e.g., https://prowler.com or https://docs.prowler.com). This is just for reference and doesn’t affect functionality.
      • Webhook URL: Leave blank or uncheck “Active” under Webhook. Prowler doesn’t require webhooks since it performs on-demand scans rather than responding to GitHub events.
      • Webhook secret: Leave blank (not needed for Prowler)
      • Permissions: Configure in the next step (see below)
    About Homepage URL and WebhooksThe Homepage URL is purely informational and can be any valid URL - it’s just displayed to users who view the app. Use your company website, your GitHub organization URL, or even https://docs.prowler.com.Webhooks are not required for Prowler. Since Prowler performs on-demand security scans when you run it (rather than automatically responding to GitHub events), you can safely disable webhooks or leave the URL blank.
  3. Configure Permissions To enable Prowler functionality, configure these permissions:
    • Repository permissions:
      • Contents (Read)
      • Metadata (Read)
      • Pull requests (Read)
    • Organization permissions:
      • Members (Read)
      • Administration (Read)
    • Account permissions:
      • Email addresses (Read)
  4. Where can this GitHub App be installed?
    • Select “Any account” to be able to install the GitHub App in any organization.
  5. Generate Private Key
    • Scroll to the “Private keys” section after app creation
    • Click “Generate a private key”
    • Download the .pem file and store securely
  6. Record App ID
    • Locate the App ID at the top of the GitHub App settings page

​
Install the GitHub App

  1. Install Application
    • Navigate to GitHub App settings
    • Click “Install App” in the left sidebar
    • Select the target account/organization
    • Choose specific repositories or select “All repositories”

​
Best Practices

​
Security Considerations

Implement the following security measures:
  • Secure Credential Storage: Store credentials using environment variables instead of hardcoding tokens
  • Secrets Management: Use dedicated secrets management systems in production environments
  • Regular Token Rotation: Rotate tokens and keys regularly
  • Least Privilege Principle: Grant only minimum required permissions
  • Permission Auditing: Review and audit permissions regularly
  • Token Expiration: Set appropriate expiration times for tokens
  • Usage Monitoring: Monitor token usage and revoke unused tokens

​
Authentication Method Selection

Choose the appropriate method based on use case:
  • Personal Access Token: Individual use, testing, or simple automation
  • OAuth App Token: Applications requiring user consent and delegation
  • GitHub App: Production integrations, especially for organizations

​
Troubleshooting Common Issues

​
Insufficient Permissions

  • Verify token/app has necessary scopes/permissions
  • Check organization restrictions on third-party applications

​
Token Expiration

  • Confirm token has not expired
  • Verify fine-grained tokens have correct resource access

​
Rate Limiting

  • GitHub implements API call rate limits
  • Consider GitHub Apps for higher rate limits

​
Organization Settings

  • Some organizations restrict third-party applications
  • Contact organization administrator if access is denied