actionsguard 1.0.0

GitHub Actions security scanner using OpenSSF Scorecard

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

Development Installation (Current Method)

Since ActionsGuard is not yet published to PyPI, install from source:

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

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

# Install dependencies
pip install -r requirements.txt

# Install ActionsGuard in development mode
pip install -e .

# Verify installation
actionsguard --version

Future: Via pip (After PyPI Publication)

pip install actionsguard

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
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip 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: |
    pip install actionsguard
    actionsguard scan --org ${{ github.repository_owner }} --fail-on-critical

GitLab CI

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

Jenkins

stage('Security Scan') {
    steps {
        sh 'pip 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. ActionsGuard Not Found on PyPI

ERROR: Could not find a version that satisfies the requirement actionsguard

Solution: ActionsGuard is not yet published to PyPI. Install from source:

git clone https://github.com/cybrking/actions-guard.git
cd actions-guard
pip install -e .

3. 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)

4. 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

5. 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
pip install -e .

Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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!