A tool for finding security issues in GitHub Actions CI/CD setups.

Quick links:

• Installation
• Quick start guide
• Usage
  • Online and offline use
  • Output formats
  • Audit documentation
• Integration
  • Use in GitHub Actions
• Technical details
• Contributing
• The name?

Go right to the Quickstart or Usage to learn how to use zizmor locally or in your CI/CD.

You can install zizmor from https://crates.io via cargo:

cargo install zizmor

or via Homebrew:

brew install zizmor

You can run zizmor on any file(s) you have locally:

# audit a specific workflow
zizmor my-workflow.yml
# discovers .github/workflows/*.yml automatically
zizmor path/to/repo

By default, zizmor will emit a Rust-style human-friendly findings, e.g.:

error[pull-request-target]: use of fundamentally insecure workflow trigger
  --> /home/william/devel/gha-hazmat/.github/workflows/pull-request-target.yml:20:1
   |
20 | / on:
21 | |   # NOT OK: pull_request_target should almost never be used
22 | |   pull_request_target:
   | |______________________^ triggers include pull_request_target, which is almost always used insecurely
   |

1 findings (0 unknown, 0 informational, 0 low, 0 medium, 1 high)

See the Usage for more examples, including examples of configuration.

Some of zizmor's audits require access to GitHub's API. zizmor will perform online audits by default if the user has a GH_TOKEN specified in their environment. If no GH_TOKEN is present, then zizmor will operate in offline mode by default.

Both of these can be made explicit through their respective command-line flags:

# force offline, even if a GH_TOKEN is present
zizmor --offline workflow.yml

# passing a token explicitly will forcefully enable online mode
zizmor --gh-token ghp-... workflow.yml

zizmor always produces output on stdout. If a terminal is detected, zizmor will default to a human-readable diagnostic output; if no terminal is detected, zizmor will emit JSON.

Output formats can be controlled explicitly via the --format option:

# force diagnostic output, even if not a terminal
zizmor --format plain

# emit zizmor's own JSON format
zizmor --format json

# emit SARIF JSON instead of normal JSON
zizmor --format sarif

See Integration for suggestions on when to use each format.

zizmor is trivial to use within GitHub Actions; you can run it just like you would locally.

zizmor --format sarif specifies SARIF as the output format, which GitHub's code scanning feature also supports.

See GitHub's documentation for advice on how to integrate zizmor's results directly into a repository's scanning setup.

For a specific example, see zizmor's own repository workflow scan. GitHub's example of running ESLint as a security workflow provides additional relevant links.

Forthcoming. See DEVELOPMENT.md in the mean time.

See our contributing guide!

Now you can have beautiful clean workflows!