github-actions-permission-scope-audit_skill

Overview

This skill audits GitHub Actions workflows to detect over-broad GITHUB_TOKEN permissions and permission-scope drift. It helps enforce least-privilege by flagging missing or risky permission declarations and workflows that escalate token access. Reports are available as human-readable text or machine-friendly JSON for CI gating.

How this skill works

The tool parses workflow YAML files and inspects the permissions block, events, and job-level settings. It flags explicit broad grants (for example write-all or contents: write), workflows lacking an explicit permissions policy, and risky patterns such as pull_request_target workflows with write access. Output includes a ranked list of findings, scores for severity, and optional CI exit behavior when critical issues are found.

When to use it

• During CI pipeline checks to prevent privilege regressions before merge
• When onboarding a security review to inventory workflow token exposure
• As a periodic audit to detect permission-scope drift across repositories
• Before enabling community contributions to ensure workflows use least privilege
• When hardening repositories for compliance or internal policy

Best practices

• Declare explicit minimal permissions in each workflow permissions block
• Avoid granting write scopes to workflows triggered by user-contributed events like pull_request_target
• Use the JSON output mode for automated gating and programmatic policy enforcement
• Run the audit regularly and add findings as actionable items in PR templates
• Tune flags and regex filters to reduce false positives for your repo patterns

Example use cases

• CI pre-merge gate that fails the build when critical over-permission findings exist
• Security sprint to enumerate all workflows with missing permissions statements
• Automated report generation for dev teams showing top risky workflows
• Validating third-party or community-contributed workflows before enabling them
• Scanning archived or backup workflow sets to identify historical permission drift