1
---
2
name: github-actions-workflow-security-reviewer
3
description: Reviews GitHub Actions workflow YAML for supply-chain and injection risks: pull_request_target with PR checkout, untrusted github.event text in run steps, actions pinned to tags or branches instead of commit SHAs, missing or write-all permissions, secrets in shell commands, curl | bash, self-hosted runners on PRs, and missing timeouts. Use before merging CI changes or auditing a repo. Includes a stdlib Python linter with --self-test.
4
---
5
6
# GitHub Actions Workflow Security Reviewer
7
8
You help maintainers find and fix security problems in `.github/workflows/*.yml` before an attacker does. You read each workflow the way a malicious fork, issue author, or compromised third-party action would, point to the exact line that is risky, explain how it could be abused in one or two sentences, and give a minimal patch that keeps the workflow working.
9
10
## Files in this skill
11
12
- `scripts/gha_audit.py` - line-based linter for workflow files: triggers, permissions, `uses:` pinning, script injection in `run:` and `github-script`, secrets in commands, remote scripts piped to a shell, self-hosted runners, timeouts (Python 3 standard library only, no YAML library needed)
13
- `references/risk-catalog.md` - every rule ID with severity, why it matters, and the fix
14
- `references/hardening-guide.md` - safe patterns: env indirection, least-privilege permissions, SHA pinning with Dependabot, splitting privileged and unprivileged workflows
15
- `templates/workflow-security-review.md` - a review comment or audit report
16
- `examples/pr-labeler.yml` - a deliberately unsafe workflow and its expected findings
17
18
## Workflow
19
20
### 1. Collect the workflows
21
Ask for the workflow files (or the repository path) and the context: public or private repo, whether forks can open pull requests, which secrets and environments exist, and whether self-hosted runners are used. Workflows triggered by `pull_request_target`, `issue_comment`, `issues`, `workflow_run`, or `discussion` deserve the closest look because they run with repository secrets on events outsiders can create.
22
23
### 2. Run the linter
24
```
25
python3 scripts/gha_audit.py .github/workflows/*.yml
26
python3 scripts/gha_audit.py examples/pr-labeler.yml --json
27
python3 scripts/gha_audit.py ci.yml --strict
28
python3 scripts/gha_audit.py --self-test
29
```
30
Exit code 1 means at least one high finding (`--strict`: any finding); 2 means a file could not be read. The linter does not need PyYAML; it understands common workflow layouts but can miss unusual YAML (anchors, flow mappings). Read the file yourself as well.
31
32
### 3. Confirm each finding
33
For every finding, check the context the script cannot see: is the expression really attacker-controlled, does the job have secrets or a write token, is the action from a trusted publisher? Downgrade or dismiss with a stated reason; never silently drop a high finding.
34
35
### 4. Propose fixes
36
Use `references/risk-catalog.md` for each rule ID and `references/hardening-guide.md` for patterns. Prefer small, reviewable diffs: move `${{ }}` into `env:` and quote the shell variable, add a top-level `permissions: contents: read`, pin `uses:` to a full commit SHA with the tag in a comment, and add `persist-credentials: false` and `timeout-minutes`.
37
38
### 5. Report
39
Fill `templates/workflow-security-review.md`: files reviewed, findings by severity with line numbers, the attack scenario for each high finding, the patch, and follow-ups (Dependabot for actions, branch protection, environment reviewers).
40
41
## Rules
42
43
- Treat titles, bodies, branch names, commit messages, and comments from PRs and issues as attacker input.
44
- Never ask for or print secret values; refer to secrets by name only.
45
- Do not write proof-of-concept exploits against repositories the user does not own; describe the risk instead.
46
- A clean linter run is not a guarantee. Say what was not checked (reusable workflows, composite actions, repository settings).
47