prowler/docs/user-guide/providers/github/getting-started-github.mdx

---
title: 'Getting Started with GitHub'
---

This guide covers setting up GitHub security scanning with Prowler. Choose a preferred interface below:

<Note>
**Understanding GitHub Scan Scope**

Prowler can scan either:
- **User Repositories**: All repositories owned by or accessible to a specific GitHub user
- **Organizations**: Repositories and organization-level settings

**Important**: Scanning user repositories does NOT include organization-level checks (MFA requirements, security policies, etc.). To scan organizations, you must explicitly configure them.

</Note>

<CardGroup cols={2}>
  <Card title="Prowler Cloud/App" icon="cloud" href="#prowler-cloudapp">
    Web-based interface with centralized management
  </Card>
  <Card title="Prowler CLI" icon="terminal" href="#prowler-cli">
    Command-line interface for local or automated scans
  </Card>
</CardGroup>

---

## Prowler Cloud/App

<iframe width="560" height="380" src="https://www.youtube-nocookie.com/embed/9ETI84Xpu2g" title="Prowler Cloud Onboarding Github" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen="1"></iframe>

> Walkthrough video onboarding a GitHub Account using GitHub App.

### Prerequisites

Before adding GitHub to Prowler Cloud/App, ensure you have:

1. **GitHub Account Access**
   - Personal GitHub account, OR
   - Admin access to a GitHub organization

2. **Authentication Credentials**
   - Choose one method (see [Authentication Guide](/user-guide/providers/github/authentication)):
     - **Fine-Grained Personal Access Token** (Recommended)
     - OAuth App Token
     - GitHub App Credentials (Not Recommended - limited data access)

### Step 1: Access Prowler Cloud/App

