ActSpect - GitHub Actions Security Scanner

ActSpect is a comprehensive security analysis tool for GitHub Actions workflows and their dependencies. It provides deep supply chain scanning capabilities to identify security vulnerabilities, misconfigurations, and compliance issues in your CI/CD pipelines.

🚀 Features

Advanced Supply Chain Scanning

• Deep Dependency Analysis: Recursively analyze actions and their dependencies to any specified depth
• Multi-Scanner Support: Integrated support for Zizmor and OpenGrep/Semgrep scanners
• Comprehensive Coverage: Scan composite actions, reusable workflows, and Docker actions
• Dependency Visualization: Generate interactive dependency graphs to visualize your supply chain

Security Analysis

• Vulnerability Detection: Identify security issues throughout the entire dependency chain
• Configuration Assessment: Detect misconfigurations and excessive permissions
• Best Practice Validation: Ensure adherence to GitHub Actions security best practices
• Severity-Based Filtering: Focus on issues that matter most with configurable severity levels

Reporting & Visualization

• Multi-Format Reports: Generate both JSON and HTML reports for different use cases
• Interactive HTML Reports: Rich, searchable HTML reports with detailed findings
• Dependency Graphs: Visual representation of your action dependencies
• Consolidated Analysis: Single report combining findings from multiple scanners

📦 Installation

Prerequisites

• Python 3.8 or higher
• Git
• GitHub personal access token

Install ActSpect

pip install actspect

Install Optional Dependencies

For enhanced scanning capabilities:

OpenGrep/Semgrep Scanner

For static analysis scanning, install OpenGrep or Semgrep manually:

Option 1: Install OpenGrep (recommended)

# Download the latest release from GitHub
# Visit: https://github.com/opengrep/opengrep/releases
# Download the appropriate binary for your platform and add it to your PATH

Option 2: Install Semgrep and create OpenGrep alias

pip install semgrep
# Create an alias so ActSpect can find it as 'opengrep'
sudo ln -s $(which semgrep) /usr/local/bin/opengrep

Dependency Graph Generation

# For dependency graph visualization
sudo apt-get install graphviz  # Ubuntu/Debian
brew install graphviz          # macOS

🔧 Quick Start

1. Set up your GitHub token

export GITHUB_TOKEN="your_github_token_here"

2. Basic workflow scan

actspect scan --repo owner/repository

3. Advanced scanning with custom options

actspect scan \
  --repo owner/repository \
  --scanner all \
  --min-severity medium \
  --max-depth 10 \
  --dependency-graph \
  --output-dir ./reports

📋 Usage

Command Line Interface

Scan Command

actspect scan [OPTIONS]

Options:

• --repo, -r: GitHub repository in "owner/repo" format (required)
• --token, -t: GitHub personal access token (or set GITHUB_TOKEN env var)
• --workflow-path: Path to specific workflow file to scan
• --output-dir, -o: Directory to save reports (default: ./actspect_reports)
• --max-depth: Maximum depth for dependency scanning (default: 5)
• --scanner: Scanner to use: zizmor, opengrep, or all (default: all)
• --min-severity: Minimum severity level: critical, high, medium, low (default: low)
• --verbose, -v: Enable verbose output
• --debug, -d: Enable debug mode with extensive logging
• --deep-scan: Enable comprehensive deep scanning
• --dependency-graph: Generate dependency graph visualization

Info Command

actspect info

Display system information and dependency status.

Setup Command

actspect setup [--install-all]

Set up ActSpect and install optional dependencies.

Test Scanner Command

actspect test-scanner [zizmor|semgrep|all]

Test if specific scanners are working correctly.

Configuration Examples

Basic Security Scan

actspect scan --repo myorg/myrepo

Comprehensive Security Audit

actspect scan \
  --repo myorg/myrepo \
  --scanner all \
  --min-severity high \
  --max-depth 15 \
  --dependency-graph \
  --verbose

Focused Critical Issues Scan

actspect scan \
  --repo myorg/myrepo \
  --min-severity critical \
  --scanner zizmor

