prowler/docs/user-guide/providers/github/authentication.mdx

---
title: "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 |

<Note>
**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
</Note>


<Warning>
**Classic Personal Access Tokens**

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

</Warning>

### 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` |

<Note>
**Pull requests permission is optional.** It's only needed if you want to audit PR-specific settings beyond what branch protection provides.
</Note>

#### Organization Permissions

Required for scanning organization-level security settings:

<Note>
**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.
</Note>

| 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 |

<Note>
GitHub Apps don't have account-level permissions - they operate at the organization/repository level.
</Note>

### 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`

<Warning>
**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.
</Warning>

### 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:**

<Tip>
**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.
</Tip>

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.

<Warning>
GitHub shows the token only once. Store it securely.

</Warning>

![GitHub Fine-Grained Token Permissions](/images/providers/github-pat-permissions.png)

#### 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

<Note>
**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.
</Note>

**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**

<Warning>
**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.
</Warning>

---

## 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** > **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).

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
# 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
# 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

<Warning>
**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`.

</Warning>

**Scan user repositories:**

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

**Scan organizations:**

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

**Filter scans:**

```bash
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)