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:
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:
- Ignore all findings in
safe.yml
, regardless of line/column location - Ignore any findings in
somewhat-safe.yml
that occur on line 123 - 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:
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.
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
- Optional: Remove the
env:
block to only runzizmor
'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:
- 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:
See pre-commit
documentation for more information on how to configure
pre-commit
.