1. Navigate to [Prowler Cloud](https://cloud.prowler.com/) or launch [Prowler App](/user-guide/tutorials/prowler-app)
2. Go to **Configuration** → **Providers**

    ![Providers Page](/images/prowler-app/cloud-providers-page.png)

3. Click **Add Provider**

    ![Add a Provider](/images/prowler-app/add-cloud-provider.png)

4. Select **GitHub**

    ![Select GitHub](/images/providers/select-github.png)

### Step 2: Configure GitHub Account

5. Add the **GitHub Account ID** and an optional alias:
   - **Account ID**: Your GitHub username (e.g., `username`) or organization name (e.g., `org-name`)
   - **Alias** (optional): Friendly name for this connection (e.g., `My Personal Repos` or `Prowler Org`)

    ![Add GitHub Account ID](/images/providers/add-github-account-id.png)

6. Click **Next**

### Step 3: Choose Authentication Method

<Note>
**Recommended: Fine-Grained Personal Access Token**

**Fine-Grained Personal Access Tokens** are strongly recommended because they provide:
- Best data access for comprehensive security scanning
- Granular permission control
- Resource-specific access

**GitHub Apps are not recommended** — they provide the most limited access to GitHub data for security scanning purposes.
</Note>

7. Select your preferred authentication method:

    ![Select auth method](/images/providers/select-auth-method.png)

<Tabs>
  <Tab title="Personal Access Token (Recommended)">
    ![Configure Personal Access Token](/images/providers/auth-pat.png)

    **Recommended method** - provides the best data access for security scanning.

    1. Enter your Fine-Grained Personal Access Token
    2. Click **Verify** to test the connection
    3. Click **Save**

    **Don't have a token yet?** [Create a pre-configured token on GitHub](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) or see [How to create a Personal Access Token](/user-guide/providers/github/authentication#create-a-fine-grained-personal-access-token) for detailed instructions.
  </Tab>

  <Tab title="OAuth App Token">
    ![Configure OAuth App Token](/images/providers/auth-oauth.png)

    For applications requiring user consent and delegated permissions.

    1. Enter your OAuth App Token
    2. Click **Verify** to test the connection
    3. Click **Save**

    **Don't have an OAuth token?** See [How to create an OAuth App Token](/user-guide/providers/github/authentication#oauth-app-token)
  </Tab>

  <Tab title="GitHub App (Not Recommended)">
    ![Configure GitHub App](/images/providers/auth-github-app.png)

    <Warning>
    **Not recommended** - most limited data access. Use only if required by organization policy.
    </Warning>

    1. Enter your GitHub App ID
    2. Upload or paste your Private Key (`.pem` file)
    3. Click **Verify** to test the connection
    4. Click **Save**

    **Don't have a GitHub App?** See [How to create a GitHub App](/user-guide/providers/github/authentication#github-app-credentials)
  </Tab>
</Tabs>


8. Click **Start Scan** to begin your first security assessment

### Step 5: View Results

Once the scan completes, you can:
- View security findings in the dashboard
- Export results in multiple formats (JSON, CSV, HTML)
- Set up continuous scanning schedules
- Configure alerts for critical findings

---

## Prowler CLI

### Prerequisites

Before running Prowler CLI for GitHub, ensure you have:

1. **Prowler Installed**
   ```bash
   # Install via pip
   pip install prowler

   # Or via poetry
   poetry install
   ```

2. **Authentication Credentials**
   - Choose one method (see [Authentication Guide](/user-guide/providers/github/authentication)):
     - **Fine-Grained Personal Access Token** (Recommended)
     - OAuth App Token
     - GitHub App Credentials (Not Recommended)

### Authentication Setup

Prowler CLI automatically detects authentication 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`

<Tabs>
  <Tab title="Environment Variables (Recommended)">
```bash
# Personal Access Token (Recommended)
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxx"

# OAuth App Token
export GITHUB_OAUTH_APP_TOKEN="oauth_token_here"

# GitHub App
export GITHUB_APP_ID="123456"
export GITHUB_APP_KEY="$(cat /path/to/private-key.pem)"
```

Then run Prowler without additional flags:
```bash
prowler github
```
  </Tab>

  <Tab title="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
```
  </Tab>
</Tabs>

**Don't have credentials yet?** See the [Authentication Guide](/user-guide/providers/github/authentication) for step-by-step instructions.

### Scan Scope: Understanding What Gets Scanned

<Warning>
**Distinguishing User Scans from Organization Scans**

The scan scope depends entirely on the Prowler CLI invocation method:

| Command | What Gets Scanned | Organization Checks Included? |
|---------|------------------|-------------------------------|
| `prowler github` | All repositories the token has access to | No |
| `prowler github --repository owner/repo` | Single specified repository | No |
| `prowler github --organization org-name` | Organization repos + org settings | Yes |
| `prowler github --organization org-name --repository owner/repo` | Organization + single repository | Yes |

**Key Points:**
- Scanning **user repositories** does NOT run organization-level checks
- To audit organization MFA, security policies, etc., the `--organization` flag is required
- Members of multiple organizations should specify each one explicitly

</Warning>

### Scanning User Repositories

Scan repositories owned by your user account:

```bash
# Scan all repositories accessible to your token
prowler github

# Scan a specific repository
prowler github --repository username/my-repo

# Scan multiple specific repositories
prowler github --repository username/repo1 --repository username/repo2
```

**What gets scanned:**
- Repository security settings
- Branch protection rules
- Secret scanning configuration
- Dependabot settings
- Organization-level policies (not included)

### Scanning Organizations

Scan organization repositories and organization-level security settings:

```bash
# Scan a single organization
prowler github --organization prowler-cloud

# Scan multiple organizations
prowler github --organization org1 --organization org2

# Scan organization and specific repositories within it
prowler github --organization my-org --repository my-org/critical-repo
```

**What gets scanned:**
- All organization repositories
- Repository security settings
- Organization MFA requirements
- Organization security policies
- Member access and permissions

### Scan Scoping

Scan scoping controls which repositories and organizations Prowler includes in a security assessment. By default, Prowler scans all repositories accessible to the authenticated user or organization. To limit the scan to specific repositories or organizations, use the following flags.

#### Scanning Specific Repositories

To restrict the scan to one or more repositories, use the `--repository` flag followed by the repository name(s) in `owner/repo-name` format:

```console
prowler github --repository owner/repo-name
```

To scan multiple repositories, specify them as space-separated arguments:

```console
prowler github --repository owner/repo-name-1 owner/repo-name-2
```

#### Scanning Specific Organizations

To restrict the scan to one or more organizations or user accounts, use the `--organization` flag:

```console
prowler github --organization my-organization
```

To scan multiple organizations, specify them as space-separated arguments:

```console
prowler github --organization org-1 org-2
```

#### Scanning Specific Repositories Within an Organization

To scan specific repositories within an organization, combine the `--organization` and `--repository` flags. The `--organization` flag qualifies unqualified repository names automatically:

```console
prowler github --organization my-organization --repository my-repo
```

This scans only `my-organization/my-repo`. Fully qualified repository names (`owner/repo-name`) are also supported alongside `--organization`:

```console
prowler github --organization my-org --repository my-repo other-owner/other-repo
```

In this case, `my-repo` is qualified as `my-org/my-repo`, while `other-owner/other-repo` is used as-is.

<Note>
The `--repository` and `--organization` flags can be combined with any authentication method.
</Note>

### Filtering Scans

Customize your scan scope with these options:

```bash
# Run only critical severity checks
prowler github --severity critical

# Run specific checks
prowler github --checks repository_default_branch_protection_enabled,organization_members_mfa_required

# Exclude specific checks
prowler github --excluded-checks repository_archived

# Scan with specific compliance framework
prowler github --compliance cis_1.0_github

# Output results in specific format
prowler github --output-formats json,csv,html
```

### Example Workflows

<Tabs>
  <Tab title="Quick Security Assessment">
```bash
# Scan your personal repositories for critical issues
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
prowler github --severity critical high
```
  </Tab>

  <Tab title="Organization Compliance Audit">
```bash
# Full organization scan with CIS compliance
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
prowler github \
  --organization prowler-cloud \
  --compliance cis_1.0_github \
  --output-formats json,html
```
  </Tab>

  <Tab title="CI/CD Integration">
```bash
# Scan specific repository in CI pipeline
prowler github \
  --personal-access-token "$GITHUB_TOKEN" \
  --repository "$GITHUB_REPOSITORY" \
  --severity critical \
  --output-formats json

# Exit with non-zero if critical findings
if grep -q '"Status": "FAIL".*"Severity": "critical"' prowler-output*.json; then
  echo "Critical security issues found!"
  exit 1
fi
```
  </Tab>

  <Tab title="Multi-Organization Scan">
```bash
# Scan multiple organizations you're part of
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
prowler github \
  --organization org1 \
  --organization org2 \
  --organization org3 \
  --output-formats csv
```
  </Tab>
</Tabs>

### Viewing Prowler CLI Scan Results

Prowler CLI generates results in multiple formats:

```bash
# Results are saved in ./output/ directory by default
ls output/

# View HTML report in browser
open output/prowler-output-*.html

# Parse JSON results with jq
cat output/prowler-output-*.json | jq '.findings[] | select(.Status=="FAIL")'

# Import CSV into spreadsheet
open output/prowler-output-*.csv
```

---

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/user-guide/providers/github/authentication">
    Detailed permissions and token creation
  </Card>
  <Card title="Available Checks" icon="list-check" href="https://hub.prowler.com/github">
    Browse all GitHub security checks
  </Card>
  <Card title="Compliance Frameworks" icon="shield-check" href="https://hub.prowler.com/compliance">
    CIS, NIST, and other frameworks
  </Card>
  <Card title="Troubleshooting" icon="circle-question" href="/user-guide/providers/github/authentication#troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>

## Additional Resources

- [GitHub REST API Documentation](https://docs.github.com/en/rest)
- [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 Security Best Practices](https://docs.github.com/en/code-security)
- [Prowler CLI Reference](/getting-started/basic-usage/prowler-cli)