Specific Workflow Analysis

actspect scan \
  --repo myorg/myrepo \
  --workflow-path .github/workflows/ci.yml \
  --max-depth 8

🔍 Scanning Capabilities

Dependency Types Analyzed

• Standard GitHub Actions: Regular published actions from GitHub Marketplace
• Composite Actions: Actions that combine multiple steps or other actions
• Reusable Workflows: GitHub workflows called by other workflows
• Local Actions: Actions defined within the same repository
• Docker Actions: Actions that run within Docker containers

Security Risks Detected

• Unpinned Dependencies: Actions not pinned to specific commit hashes
• Excessive Permissions: Actions requesting more permissions than necessary
• Command Injection: Potential command injection vulnerabilities
• Code Injection: Possible code injection points in scripts or inputs
• Vulnerable Inputs: Unsafe handling of inputs or environment variables
• Transitive Vulnerabilities: Security issues in nested dependencies
• Configuration Issues: Misconfigurations in workflow and action definitions

Scanner Integration

Zizmor Scanner

• Specialized GitHub Actions security scanner
• Built-in rules for common vulnerabilities
• Fast and accurate analysis
• Default scanner for ActSpect

OpenGrep/Semgrep Scanner

• Advanced static analysis capabilities
• Extensive rule sets for security patterns
• Custom rule support
• Comprehensive code analysis

📊 Report Formats

JSON Reports

Structured data format suitable for:

• Integration with other tools
• Automated processing
• API consumption
• Custom analysis

HTML Reports

Interactive web-based reports featuring:

• Searchable findings
• Severity-based filtering
• Detailed vulnerability descriptions
• Recommendations for remediation
• Visual severity indicators

Dependency Graphs

Visual representations showing:

• Action dependency relationships
• Supply chain complexity
• Potential security bottlenecks
• Circular dependencies

🏗️ Project Structure

ActSpect follows a modular architecture designed for maintainability and extensibility:

ActSpect/
├── README.md                    # Project documentation
├── LICENSE                      # MIT License
├── NOTICE                       # Third-party notices
├── requirements.txt             # Python dependencies  
├── setup.py                     # Package setup configuration
└── ActSpect/                    # Main package directory
    ├── __init__.py              # Package initialization
    ├── constants.py             # Constants and configuration
    ├── logging_config.py        # Logging configuration
    ├── cli/                     # Command-line interface
    │   ├── __init__.py
    │   ├── main.py              # Main CLI entry point
    │   ├── commands.py          # CLI command definitions
    │   └── display.py           # Display logic and UI
    ├── core/                    # Core functionality
    │   ├── __init__.py
    │   ├── github_client.py     # GitHub API client
    │   ├── workflow_parser.py   # Workflow parsing logic
    │   └── action_resolver.py   # Action resolution and dependency analysis
    ├── scanners/                # Security scanners
    │   ├── __init__.py
    │   ├── base.py              # Base scanner abstract class
    │   ├── zizmor.py            # Zizmor scanner implementation
    │   ├── semgrep.py           # Semgrep scanner implementation
    │   └── factory.py           # Scanner factory and management
    ├── reports/                 # Report generation
    │   ├── __init__.py
    │   ├── manager.py           # Report management
    │   └── html_converter.py    # JSON to HTML conversion
    └── utils/                   # Utility modules
        ├── __init__.py
        ├── file_utils.py        # File operations
        ├── path_utils.py        # Path utilities
        ├── system_utils.py      # System operations
        ├── format_utils.py      # Formatting utilities
        └── security_utils.py    # Security-related utilities

Architecture Benefits

• Modular Design: Clear separation of concerns with logical module organization
• Extensible Scanners: Easy to add new security scanners through the factory pattern
• Type Safety: Comprehensive type hints throughout for better IDE support
• Error Handling: Robust error handling with custom exception classes
• Security Focus: Built-in security utilities and secure coding practices

🛡️ Security Best Practices

Action Security

