docs(github): refactor getting started and auth (#8767)

Author: andoniaf

docs/tutorials/github/authentication.md

@@ -1,47 +1,211 @@
-# Github Authentication in Prowler
+# 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)**
-- **OAuth App Token**
-- **GitHub App Credentials**
+- [Personal Access Token (PAT)](./authentication.md#personal-access-token-pat)
+- [OAuth App Token](./authentication.md#oauth-app-token)
+- [GitHub App Credentials](./authentication.md#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.
 
-## Supported Login Methods
+## Personal Access Token (PAT)
 
-Here are the available login methods and their respective flags:
+Personal Access Tokens provide the simplest GitHub authentication method, but it can only access resources owned by a single user or organization.
 
-### Personal Access Token (PAT)
+???+ 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.
 
-Use this method by providing your personal access token directly.
+#### **Option 1: Create a Fine-Grained Personal Access Token (Recommended)**
 
-```console
-prowler github --personal-access-token pat
-```
+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
 
-### OAuth App Token
+2. **Access Developer Settings**
+    - Scroll down the left sidebar
+    - Click "Developer settings"
 
-Authenticate using an OAuth app token.
+3. **Generate Fine-Grained Token**
+    - Click "Personal access tokens"
+    - Select "Fine-grained tokens"
+    - Click "Generate new token"
 
-```console
-prowler github --oauth-app-token oauth_token
-```
+4. **Configure Token Settings**
+    - **Token name**: Give your token a descriptive name (e.g., "Prowler Security Scanner")
+    - **Expiration**: Set an appropriate expiration date (recommended: 90 days or less)
+    - **Repository access**: Choose "All repositories" or "Only select repositories" based on your needs
 
-### GitHub App Credentials
-Use GitHub App credentials by specifying the App ID and the private key path.
+    ???+ 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.
 
-```console
-prowler github --github-app-id app_id --github-app-key-path app_key_path
-```
+5. **Configure Token Permissions**
+    To enable Prowler functionality, configure the following permissions:
 
-### Automatic Login Method Detection
+    - **Repository permissions:**
+        - **Administration**: Read-only access
+        - **Contents**: Read-only access
+        - **Metadata**: Read-only access
+        - **Pull requests**: Read-only access
+
+    - **Organization permissions:**
+        - **Administration**: Read-only access
+        - **Members**: Read-only access
+
+    - **Account permissions:**
+        - **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
+
+![GitHub Personal Access Token Permissions](./img/github-pat-permissions.png)
 
-If no login method is explicitly provided, Prowler will automatically attempt to authenticate using environment variables in the following order of precedence:
+#### **Option 2: Create a Classic Personal Access Token (Not Recommended)**
 
-1. `GITHUB_PERSONAL_ACCESS_TOKEN`
-2. `GITHUB_OAUTH_APP_TOKEN`
-3. `GITHUB_APP_ID` and `GITHUB_APP_KEY` (where the key is the content of the private key file)
+???+ warning "Security Risk"
+    Classic tokens provide broad permissions that may exceed what Prowler actually needs. Use fine-grained tokens instead for better security.
+
+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**: Unique application name
+        - **Homepage URL**: Application homepage
+        - **Webhook URL**: Webhook payload URL (optional)
+        - **Permissions**: Application permission requirements
+
+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
 
-???+ note
-    Ensure the corresponding environment variables are set up before running Prowler for automatic detection when not specifying the login method.