GitHub Authentication in Prowler

Prowler for GitHub offers multiple authentication types across Prowler Cloud and Prowler CLI.

Common Setup

Authentication Methods Overview

Prowler offers three authentication methods. Fine-Grained Personal Access Tokens are recommended for most use cases.

Method	Best For	Key Benefit
Fine-Grained Personal Access Token	Individual users, quick setup	Simple, user-scoped access
GitHub App	Organizations, automation, CI/CD	Organization-scoped, no personal account dependency
OAuth App Token	Delegated user authorization	User-consented access flows

Which should I choose?

• Personal scanning or quick setup: Use Fine-Grained PAT
• Organization-wide scanning or CI/CD pipelines: Use GitHub App (recommended for production)
• Building apps with user authorization: Use OAuth App

Classic Personal Access Tokens

GitHub has deprecated classic Personal Access Tokens. Use Fine-Grained Tokens instead - they provide granular permission control and better security.

Required Permissions

Required permissions depend on the scan scope: user repositories, organization repositories, or both.

Repository Permissions

Required for scanning repository security settings:

Permission	Access Level	Purpose	Checks Enabled
Administration	Read	Branch protection, security settings	All branch protection checks, secret scanning status
Contents	Read	File existence checks	repository_public_has_securitymd_file, repository_has_codeowners_file
Metadata	Read	Basic repository information	All checks (automatically granted)
Dependabot alerts	Read	Dependency vulnerability scanning	repository_dependency_scanning_enabled

Pull requests permission is optional. It’s only needed if you want to audit PR-specific settings beyond what branch protection provides.

Organization Permissions

Required for scanning organization-level security settings:

For Fine-Grained PATs: Organization permissions only appear when the Resource Owner is set to an organization (not your personal account).

For GitHub Apps: Organization permissions are configured during app creation and apply to all organizations where the app is installed.

Permission	Access Level	Purpose	Checks Enabled
Administration	Read	Organization security policies	organization_members_mfa_required, organization_repository_creation_limited, organization_default_repository_permission_strict
Members	Read	Member access reviews	Organization membership auditing

Account Permissions (Fine-Grained PAT only)

Permission	Access Level	Purpose
Email addresses	Read	User email verification

GitHub Apps don’t have account-level permissions - they operate at the organization/repository level.

Permissions and Check Coverage

With the Read-only permissions listed above, Prowler can run:

Check Category	Coverage	Notes
Branch protection checks (12 checks)	✅ Full	Signed commits, status checks, PR reviews, etc.
Repository security checks	✅ Full	Secret scanning, Dependabot, SECURITY.md, CODEOWNERS
Organization checks (3 checks)	✅ Full	MFA, repo creation policies, default permissions
Compliance frameworks	✅ Full	CIS GitHub Benchmark and others
Merge settings (delete_branch_on_merge)	⚠️ MANUAL	Requires write permission (see below)

Check that returns MANUAL status with Read-only permissions:

• repository_branch_delete_on_merge_enabled

About Write Permissions

The delete_branch_on_merge setting is only returned by the GitHub API when the token has Administration: Read and write permission.

Granting Write permissions is not recommended under any circumstances:

• Token can modify repository settings
• Token can change branch protection rules
• Violates the principle of least privilege

Recommendation: Accept MANUAL status for this single check rather than granting write access. This limitation applies equally to Fine-Grained PATs and GitHub Apps.

Step-by-Step Permission Assignment

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

Benefits of Fine-Grained Tokens

Fine-Grained Personal Access Tokens are ideal for:

• 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

Create a Fine-Grained Token:

Quick Setup: Use these pre-configured links to create a token with the required permissions already selected:

• Create token for user repositories — scans personal repositories
• Create token for organization scanning — scans organization repositories and settings

For organization scanning, change the Resource Owner to the target organization after the page loads. Organization permissions only appear when an organization is selected.

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.

GitHub shows the token only once. Store it securely.

OAuth App Token

Recommended OAuth App Use Cases:

Use OAuth App Tokens when building applications that need delegated user permissions and explicit user authorization.

OAuth Scopes:

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

Create an OAuth App:

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:

   https://github.com/login/oauth/authorize?client_id={app_id}
   

4. Exchange authorization code for access token:

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

GitHub App Credentials

When to Use GitHub Apps

GitHub Apps are ideal for:

• Organization-wide scanning without tying access to a personal account
• CI/CD pipelines where you need machine identity (not user-based)
• Multi-organization setups with centralized app management
• Audit compliance where you need to track app-level access separately from users

GitHub Apps use the same permission model as Fine-Grained PATs - both provide full access to all Prowler checks.

GitHub App Permissions:

If a GitHub App is required:

Repository permissions:

Permission	Access Level	Purpose	Checks Enabled
Administration	Read	Branch protection, security settings	All branch protection checks, repository_secret_scanning_enabled
Contents	Read	File existence checks	repository_public_has_securitymd_file, repository_has_codeowners_file
Metadata	Read	Basic repository information	All checks (automatically granted)
Dependabot alerts	Read	Dependency vulnerability scanning	repository_dependency_scanning_enabled

Organization permissions:

Permission	Access Level	Purpose	Checks Enabled
Administration	Read	Organization security policies	organization_members_mfa_required, organization_repository_creation_limited, organization_default_repository_permission_strict
Members	Read	Member access reviews	Organization membership auditing

Create a GitHub App:

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

Private Key Security

Store the .pem private key securely. Anyone with this key can authenticate as your GitHub App. Never commit it to version control.

---

Prowler Cloud Authentication

For step-by-step setup instructions for Prowler Cloud, see the Getting Started Guide.

Using Personal Access Token

1. In Prowler Cloud, navigate to Configuration > Providers > Add 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).

For complete step-by-step instructions, see the Getting Started Guide.

---

Prowler CLI Authentication

Authentication Methods

Prowler CLI automatically detects credentials using environment variables in this order:

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

Understanding Scan Scope

What Prowler scans depends on the invocation method:

Command	What Gets Scanned	Organization Checks?
prowler github	All accessible repositories	No
prowler github --repository owner/repo	Single repository	No
prowler github --organization org-name	Organization repos + settings	Yes

Key Point: Scanning user repositories does NOT include organization-level checks. To audit organization MFA, security policies, etc., you must use --organization.

Scan user repositories:

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

Scan organizations:

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

Filter scans:

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

For complete step-by-step instructions, see the Getting Started Guide.

---

Troubleshooting

”Insufficient Permissions” Errors

Symptom: Checks fail or return MANUAL status.

Solutions:

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”

Symptom: Prowler doesn’t find organizations even though you’re a member.

Cause: Fine-Grained Token’s Resource Owner is set to personal account.

Solution: Create a new token with Resource Owner set to the organization and get it approved by an admin.

Organization Checks Return MANUAL

Symptom: Checks like organization_members_mfa_required return MANUAL.

Cause: Token lacks Organization → Administration: Read permission.

Solutions:

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

Symptom: Can’t find Organization permissions section when creating token.

Cause: Resource owner is set to personal account.

Solution: Change Resource owner dropdown to the organization name. Organization permissions section will appear.

Rate Limiting

Symptom: “API rate limit exceeded” errors.

Solutions:

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

Token Expired or Revoked

Symptom: Authentication fails with valid-looking token.

Solutions:

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