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

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 supports SARIF as an 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.

Forthcoming. See DEVELOPMENT.md in the mean time.

See our contributing guide!

Now you can have beautiful clean workflows!