• Pin to Commit Hashes: Always use specific commit hashes instead of version tags
• Minimal Permissions: Use fine-grained permissions instead of write-all
• Input Validation: Validate and sanitize all action inputs
• Secret Management: Properly handle secrets and tokens
• Regular Updates: Keep dependencies updated while maintaining security

Workflow Security

• Least Privilege: Apply principle of least privilege to all permissions
• Environment Isolation: Use appropriate environment protections
• Artifact Security: Secure artifact uploads and downloads
• Branch Protection: Implement proper branch protection rules
• Review Process: Establish code review processes for workflow changes

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Setup

git clone https://github.com/Axonius/ActSpect.git
cd ActSpect
pip install -e ".[dev]"

Code Quality Standards

# Format code
black ActSpect/

# Lint code  
flake8 ActSpect/

# Type checking
mypy ActSpect/

# Run tests
pytest tests/ --cov=ActSpect

Adding New Scanners

1. Create a new scanner class in ActSpect/scanners/
2. Inherit from BaseScanner
3. Implement required methods
4. Register in the scanner factory
5. Add tests and documentation

Contributing Guidelines

• Fork the repository and create a feature branch
• Follow the existing code style and conventions
• Add tests for new functionality
• Update documentation as needed
• Submit a pull request with a clear description

By contributing to ActSpect, you agree that your contributions will be licensed under the MIT License.

📄 License

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

Third-Party Dependencies

ActSpect integrates with and depends on several third-party tools and libraries:

• Zizmor - MIT License - GitHub Actions security scanner
• OpenGrep/Semgrep - LGPL-2.1 License - Static analysis tool
• PyGithub - LGPL-3.0 License - GitHub API library
• Rich - MIT License - Terminal formatting library
• Click - BSD-3-Clause License - Command line interface
• PyYAML - MIT License - YAML parser

See NOTICE file for complete third-party license information.

Commercial Use

ActSpect is freely available for commercial use under the MIT License. No restrictions apply beyond those specified in the license.

Disclaimer

ActSpect is an independent open source project and is not affiliated with or endorsed by GitHub, Inc., Trail of Bits, Semgrep, Inc., or any other third-party organizations whose tools or services may be integrated with or referenced by ActSpect.

GitHub Actions is a trademark of GitHub, Inc.

🆘 Support

• Documentation: Full documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Report security vulnerabilities privately via email
• Community: Join our community discussions for help and feedback

🙏 Acknowledgments

• Zizmor - GitHub Actions security scanner by Trail of Bits
• Semgrep - Static analysis tool by Semgrep, Inc.
• PyGithub - GitHub API library
• Rich - Terminal formatting library
• Click - Command line interface framework

Special thanks to the security research community for their work on GitHub Actions security.

🚧 Roadmap

• Support for GitLab CI/CD pipelines
• Integration with popular CI/CD platforms
• Enhanced rule customization
• Performance optimizations
• Extended reporting formats
• Real-time monitoring capabilities
• IDE integrations and plugins
• Custom scanner plugin system
• SARIF format support
• Integration with security dashboards

📈 Performance & Scalability

ActSpect is designed for efficiency:

• Intelligent Caching: Avoids redundant API calls and processing
• Concurrent Scanning: Parallel processing where possible
• Memory Efficient: Optimized for large dependency trees
• Rate Limiting: Respects GitHub API limits automatically
• Incremental Updates: Smart detection of changes

Contributors

This project is made possible by the amazing people who have shaped it through their code, ideas, and guidance.

• Igor Stepansky - Lead & Primary Contributor
  Created the initial project setup, wrote all core features, and authored documentation.

• Avri Schneider
  Provided initial project code review, quality assurance, and deployment.

• Nissan Itzhakov
  Deploying and maintenance of the project.

• Tomer Mekler
  Advised on project direction, design, and planning.

• Sharon Ohayon
  Project management and team leadership.

• Michael Goberman
  Project management and team leadership.

---

Made with ❤️ for the DevSecOps community

ActSpect helps secure your software supply chain by providing comprehensive visibility into GitHub Actions workflows and their dependencies. Start securing your CI/CD pipelines today!