Skip to content

Usage Recipes🔗

Operating Modes🔗

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

Output formats🔗

zizmor always produces output on stdout.

By default, zizmor produces cargo-style diagnostic output. This output will be colorized by default when sent to a supporting terminal and uncolorized by default when piped to another program. Users can also explicitly disable output colorization by setting NO_COLOR=1 in their environment.

Apart from the default, zizmor supports JSON and SARIF as machine-readable output modes. These can be selected via the --format option:

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

# use the default diagnostic output explicitly
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.

Exit codes🔗

Note

Exit codes 10 and above are not used if --no-exit-codes or --format sarif is passed.

zizmor uses various exit codes to summarize the results of a run:

Code Meaning
0 Successful audit; no findings to report (or SARIF mode enabled).
1 Error during audit; consult output.
10 One or more findings found; highest finding is "unknown" level.
11 One or more findings found; highest finding is "informational" level.
12 One or more findings found; highest finding is "low" level.
13 One or more findings found; highest finding is "medium" level.
14 One or more findings found; highest finding is "high" level.

All other exit codes are currently reserved.

Ignoring results🔗

zizmor's defaults are not always 100% right for every possible use case.

If you find that zizmor produces findings that aren't right for you (and aren't false positives, which should be reported!), then you can choose to selectively ignore results via a zizmor.yml configuration file.

Here's what a zizmor.yml file might look like:

zizmor.yml
rules:
  template-injection:
    ignore:
      - safe.yml
      - somewhat-safe.yml:123
      - one-exact-spot.yml:123:456

Concretely, this zizmor.yml configuration declares three ignore rules, all for the template-injection audit:

  1. Ignore all findings in safe.yml, regardless of line/column location
  2. Ignore any findings in somewhat-safe.yml that occur on line 123
  3. Ignore one finding in one-exact-spot.yml that occurs on line 123, column 456

More generally, the filename ignore syntax is workflow.yml:line:col, where line and col are both optional and 1-based (meaning foo.yml:1:1 is the start of the file, not foo.yml:0:0).

To pass a configuration to zizmor, you can either place zizmor.yml somewhere where zizmor will discover it, or pass it explicitly via the --config argument. With --config, the file can be named anything:

zizmor --config my-zizmor-config.yml /dir/to/audit

See Configuration: rules.<id>.ignore for more details on writing ignore rules.

Integration🔗

Use in GitHub Actions🔗

zizmor is designed to integrate with GitHub Actions. In particular, zizmor --format sarif specifies SARIF as the output format, which GitHub's code scanning feature uses.

You can integrate zizmor into your CI/CD however you please, but one easy way to do it is with a workflow that connects to GitHub's code scanning functionality.

Important

The workflow below performs a SARIF upload, which is available for public repositories and for GitHub Enterprise Cloud organizations that have Advanced Security. If neither of these apply to you, then you can adapt the workflow to emit JSON or diagnostic output via --format json or --format plain respectively.

zizmor.yml
name: GitHub Actions Security Analysis with zizmor 🌈

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["**"]

jobs:
  zizmor:
    name: zizmor latest via Cargo
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      # required for workflows in private repositories
      contents: read
      actions: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Setup Rust
        uses: actions-rust-lang/setup-rust-toolchain@v1
      - name: Get zizmor
        run: cargo install zizmor
      - name: Run zizmor 🌈
        run: zizmor --format sarif . > results.sarif
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # (1)!
      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
          category: zizmor
  1. Optional: Remove the env: block to only run zizmor's offline audits.

For more inspiration, see zizmor's own repository workflow scan, as well as GitHub's example of running ESLint as a security workflow.

Use with pre-commit🔗

zizmor can be used with the pre-commit framework. To do so, add the following to your .pre-commit-config.yaml repos section:

-   repo: https://github.com/woodruffw/zizmor
    rev: v0.3.0 # (1)!
    hooks:
    - id: zizmor
  1. Don't forget to update this version to the latest zizmor release!

This will run zizmor on every commit. If you want to run zizmor only on specific files, you can use the files option:

-   repo:
    ...
    hooks:
    - id: zizmor
      files: ^path/to/audit/.*\.yml$

See pre-commit documentation for more information on how to configure pre-commit.