ActionsGuard 🛡️

GitHub Actions Security Scanner - Scan your GitHub Actions workflows for security vulnerabilities using OpenSSF Scorecard.

Features

🔍 Comprehensive Scanning: Scan single repositories, entire organizations, or user accounts
📊 Multiple Report Formats: JSON, HTML, CSV, and Markdown reports
📦 Inventory Tracking: Keep track of all your repos and their security scores over time
🚀 Easy Integration: Use as CLI tool or GitHub Action
⚡ Parallel Execution: Fast scanning with concurrent repository processing
🎯 Focused Checks: Run specific security checks or all OpenSSF Scorecard checks
📈 Beautiful Reports: Visual HTML reports with risk scoring and detailed findings

What It Checks

ActionsGuard leverages OpenSSF Scorecard to check for:

Dangerous Workflows: Detects potentially dangerous patterns in GitHub Actions
Token Permissions: Ensures proper token permission configuration
Pinned Dependencies: Verifies dependencies are pinned to specific versions
And 15+ additional security checks

Installation

Prerequisites

Important: ActionsGuard requires OpenSSF Scorecard to be installed first.

Install Scorecard

Recommended: Using Homebrew (macOS & Linux)

brew install scorecard

Alternative: Download Binary Manually

Click to expand manual installation instructions

# macOS (Apple Silicon)
curl -L -o scorecard https://github.com/ossf/scorecard/releases/latest/download/scorecard_darwin_arm64
chmod +x scorecard
sudo mv scorecard /usr/local/bin/scorecard

# macOS (Intel)
curl -L -o scorecard https://github.com/ossf/scorecard/releases/latest/download/scorecard_darwin_amd64
chmod +x scorecard
sudo mv scorecard /usr/local/bin/scorecard

# Linux
curl -L -o scorecard https://github.com/ossf/scorecard/releases/latest/download/scorecard_linux_amd64
chmod +x scorecard
sudo mv scorecard /usr/local/bin/scorecard

Verify Installation:

scorecard version

Install ActionsGuard

Via pip (Recommended)

pip3 install actionsguard

Development Installation

For contributing or local development:

# Clone the repository
git clone https://github.com/cybrking/actions-guard.git
cd actions-guard

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip3 install -e .

# Verify installation
actionsguard --version

Quick Start

1. Set up GitHub Token

Option A: Fine-grained Token (Recommended)

Create at: https://github.com/settings/personal-access-tokens/new

Permissions needed:

Repository permissions:
- Actions: Read
- Contents: Read
- Metadata: Read
Organization permissions (for org scanning):
- Members: Read

export GITHUB_TOKEN="github_pat_your_token_here"

Option B: Classic Token

Create at: https://github.com/settings/tokens/new

Scopes needed:

repo (for private repos) or public_repo (for public repos only)
read:org (for organization scanning)

export GITHUB_TOKEN="ghp_your_token_here"

⚠️ Important for Private Repositories:

If you're scanning your own private repos, you MUST use repo scope (not just public_repo). If you see "0 repositories found", your token likely doesn't have the right permissions.

Quick test:

# Check if your token can see your repos
actionsguard debug --user your-username

The debug command will:

Show which user you're authenticated as
Display your token scopes
List all repositories your token can see
Explain why repos might be filtered out

2. Scan a Repository

actionsguard scan --repo owner/repository

3. Scan an Organization or User Account

# Scan an entire organization
actionsguard scan --org your-organization

# Scan a user account (e.g., your personal repos)
actionsguard scan --user cybrking

Usage

CLI Examples

Basic Scanning

# Scan a single repository
actionsguard scan --repo kubernetes/kubernetes

# Scan entire organization
actionsguard scan --org my-org

# Scan a user account (personal repos)
actionsguard scan --user your-user

# Scan with custom token
actionsguard scan --repo owner/repo --token ghp_xxxxxxxxxxxx

Advanced Filtering

# Exclude specific repositories
actionsguard scan --org my-org --exclude repo1,repo2
actionsguard scan --user your-user --exclude forked-repo

# Only scan specific repositories
actionsguard scan --org my-org --only important-repo,critical-repo
actionsguard scan --user your-user --only my-critical-project

# Run specific security checks
actionsguard scan --org my-org --checks Dangerous-Workflow,Token-Permissions

# Run all Scorecard checks
actionsguard scan --org my-org --all-checks

Custom Output

# Change output directory
actionsguard scan --org my-org --output ./security-reports

# Generate specific report formats
actionsguard scan --org my-org --format json,html

# Fail on critical issues (useful for CI/CD)
actionsguard scan --org my-org --fail-on-critical

Parallel Scanning

# Adjust parallel scan workers (default: 5)
actionsguard scan --org my-org --parallel 10

GitHub Action Usage

Add ActionsGuard to your workflow:

name: Security Scan

on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  workflow_dispatch:

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Run ActionsGuard
        uses: your-username/actionsguard@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          org-name: my-organization
          fail-on-critical: true

      - name: Upload Reports
        uses: actions/upload-artifact@v3
        with:
          name: security-reports
          path: reports/

Action Inputs

Input	Description	Required	Default
`github-token`	GitHub token for API access	Yes	-
`org-name`	Organization to scan	No	Current repo org
`repo-name`	Single repository to scan	No	-
`exclude-repos`	Comma-separated repos to exclude	No	-
`only-repos`	Only scan these repos	No	-
`checks`	Specific checks to run	No	`Dangerous-Workflow,Token-Permissions,Pinned-Dependencies`
`all-checks`	Run all checks	No	`false`
`output-format`	Report formats	No	`html,json,csv,markdown`
`fail-on-critical`	Fail if critical issues found	No	`false`

