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

---
title: "Getting Started with the GitHub Actions Provider"
---
import { VersionBadge } from "/snippets/version-badge.mdx"

Prowler's GitHub Actions provider enables comprehensive security scanning for GitHub Actions workflows using [zizmor](https://github.com/woodruffw/zizmor). This provider helps identify security vulnerabilities and misconfigurations in CI/CD pipelines.

## Prerequisites

Before using the GitHub Actions provider, zizmor must be installed:

```bash
# Using Cargo (Rust package manager)
cargo install zizmor

# Or download from GitHub releases
# See: https://github.com/woodruffw/zizmor/releases
```

## What Does It Scan?

The GitHub Actions provider scans for:

- **Template injection vulnerabilities** - Prevents attacker-controlled code execution
- **Accidental credential persistence and leakage** - Detects exposed secrets
- **Excessive permission scopes** - Identifies over-privileged workflows
- **Impostor commits and confusable git references** - Spots suspicious references
- **Other GitHub Actions security best practices**

## How It Works

- The GitHub Actions provider scans `.github/workflows/` directories for workflow files.
- Local scans require no authentication.
- Remote repository scans support authentication via GitHub credentials.
  - Check the [GitHub Actions Authentication](/user-guide/providers/github-actions/authentication) page for more details.
- Results are output in the same formats as other Prowler providers (CSV, JSON, HTML, etc.).

## Prowler CLI

<VersionBadge version="5.14.0" />

### Basic Usage

#### Scan Local Workflows

Scan GitHub Actions workflows in the current directory:

```bash
prowler github_actions
```

Scan workflows in a specific directory:

```bash
prowler github_actions --workflow-path /path/to/repository
```

#### Scan Remote Repository

Scan a public GitHub repository:

```bash
prowler github_actions --repository-url https://github.com/user/repo
```

Scan a private repository with authentication:

```bash
prowler github_actions --repository-url https://github.com/user/private-repo \
  --personal-access-token YOUR_TOKEN
```

### Authentication for Private Repositories

Authentication for private repositories can be provided using one of the following methods:

- **Personal Access Token:**
  ```bash
  prowler github_actions --repository-url https://github.com/org/private-repo \
    --personal-access-token YOUR_PAT
  ```
- **OAuth App Token:**
  ```bash
  prowler github_actions --repository-url https://github.com/org/private-repo \
    --oauth-app-token YOUR_OAUTH_TOKEN
  ```
- If not provided via CLI, the following environment variables will be used:
  ```bash
  export GITHUB_PERSONAL_ACCESS_TOKEN=your-token
  # or
  export GITHUB_OAUTH_APP_TOKEN=your-oauth-token

  prowler github_actions --repository-url https://github.com/org/private-repo
  ```

### Excluding Workflows

Exclude specific workflows from the scan results using glob patterns. Prowler filters findings after zizmor completes the scan, matching patterns against both workflow filenames and full paths:

```bash
# Exclude by filename pattern (matches any path)
prowler github_actions --exclude-workflows "test-*.yml" "api-*.yml"

# Exclude by full path pattern
prowler github_actions --exclude-workflows ".github/workflows/experimental-*.yml"

# Exclude entire subdirectories
prowler github_actions --exclude-workflows "**/draft/*.yml"

# Combine multiple pattern types
prowler github_actions \
  --workflow-path .github/workflows \
  --exclude-workflows "test-*.yml" ".github/workflows/experimental/*"
```

<Note>
Patterns can match against either the full path or just the filename:
- `test-*.yml` matches `test-deploy.yml` in any directory
- `.github/workflows/test-*.yml` matches only workflows in that specific directory
- `**/experimental/*.yml` matches workflows in any `experimental` subdirectory
</Note>

### Output Formats

The GitHub Actions provider supports all standard Prowler output formats:

```bash
# Generate HTML, CSV, and JSON reports
prowler github_actions --output-formats html csv json-ocsf

# Custom output directory
prowler github_actions --output-directory ./security-reports

# Custom output filename
prowler github_actions --output-filename github-actions-security-scan
```

### Complete Security Scan with Full Reporting

```bash
prowler github_actions \
  --repository-url https://github.com/my-org/my-repo \
  --personal-access-token $GITHUB_TOKEN \
  --output-formats html csv json-ocsf \
  --output-directory ./security-reports \
  --verbose
```

### Scan Multiple Local Repositories

```bash
for repo in repo1 repo2 repo3; do
  echo "Scanning $repo..."
  prowler github_actions \
    --workflow-path ./$repo \
    --output-filename "scan-$repo" \
    --output-directory ./reports
done
```

## Understanding Results

The scanner identifies issues with different severity levels:

- **CRITICAL/HIGH**: Immediate security risks that should be addressed urgently
- **MEDIUM**: Potential security issues that should be reviewed
- **LOW/INFO**: Best practice violations or informational findings

Each finding includes:
- Description of the security issue
- Affected workflow file and line number
- Remediation recommendations
- Links to relevant documentation

## Integration with CI/CD

Integrate Prowler's GitHub Actions scanning into CI/CD pipelines:

```yaml
name: Security Scan
on:
  push:
    paths:
      - '.github/workflows/**'
  pull_request:
    paths:
      - '.github/workflows/**'

jobs:
  scan-workflows:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install zizmor
        run: |
          cargo install zizmor

      - name: Install Prowler
        run: |
          pip install prowler

      - name: Scan GitHub Actions workflows
        run: |
          prowler github_actions \
            --workflow-path . \
            --output-formats json-ocsf \
            --output-directory ./reports

      - name: Upload scan results
        uses: actions/upload-artifact@v4
        with:
          name: workflow-security-scan
          path: ./reports/
```

## Troubleshooting

### Zizmor Not Found

If an error about zizmor not being found occurs:

1. Ensure zizmor is installed: `which zizmor`
2. Install it using: `cargo install zizmor`
3. Verify it is in your PATH

### Authentication Issues

For private repositories:
- Ensure your token has appropriate permissions (`repo` scope for private repos)
- Check that credentials are correctly set
- Verify the repository URL is correct

### No Findings

If no findings are returned:
- Verify that `.github/workflows/` directory exists
- Check that workflow files have `.yml` or `.yaml` extension
- Run with `--verbose` flag for more details