> ## Documentation Index > Fetch the complete documentation index at: https://docs.prowler.com/llms.txt > Use this file to discover all available pages before exploring further. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback: POST https://docs.prowler.com/feedback ```json { "path": "/user-guide/providers/github/authentication", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # 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**](#fine-grained-personal-access-token-recommended) | Individual users, quick setup | Simple, user-scoped access | | [**GitHub App**](#github-app-credentials) | Organizations, automation, CI/CD | Organization-scoped, no personal account dependency | | [**OAuth App Token**](#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](https://github.com/settings/personal-access-tokens/new?name=Prowler+Security+Scanner\&description=Fine-grained+PAT+for+Prowler+security+scanning\&expires_in=90\&administration=read\&contents=read\&vulnerability_alerts=read\&emails=read) — scans personal repositories * [Create token for organization scanning](https://github.com/settings/personal-access-tokens/new?name=Prowler+Security+Scanner\&description=Fine-grained+PAT+for+Prowler+organization+security+scanning\&expires_in=90\&administration=read\&contents=read\&vulnerability_alerts=read\&emails=read\&organization_administration=read\&members=read) — 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. GitHub Fine-Grained Token Permissions #### 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](/user-guide/providers/github/getting-started-github#prowler-cloudapp). ### 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](/user-guide/providers/github/getting-started-github#prowler-cloudapp). *** ## 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) ```bash theme={null} # 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 ```bash theme={null} # 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:** ```bash theme={null} prowler github prowler github --repository username/my-repo ``` **Scan organizations:** ```bash theme={null} prowler github --organization org-name prowler github --organization org1 --organization org2 ``` **Filter scans:** ```bash theme={null} 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](/user-guide/providers/github/getting-started-github#prowler-cli). *** ## 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](https://docs.github.com/en/rest/authentication) * [Fine-Grained Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) * [GitHub Apps Documentation](https://docs.github.com/en/apps) * [GitHub API Rate Limits](https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api) * [Getting Started Guide](/user-guide/providers/github/getting-started-github)