Action Outputs

Output	Description
`reports-path`	Path to generated reports
`critical-count`	Number of critical issues
`overall-score`	Average security score
`summary`	JSON scan summary

Report Formats

HTML Report

Beautiful, interactive HTML report with:

Executive summary with metrics
Color-coded risk levels
Collapsible sections for easy navigation
Direct links to documentation
Mobile-responsive design

JSON Report

Machine-readable JSON with complete scan data:

{
  "total_repos": 50,
  "successful_scans": 48,
  "failed_scans": 2,
  "average_score": 7.2,
  "critical_count": 3,
  "results": [...]
}

CSV Report

Spreadsheet-compatible format for analysis in Excel or Google Sheets:

Repository,URL,Score,Risk Level,Critical Issues,High Issues,...
owner/repo1,https://...,6.5,MEDIUM,0,2,...

Markdown Report

GitHub-flavored markdown with emojis and collapsible sections, perfect for:

GitHub Issues
Pull Request comments
Documentation

Configuration

Environment Variables

GITHUB_TOKEN: GitHub personal access token
ACTIONSGUARD_OUTPUT_DIR: Default output directory
ACTIONSGUARD_CHECKS: Default checks to run

Exit Codes

0: Success, no critical issues
1: Critical issues found (with --fail-on-critical)
2: Error during execution

Development

Setup

# Clone repository
git clone https://github.com/cybrking/actions-guard.git
cd actions-guard

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip3 install -e ".[dev]"

Running Tests

pytest tests/ -v --cov=actionsguard

Code Quality

# Format code
black actionsguard/ tests/

# Lint
flake8 actionsguard/ tests/

# Type checking
mypy actionsguard/

CI/CD Integration

GitHub Actions

- name: Security Scan
  run: |
    pip3 install actionsguard
    actionsguard scan --org ${{ github.repository_owner }} --fail-on-critical

GitLab CI

security_scan:
  script:
    - pip3 install actionsguard
    - actionsguard scan --org my-org --fail-on-critical
  artifacts:
    paths:
      - reports/

Jenkins

stage('Security Scan') {
    steps {
        sh 'pip3 install actionsguard'
        sh 'actionsguard scan --org my-org --fail-on-critical'
        publishHTML([
            reportDir: 'reports',
            reportFiles: 'report.html',
            reportName: 'Security Report'
        ])
    }
}

Troubleshooting

For detailed troubleshooting guides, see:

Token Issues: docs/TROUBLESHOOTING_TOKEN.md
General Guide: docs/TOKEN_GUIDE.md

Common Issues

1. Scorecard Command Not Found

Error: OpenSSF Scorecard not found

Solution: Install scorecard using Homebrew:

brew install scorecard

# Verify installation
scorecard version

If you don't have Homebrew, install it from https://brew.sh or see the manual installation instructions in the Prerequisites section above.

2. GitHub API Rate Limit

Error: GitHub API rate limit exceeded

Solution:

Wait for rate limit reset (check: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit)
Use a different token
Authenticated requests have higher limits (5000/hour vs 60/hour)

3. Organization Access Denied

Error: No permission to access organization

Solution:

For Fine-grained tokens: Ensure "Members: Read" permission is granted under Organization permissions
For Classic tokens: Ensure your token has the read:org scope
Verify you're a member of the organization or have appropriate access

4. Python Project Not Found

ERROR: file:///path does not appear to be a Python project

Solution: Make sure you're in the correct directory (should contain setup.py and pyproject.toml):

cd actions-guard  # Navigate to the cloned repository
pip3 install -e .

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

OpenSSF Scorecard - The security checks engine
PyGithub - GitHub API wrapper
Click - CLI framework
Rich - Terminal formatting

Roadmap

SARIF output for GitHub Security tab
Comparison mode for regression detection
Auto-create GitHub Issues for critical findings
Custom security check plugins
Web UI for report visualization
Integration with more CI/CD platforms

Made with ❤️ by Travis Felder

If you find ActionsGuard useful, please consider giving it a ⭐ on GitHub!

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
.github-action		.github-action
.github		.github
actionsguard		actionsguard
docs		docs
examples		examples
scripts		scripts
tests		tests
.actionsguard.example.json		.actionsguard.example.json
.actionsguard.example.yml		.actionsguard.example.yml
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
QUICKSTART.md		QUICKSTART.md
README.md		README.md
RELEASING.md		RELEASING.md
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
test_output.txt		test_output.txt

Folders and files

Latest commit

History

Repository files navigation

ActionsGuard 🛡️

Features

What It Checks

Installation

Prerequisites

Install Scorecard

Install ActionsGuard

Via pip (Recommended)

Development Installation

Quick Start

1. Set up GitHub Token

2. Scan a Repository

3. Scan an Organization or User Account

Usage

CLI Examples

Basic Scanning

Advanced Filtering

Custom Output

Parallel Scanning

GitHub Action Usage

Action Inputs

Action Outputs

Report Formats

HTML Report

JSON Report

CSV Report

Markdown Report

Configuration

Environment Variables

Exit Codes

Development

Setup

Running Tests

Code Quality

CI/CD Integration

GitHub Actions

GitLab CI

Jenkins

Troubleshooting

Common Issues

Contributing

License

Acknowledgments

Roadmap

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages