GitHub Actions Permission Scope Audit

Audit GitHub Actions workflow permission scope drift to enforce least-privilege token access.

Security Scan

The skill's code, instructions, and requirements are coherent with its stated purpose (auditing GitHub Actions workflow permission scopes); it reads local workflow YAML files and emits text/JSON reports and does not request credentials, network access, or unusual system privileges.

Purpose & Capability

Name/description match the shipped script and fixtures. Declared required binaries (bash, python3) are exactly what the SKILL.md and scripts use. No unrelated credentials, config paths, or binaries are requested.

Instruction Scope

SKILL.md instructs the agent to read workflow YAML files, run the bundled shell script, and optionally set environment flags; the script only reads files matched by WORKFLOW_GLOB, extracts events/permission lines via regex, scores findings, and prints text/JSON. It does not send data externally, read unrelated system config, or access secrets.

Install Mechanism

This is an instruction-only skill with no install spec; the only shipped code is a shell script and fixtures. Nothing is downloaded or extracted from external URLs.

Credentials

No required environment variables or credentials are declared; optional ENV inputs are for filtering/reporting and are appropriate for the task. The script does not attempt to read additional env vars or secret files.

Persistence & Privilege

Skill does not request permanent presence (always:false) or modify other skills or system-wide settings. It runs on demand and has no privileged persistence behavior.

Assessment

This skill appears to do exactly what it claims: scan your repository's .github/workflows YAML files for broad GITHUB_TOKEN permissions and emit a ranked report. Before installing/running: (1) review the bundled script if you have strict security controls — it parses YAML using regex rather than a YAML parser so it may mis-detect unusual formatting; (2) run it in the repository root (or set WORKFLOW_GLOB) because it only reads files matched by the glob; (3) it requires bash and python3 on PATH; (4) it does not exfiltrate data or require credentials, but avoid running it against untrusted repositories if you don't want the agent to read those repo files. Overall the skill is internally consistent and proportionate for its stated purpose.

Use this skill to detect over-broad GITHUB_TOKEN permissions and scope drift across GitHub Actions workflows.

What this skill does

• Reads workflow YAML files
• Detects explicit broad permission grants (write-all, contents: write, etc.)
• Flags risky patterns like pull_request_target workflows with write permissions
• Identifies workflows with no explicit permissions policy
• Emits text or JSON for CI triage and policy gates

Inputs

Optional:

• WORKFLOW_GLOB (default: .github/workflows/*.y*ml)
• TOP_N (default: 20)
• OUTPUT_FORMAT (text or json, default: text)
• WARN_SCORE (default: 2)
• CRITICAL_SCORE (default: 5)
• FLAG_MISSING_PERMISSIONS (0 or 1, default: 1)
• FLAG_WRITE_ALL (0 or 1, default: 1)
• FLAG_WRITE_SCOPES (0 or 1, default: 1)
• WORKFLOW_FILE_MATCH / WORKFLOW_FILE_EXCLUDE (regex, optional)
• EVENT_MATCH / EVENT_EXCLUDE (regex, optional)
• PERMISSION_MATCH / PERMISSION_EXCLUDE (regex, optional)
• FAIL_ON_CRITICAL (0 or 1, default: 0)

Run

Text report:

WORKFLOW_GLOB='.github/workflows/*.yml' \
bash skills/github-actions-permission-scope-audit/scripts/permission-scope-audit.sh

JSON output + fail gate:

WORKFLOW_GLOB='.github/workflows/*.yml' \
OUTPUT_FORMAT=json \
FAIL_ON_CRITICAL=1 \
bash skills/github-actions-permission-scope-audit/scripts/permission-scope-audit.sh

Run against bundled fixtures:

WORKFLOW_GLOB='skills/github-actions-permission-scope-audit/fixtures/*.yml' \
bash skills/github-actions-permission-scope-audit/scripts/permission-scope-audit.sh

Output contract

• Exit 0 in report mode (default)
• Exit 1 when FAIL_ON_CRITICAL=1 and one or more workflows are critical
• Text mode prints summary + ranked workflows
• JSON mode prints summary + ranked workflows + critical workflows