Skip to main content

​
All flags

FlagShortDefaultDescription
--path-p.Path to the local repository or directory to scan.
--file-funsetScan a single specific workflow file. Overrides --path.
--git-gunsetGitHub repository to scan. Accepts owner/repo or a full URL. Triggers a git clone --depth 1 into a temp directory.
--orgunsetScan every repository owned by a GitHub org or user, fetching workflows over the API (no cloning). Requires a token. --fail-on applies to the aggregate. See Scan an entire organization.
--output-oconsoleOutput format. One of console, json, or sarif (SARIF 2.1.0 for GitHub code scanning).
--fail-on-sMEDIUMSeverity threshold for exit code 1. One of HIGH, MEDIUM, LOW, INFO, or NONE. See exit codes.
--ruleset-rallWhich rules to apply. all includes best-practice checks; owasp keeps only CICD-SEC-*.
--min-confidenceLOWDrop findings below this confidence: HIGH, MEDIUM, or LOW. Confidence is how sure the check is the finding is real (heuristic checks like typosquat matching or secret-name patterns are MEDIUM), orthogonal to severity (how bad it would be). The default keeps everything.
--personaregularNoise tier. regular runs the high-signal security checks; pedantic adds hygiene nits (missing timeouts, job-level continue-on-error); auditor adds everything, including checks that are informational on their own (self-hosted runner usage).
--keep-tempfalseWhen using -g, keep the temporary clone directory after the scan. Useful for inspecting what was scanned.
--fixfalseAttempt to automatically fix detected issues in place. See Auto-fix. Not supported with -g.
--audit-pinsfalseForce the online supply-chain audits of pinned actions (known-vulnerable, impostor-commit, ref/version-mismatch, typosquat) even when no token is available, accepting GitHub’s 60-requests/hour anonymous limit. You rarely need this: the audits run automatically whenever a token is present.
--offlinefalseDisable every network-backed audit — online pin audits and repository-settings checks — guaranteeing no API traffic. Only the git clone for -g targets remains.

​
Online audits

The online supply-chain audits of pinned actions (known-vulnerable via GHSA, impostor-commit, ref/version-mismatch, typosquat) run automatically when you supply a GitHub token via --github-token, $GITHUB_TOKEN, or $GH_TOKEN — including inside GitHub Actions, where the Pipefort action passes the workflow token for you. Without a token a scan stays fully offline unless you force the audits with --audit-pins. --offline disables them (and the repository-settings audit) unconditionally. A token that gh auth token would return does not auto-enable the audits — a plain local scan never makes API calls just because the GitHub CLI happens to be logged in. It is still used to authenticate audits you enable explicitly. When a gh login is detected and the scanned workflows pin third-party actions, Pipefort prints a one-line hint that the online audits are available (run --audit-pins or set $GITHUB_TOKEN to turn them on); it never makes the calls unprompted.

​
Target selection

The CLI picks a target in this order:
  1. --git owner/repo — shallow-clone, then scan the temp directory.
  2. --file path/to/workflow.yml — scan a single file.
  3. --path . — scan the directory’s .github/workflows/, falling back to walking the whole tree if missing.

​
Exit codes

CodeMeaning
0No findings at or above --fail-on severity.
1At least one finding meets the threshold, or a runtime error (clone failed, parse error, etc.) occurred.
Severity weighting (lowest to highest): INFO < LOW < MEDIUM < HIGH. --fail-on NONE always exits 0 on a clean run, regardless of findings — useful when you want a report without gating.