4 releases
new 0.1.3 | Oct 29, 2024 |
---|---|
0.1.2 | Oct 29, 2024 |
0.1.1 | Oct 28, 2024 |
0.1.0 | Oct 27, 2024 |
#98 in Web programming
243 downloads per month
135KB
3K
SLoC
zizmor
A tool for finding security issues in GitHub Actions CI/CD setups.
[!IMPORTANT]
zizmor
is currently in beta. You will encounter bugs; please file them!
Quick links:
Go right to the Quickstart or Usage to learn
how to use zizmor
locally or in your CI/CD.
Installation
You can install zizmor
from https://crates.io via cargo
:
cargo install zizmor
or via Homebrew:
brew install zizmor
Quickstart
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.
Usage
Online and offline use
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
. 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.
Integration
Use in GitHub Actions
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.
Technical details
Forthcoming. See DEVELOPMENT.md in the mean time.
Contributing
The name?
Dependencies
~22–35MB
~603K SLoC