Flowcheck MCP Server

flowcheck

The default GitHub token can write to your repo. Most workflows never check.

Every GitHub Actions workflow runs with a GITHUB_TOKEN. Repos created with legacy settings give that token write access to nearly everything, and a workflow with no permissions: block inherits whatever the repo default is. Add the trigger shapes that check out pull request code inside a privileged context, secrets passed wholesale to reusable workflows, and caches written by PR runs and read back by release runs, and the workflow file itself becomes the attack surface. The 2025 tj-actions compromise showed how fast a trusted action can turn; "pwn request" write-ups have shown the same for pull_request_target checkouts of PR heads for years.

flowcheck audits every workflow in a repo for least-privilege problems, shows the evidence per file, job, and line, and emits a hardened permissions block per job, inferred from what the job's steps actually do, that you can paste in.

Why this exists

GitHub Actions are the second largest confirmed open source supply-chain attack surface of the last year, behind only npm. The failures are rarely exotic: a missing permissions block, one write-all, a checkout of ${{ github.event.pull_request.head.sha }} under pull_request_target, a self-hosted runner answering PR triggers. All of them are visible in the YAML, statically, before anything runs. flowcheck reads the YAML with a real parser (anchors, merge keys, and block scalars included), never executes anything in the scanned repo, and is callable by agents through MCP so the audit can run inside contribution and release workflows, not just by hand.

Sibling tools ask different questions: actionpin asks whether action refs are pinned to SHAs. flowcheck asks whether permissions and triggers are least-privilege. They share no code.

What it checks

Verdict rules:

• EXPOSED: at least one critical or high finding. Exit code 1.
• REVIEW: only medium or low findings. Exit code 1.
• HARDENED: no findings. Exit code 0.
• Usage errors exit with code 2. That includes a target that is not a directory or a single workflow file: a FIFO, a device, a regular non-workflow file, or a nonexistent path gets a stderr error and no verdict, never a HARDENED over zero files. A reader that closes the output pipe early makes the process exit 141, never 0.

The hardened plan

For every job, flowcheck infers the least privilege its steps need:

audit prints the plan next to the findings; harden prints the per-job blocks plus a top-level union block. Nothing is written to your files: the plan is output, you paste it.

Usage

CLI

# Audit the current repo
npx @reneturcios/flowcheck audit

# Audit another path, machine readable
npx @reneturcios/flowcheck audit ~/src/my-repo --json

# Just the hardening plan
npx @reneturcios/flowcheck harden ~/src/my-repo

Example output:

flowcheck audit .: EXPOSED
  workflows: 2, jobs: 3, findings: 2 (critical: 1, high: 1, medium: 0, low: 0)
  [CRITICAL] .github/workflows/pr.yml:14 FC-PR-HEAD-CHECKOUT (job inspect) Privileged trigger context (pull_request_target) combined with a checkout of the PR head (...)
  [HIGH] .github/workflows/pr.yml:1 FC-NO-TOP-PERMISSIONS No top-level permissions block. ...
EXPOSED: at least one critical or high finding. ...

Auditing needs no credentials and no network. Estate caps are explicit, never silent: at most 500 workflow files per run and 2 MiB per file, and the report's caps field plus a note say when a cap was hit and what was not scanned.

MCP server

Add to your MCP client config:

{
  "mcpServers": {
    "flowcheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/flowcheck", "mcp"]
    }
  }
}

Tools: audit_workflows(path) returns the full audit report as JSON. harden_plan(path) returns the per-job hardened permissions blocks, the top-level union block, and the findings they answer.

Limits, stated plainly

• Permission inference is heuristic. It recognizes the step shapes in the table above plus common gh CLI and script patterns. An unknown third-party action may need more (or less) than the plan suggests; the plan is a starting point a human reviews, not a proof.
• Broad-grant findings are calibrated for invisible consumers: when a job contains a step whose token use cannot be seen in the workflow file (an unknown third-party action, a local composite action, or an actions/github-script step, which is arbitrary JavaScript that often delegates to repo files), the finding is reported at low severity with that caveat instead of medium or high. flowcheck does not follow local composite action files or scripts a step delegates to in v0.1.1.
• The PR-head checkout rule needs an explicit ref expression pointing at the head (pull_request.head, head_ref, workflow_run.head). A checkout with no ref under pull_request_target checks out the base branch, which is the safe shape, and is not flagged. Indirect head checkouts assembled through env vars or outputs are not traced.
• Self-hosted detection sees the literal self-hosted label in runs-on; runner groups named without the label are not recognized.
• Reusable workflow jobs are planned from the call site only; the called workflow's own steps are a separate audit target.
• Matrix-generated jobs are audited as written, once, not per matrix combination.
• The secrets rule counts references under pull_request; it does not try to prove a specific secret reaches a specific step.