gha-audit
Scan .github/workflows/*.yml for known GitHub Actions supply-chain and
CI security misconfigurations, before they become an incident.
pip install gha-audit
gha-audit .
What it catches
| Check | Severity | Real-world pattern |
|---|---|---|
unpinned-action |
warn | uses: owner/repo@main (or any tag) instead of a full commit SHA. A mutable ref can be repointed to run different code without a corresponding change in your repo to review — this is exactly how the tj-actions/changed-files compromise played out in 2025. |
pull-request-target-checkout |
error | A workflow triggers on pull_request_target (runs with your repo's secrets and write token) and checks out the pull request's own head. A fork's PR can then run its own code with your secrets — the canonical "pwn request" pattern. |
script-injection |
error | A run: step interpolates ${{ github.event.issue.title }} (or PR title/body, comment body, github.head_ref, ...) directly into the shell command. These values are attacker-controlled and are substituted as raw text before the shell runs — arbitrary shell input is possible. |
broad-permissions |
warn | Top-level permissions: write-all. GitHub's own hardening guide recommends the opposite: grant only the specific scopes each job needs. |
All four are static, deterministic checks with no network access beyond
reading files already in your checkout — gha-audit never executes or
fetches the actions it inspects.
Usage
gha-audit . # scan the current repo, human-readable output
gha-audit path/to/repo # scan a different path
gha-audit --json . # machine-readable output
gha-audit --strict . # also fail (non-zero exit) on 'warn' findings, not just 'error'
Exit code is 0 when nothing is found (or only warn-level findings
without --strict), 1 when an error-level finding exists.
Accuracy
Measured against a labelled fixture corpus (tests/test_accuracy.py),
each fixture isolated to exercise exactly one check:
- Recall: 100.00% (8/8 known-vulnerable fixtures detected)
- False-positive rate: 0.00% (0/7 known-safe fixtures flagged)
Numbers are transcribed from the test harness's own output, not narrated.
What it doesn't do (yet)
- Trigger-aware permissions analysis (e.g. flagging
contents: writespecifically when combined withpull_request_target) — only the unambiguouswrite-allcase is checked today. - Traversal into reusable/composite workflows (
workflow_call). - Pinning checks for
docker://actions.
License
MIT. Author: HiroCheck.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file gha_audit-0.1.0.tar.gz.
File metadata
- Download URL: gha_audit-0.1.0.tar.gz
- Upload date:
- Size: 11.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0122baf4e7b8abfd7c4d1df3695ef9fcdc435d6c19cd6e735d2d32cbf98eb059
|
|
| MD5 |
008ab82f18b7eba9b99efd96c66acf77
|
|
| BLAKE2b-256 |
6cbdf771c3f28e29919847b917fc3363a3405ca2f8113164a2d7eefa5b4d681e
|
File details
Details for the file gha_audit-0.1.0-py3-none-any.whl.
File metadata
- Download URL: gha_audit-0.1.0-py3-none-any.whl
- Upload date:
- Size: 11.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.13.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
0afe046bf1e5726c3fdbddb13050795719d8db4b404834133c85e9b455956b4c
|
|
| MD5 |
6bb8296c0a2e7bac1a073df12cbf0685
|
|
| BLAKE2b-256 |
e3e0e469f66b77e473f30d3a9088bfecc1b6a378ff0d15a85f7ad85b5133c680
|
