mirror of
https://github.com/prowler-cloud/prowler.git
synced 2026-03-22 03:08:23 +00:00
232 lines
9.3 KiB
Plaintext
232 lines
9.3 KiB
Plaintext
---
|
|
title: 'GitHub Authentication in Prowler'
|
|
---
|
|
|
|
Prowler supports multiple methods to [authenticate with GitHub](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api). These include:
|
|
|
|
- [Personal Access Token (PAT)](/user-guide/providers/github/authentication#personal-access-token-pat)
|
|
- [OAuth App Token](/user-guide/providers/github/authentication#oauth-app-token)
|
|
- [GitHub App Credentials](/user-guide/providers/github/authentication#github-app-credentials)
|
|
|
|
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.
|
|
|
|
<Warning>
|
|
**Classic Tokens Deprecated**
|
|
|
|
GitHub 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.
|
|
|
|
</Warning>
|
|
#### **Option 1: Create a Fine-Grained Personal Access Token (Recommended)**
|
|
|
|
1. **Navigate to GitHub Settings**
|
|
- Open [GitHub](https://github.com) 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")
|
|
- **Resource owner**: Select the account that owns the resources to scan — either a personal account or a specific organization
|
|
- **Expiration**: Set an appropriate expiration date (recommended: 90 days or less)
|
|
- **Repository access**: Choose "All repositories" or "Only select repositories" based on your needs
|
|
|
|
<Note>
|
|
**Public repositories**
|
|
|
|
Even if you select 'Only select repositories', the token will have access to the public repositories that you own or are a member of.
|
|
|
|
</Note>
|
|
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** (available when an organization is selected as Resource Owner):
|
|
- **Administration**: Read-only access
|
|
- **Members**: Read-only access
|
|
|
|
- **Account permissions** (available when a personal account is selected as Resource Owner):
|
|
- **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
|
|
|
|
|
|
|
|
#### **Option 2: Create a Classic Personal Access Token (Not Recommended)**
|
|
|
|
<Warning>
|
|
**Security Risk**
|
|
|
|
Classic tokens provide broad permissions that may exceed what Prowler actually needs. Use fine-grained tokens instead for better security.
|
|
|
|
</Warning>
|
|
1. **Navigate to GitHub Settings**
|
|
- Open [GitHub](https://github.com) 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)
|
|
|
|
<Note>
|
|
**About Homepage URL and Webhooks**
|
|
|
|
The 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.
|
|
</Note>
|
|
|
|
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
|
|
|
|
5. **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
|