GitHub Authentication in Prowler

​

Common Setup

​

Authentication Methods Overview

​

Required Permissions

​

Repository Permissions

​

Organization Permissions

​

Account Permissions (Fine-Grained PAT only)

​

Permissions and Check Coverage

• repository_branch_delete_on_merge_enabled

​

Step-by-Step Permission Assignment

​

Fine-Grained Personal Access Token (Recommended for Individual Use)

• Individual users scanning their own repositories
• Quick setup without app registration overhead
• Temporary access with mandatory expiration
• Repository-specific access when you only need to scan certain repos

1. Navigate to GitHub Settings > Developer settings.
2. Click Personal access tokens > Fine-grained tokens > Generate new token.
3. Configure basic settings:
   • Token name: Descriptive name (e.g., “Prowler Security Scanner”)
   • Expiration: 90 days or less (recommended)
   • Resource owner:
     • Personal account (for user repositories)
     • Organization name (for organization scanning - requires admin approval)
   • Repository access: “All repositories” (recommended)
4. Configure Repository permissions:
   • Administration: Read
   • Contents: Read
   • Metadata: Read (auto-selected)
   • Dependabot alerts: Read
5. Configure Organization permissions (only appears when Resource owner is an organization):
   • Administration: Read
   • Members: Read
6. Configure Account permissions:
   • Email addresses: Read (optional)
7. Click Generate token and copy the token immediately.

​

OAuth App Token

• repo: Full control of repositories
• read:org: Read organization and team membership
• read:user: Read user profile data

1. Navigate to GitHub Settings > Developer settings > OAuth Apps.
2. Click New OAuth App and complete:
   • Application name
   • Homepage URL
   • Authorization callback URL
3. Obtain authorization code:
   Copy

   https://github.com/login/oauth/authorize?client_id={app_id}
   
4. Exchange authorization code for access token:
   Copy

   https://github.com/login/oauth/access_token?code={code}&client_id={app_id}&client_secret={secret}
   

​

GitHub App Credentials

1. Navigate to GitHub Settings > Developer settings > GitHub Apps.
2. Click New GitHub App and complete:
   • GitHub App name: Descriptive name (e.g., “Prowler Security Scanner”)
   • Homepage URL: Your organization’s URL or Prowler documentation
   • Webhook: Uncheck “Active” (Prowler doesn’t need webhooks)
3. Configure Repository permissions (see table above):
   • Administration: Read
   • Contents: Read
   • Metadata: Read (auto-selected)
   • Dependabot alerts: Read
4. Configure Organization permissions (see table above):
   • Administration: Read
   • Members: Read
5. Under Where can this GitHub App be installed?, select:
   • “Only on this account” for single-organization use
   • “Any account” if you need to install across multiple organizations
6. Click Create GitHub App.
7. On the app settings page:
   • Record the App ID (displayed at the top)
   • Click Generate a private key and download the .pem file
8. Install the GitHub App:
   • Click Install App in the left sidebar
   • Select target account/organization
   • Choose “All repositories” or select specific repositories
   • Click Install

​

Prowler Cloud Authentication

​

Using Personal Access Token

1. In Prowler Cloud, navigate to Configuration > Cloud Providers > Add Cloud Provider > GitHub.
2. Enter your GitHub Account ID (username or organization name).
3. Select Personal Access Token as the authentication method.
4. Enter your Fine-Grained Personal Access Token.
5. Click Verify to test the connection, then Save.

​

Using OAuth App Token

1. Follow the same steps as Personal Access Token.
2. Select OAuth App Token as the authentication method.
3. Enter your OAuth App Token.

​

Using GitHub App

1. Follow the same steps as Personal Access Token.
2. Select GitHub App as the authentication method.
3. Enter your GitHub App ID and upload the private key (.pem file).

​

Prowler CLI Authentication

​

Authentication Methods

1. GITHUB_PERSONAL_ACCESS_TOKEN
2. GITHUB_OAUTH_APP_TOKEN
3. GITHUB_APP_ID and GITHUB_APP_KEY

​

Using Environment Variables (Recommended)

# Personal Access Token (Recommended)
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxx"
prowler github

# OAuth App Token
export GITHUB_OAUTH_APP_TOKEN="oauth_token_here"
prowler github

# GitHub App
export GITHUB_APP_ID="123456"
export GITHUB_APP_KEY="$(cat /path/to/private-key.pem)"
prowler github

​

Using CLI Flags

# Personal Access Token
prowler github --personal-access-token ghp_xxxxxxxxxxxx

# OAuth App Token
prowler github --oauth-app-token oauth_token_here

# GitHub App
prowler github --github-app-id 123456 --github-app-key-path /path/to/private-key.pem

​

Scan Scope

prowler github
prowler github --repository username/my-repo

prowler github --organization org-name
prowler github --organization org1 --organization org2

prowler github --severity critical
prowler github --checks repository_default_branch_protection_enabled
prowler github --compliance cis_1.0_github

​

Troubleshooting

​

”Insufficient Permissions” Errors

1. Verify token has all required permissions
2. For organization scans, ensure organization approved the Fine-Grained Token
3. For merge settings checks, accept MANUAL status (Write permission not recommended)

​

“No Organizations Found”

​

Organization Checks Return MANUAL

1. Edit token and grant Organization → Administration: Read
2. Ensure token’s Resource owner is the organization (not personal account)
3. Get organization admin approval

​

Token Not Showing Organization Permissions

​

Rate Limiting

• Scan during off-peak hours
• Use --repository to scan specific repos instead of all
• Implement delays between scans

​

Token Expired or Revoked

1. Check token expiration date in GitHub settings
2. Verify token wasn’t revoked
3. For Fine-Grained Tokens, check if organization approval was revoked
4. Generate a new token

​

Additional Resources

• GitHub REST API Authentication
• Fine-Grained Personal Access Tokens
• GitHub Apps Documentation
• GitHub API Rate Limits
• Getting Started Guide