zizmor

https://docs.zizmor.sh
Admin
zizmor is a static analysis tool for GitHub Actions designed to find and fix common security issues...
Tokens:68,250
Snippets:630
Trust Score:6.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Output of make site-live

Source: https://docs.zizmor.sh/development

Example output from running make site-live. Shows the server starting and the URL to visit for live changes.

```text
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.40 seconds
INFO    -  [22:18:39] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [22:18:39] Serving on http://127.0.0.1:9999/zizmor/
INFO    -  [22:18:40] Browser connected: http://127.0.0.1:9999/zizmor/development/

```

--------------------------------

### Install zizmor from PyPI with pip, pipx, or uv

Source: https://docs.zizmor.sh/installation

Install zizmor from PyPI using pip, pipx, or uv. The uvx shortcut runs zizmor without a persistent install. Python wheels are provided on a best-effort basis.

```bash
# with pip
pip install zizmor

# with pipx
pipx install zizmor

# with uv
uv tool install zizmor

# or, shortcut:
uvx zizmor --help
```

--------------------------------

### Install cargo-insta for snapshot testing

Source: https://docs.zizmor.sh/development

Installs cargo-insta, the recommended tool for working with insta snapshot tests.

```bash
cargo install --locked cargo-insta
```

--------------------------------

### superfluous-actions after: using rustup toolchain install

Source: https://docs.zizmor.sh/audits

After example for the superfluous-actions audit. Replaces the dtolnay/rust-toolchain action with the equivalent pre-installed runner tool `rustup toolchain install 1.93.1`. This reduces attack surface and supply chain risk.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Install Rust v1.93.1
        run: rustup toolchain install 1.93.1

```

--------------------------------

### Install pinact with Homebrew

Source: https://docs.zizmor.sh/development

Install pinact locally via Homebrew before running `make pinact` to update `uses:` clauses in the documentation.

```bash
brew install pinact

```

--------------------------------

### Install zizmor with Homebrew

Source: https://docs.zizmor.sh/installation

Installs zizmor via Homebrew on macOS or Linux.

```bash
brew install zizmor
```

--------------------------------

### After: lockfile-aware installation with bundle install

Source: https://docs.zizmor.sh/audits

After remediation: uses `bundle install` to install packages from a committed lockfile, avoiding the ad-hoc installation pattern.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v5.0.0
      - run: bundle install

```

--------------------------------

### zizmor configuration discovery examples

Source: https://docs.zizmor.sh/release-notes

Commands that continue to load the same configuration files as before after the configuration discovery refactoring in v1.13.0. These commands are provided as examples of unchanged behavior.

```bash
zizmor .
zizmor .github/

```

--------------------------------

### Check zizmor installation with zizmor -h

Source: https://docs.zizmor.sh/quickstart

Run this command to verify that zizmor is installed correctly. The output should display the help text for zizmor, including its usage and options.

```bash
zizmor -h
```

--------------------------------

### Install zizmor on Chimera Linux with apk

Source: https://docs.zizmor.sh/installation

Installs zizmor on Chimera Linux from the user repository. First enables the user repo if needed, then installs zizmor. This is a community-maintained package.

```bash
# If you don't have the 'user' repo enabled yet, do that first
apk add chimera-repo-user

apk add zizmor
```

--------------------------------

### dependabot-execution remediation: set insecure-external-code-execution to deny

Source: https://docs.zizmor.sh/audits

Before and after examples for the dependabot-execution audit. The before example sets insecure-external-code-execution to allow, which permits code execution during dependency updates. The after example sets it to deny, which is the recommended secure configuration.

```yaml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    insecure-external-code-execution: allow

```

```yaml
version: 2
updates:
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "daily"
    insecure-external-code-execution: deny

```

--------------------------------

### Install zizmor from crates.io with cargo

Source: https://docs.zizmor.sh/installation

Installs zizmor from crates.io with cargo. Passing --locked is strongly recommended to avoid pulling untested dependency versions.

```bash
cargo install --locked zizmor
```

--------------------------------

### Install zizmor from source with cargo

Source: https://docs.zizmor.sh/installation

Installs the latest unstable zizmor directly from the GitHub source repository with cargo. Most ordinary users should not use this method; no stability or correctness guarantees are made.

```bash
cargo install --locked --git https://github.com/zizmorcore/zizmor
```

--------------------------------

### artipacked.yml after remediation

Source: https://docs.zizmor.sh/audits

Example workflow with persist-credentials: false to prevent git credential persistence, as recommended unless credentials are explicitly needed.

```yaml
on: push

jobs:
  artipacked:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
        with:
          persist-credentials: false

```

--------------------------------

### Install zizmor with Nix (with and without flakes)

Source: https://docs.zizmor.sh/installation

Installs zizmor with Nix, either without flakes using nix-env or with flakes using nix profile. This is a community-maintained package.

```bash
# without flakes
nix-env -iA nixos.zizmor

# with flakes
nix profile install nixpkgs#zizmor
```

--------------------------------

### artipacked.yml before remediation

Source: https://docs.zizmor.sh/audits

Example workflow using actions/checkout without disabling credential persistence, which may store credentials on disk and risk exposure.

```yaml
on: push

jobs:
  artipacked:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

```

--------------------------------

### Build website with make site

Source: https://docs.zizmor.sh/development

Build a local copy of the website in the site_html directory. Requires a Python runtime and uv.

```bash
make site

```

--------------------------------

### Show detailed help with zizmor --help

Source: https://docs.zizmor.sh/quickstart

Run this command to see a longer and more detailed version of the help text shown by `zizmor -h`.

```bash
zizmor --help
```

--------------------------------

### cargo install zizmor failure due to yanked dependency

Source: https://docs.zizmor.sh/troubleshooting

Example error output when `cargo install zizmor` fails due to a yanked dependency version. The error indicates that a required version of a dependency is yanked and suggests setting `CARGO_TARGET_DIR` to reuse artifacts.

```text
error: failed to compile `zizmor vA.B.C`, intermediate artifacts can be found at `/SOME/TEMP/DIR`.
To reuse those artifacts with a future compilation, set the environment variable `CARGO_TARGET_DIR` to that path.

Caused by:
  failed to select a version for the requirement `SOMEDEP = "^X.Y.Z"`
    version X.Y.Z is yanked
  location searched: crates.io index
  required by package `zizmor vA.B.C`

```

--------------------------------

### zizmor configuration discovery example

Source: https://docs.zizmor.sh/release-notes

Shows the old and new behavior for discovering configuration files when multiple repositories are passed. The old behavior would discover a config in the current working directory, while the new behavior discovers two different configs, one in each of the repositories.

```bash
# OLD: would discover config in $CWD
# NEW: will discover two different configs, one in each of the repos
zizmor ./repoA ./repoB
```

--------------------------------

### Before: ad-hoc package installation with gem install

Source: https://docs.zizmor.sh/audits

Before remediation: installs a package ad-hoc with `gem install rake`, which is flagged by the audit because it is not managed by a lockfile.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v5.0.0
      - run: gem install rake

```

--------------------------------

### Run live development server with make site-live

Source: https://docs.zizmor.sh/development

Run a development server that monitors for changes to the docs. Useful for live development.

```bash
make site-live

```

--------------------------------

### Install zizmor on Alpine Linux with apk

Source: https://docs.zizmor.sh/installation

Installs zizmor on Alpine Linux with apk. This is a community-maintained package.

```bash
apk add zizmor
```

--------------------------------

### Build developer documentation with cargo doc

Source: https://docs.zizmor.sh/development

Builds the developer-only documentation. Use cargo doc --open to build and open in the local browser.

```bash
# build only
cargo doc

# build and open in the local browser
cargo doc --open
```

--------------------------------

### Install zizmor with conda from conda-forge

Source: https://docs.zizmor.sh/installation

Installs zizmor from Anaconda's conda-forge channel. This is a community-maintained package.

```bash
conda install conda-forge::zizmor
```

--------------------------------

### Run snapshot tests with review shortcut and online tests

Source: https://docs.zizmor.sh/development

Shortcut to run snapshot tests and review in one step. The second command includes online tests.

```bash
cargo insta test --review

# or, with online tests
GH_TOKEN=$(gh auth token) cargo insta test --review --features online-tests
```

--------------------------------

### Manual GitHub Actions workflow with SARIF upload

Source: https://docs.zizmor.sh/integrations

Manual integration example for zizmor in GitHub Actions using --format=sarif and uploading the SARIF file. Requires Advanced Security for SARIF upload; otherwise use --format=github or adapt other formats.

```yaml
name: GitHub Actions Security Analysis with zizmor 🌈

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

env:
  ZIZMOR_VERSION: 1.30.1

permissions: {}

jobs:
  zizmor:
    name: zizmor via PyPI
    runs-on: ubuntu-latest
    permissions:
      security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files.
      contents: read         # Only needed for private repos. Needed to clone the repo.
      actions: read          # Only needed for private repos. Needed for upload-sarif to read workflow run info.
    steps:
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Install the latest version of uv
        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1

      - name: Run zizmor 🌈
        run: uvx "zizmor@${ZIZMOR_VERSION}" --format=sarif . > results.sarif 
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} 

      - name: Upload SARIF file
        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
        with:
          sarif_file: results.sarif
          category: zizmor

```

--------------------------------

### Example workflow for rules.secrets-outside-env.config.allow

Source: https://docs.zizmor.sh/audits

Example workflow for the rules.secrets-outside-env.config.allow rule, showing a job that uses an expression in an environment variable.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "value=${VALUE}"
        env:
          VALUE: ${{ case(foo, '', 'bar') }}

```

--------------------------------

### Generate and review snapshots with cargo insta

Source: https://docs.zizmor.sh/development

Runs all tests generating new snapshots, then reviews them. The shortcut cargo insta test --review combines both steps.

```bash
# run all the tests, generating new snapshots as necessary
cargo insta test

# review the new snapshots generated above
cargo insta review
```

--------------------------------

### Install zizmor with --locked flag

Source: https://docs.zizmor.sh/troubleshooting

Use the `--locked` flag with `cargo install` to force cargo to use the exact dependencies specified in `zizmor`'s `Cargo.lock` file, overriding any yanked versions. This is one of two options to resolve the installation failure.

```bash
cargo install --locked zizmor

```

--------------------------------

### Clone and build zizmor with cargo build

Source: https://docs.zizmor.sh/development

Clones the zizmor repository and builds the project. The cargo run -- --help command is also available, and the resulting binary is at ./target/debug/zizmor.

```bash
git clone https://github.com/zizmorcore/zizmor && cd zizmor
cargo build
# cargo run -- --help also works
./target/debug/zizmor --help
```

--------------------------------

### misfeature.yml after: virtual environment install

Source: https://docs.zizmor.sh/audits

After remediation for the misfeature audit: removes the pip-install input and installs the package in a virtual environment instead.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Setup Python
        uses: actions/setup-python@v6

      - name: Install package
        run: |
          python -m venv .env
          ./.env/bin/pip install .[dev]

```

--------------------------------

### Enable zizmor LSP in Neovim

Source: https://docs.zizmor.sh/integrations

Add this line to your init.lua to enable the zizmor LSP server via nvim-lspconfig. Requires zizmor to be installed separately.

```lua
vim.lsp.enable('zizmor')

```

--------------------------------

### Example of pseudo-ternary with falsy true arm

Source: https://docs.zizmor.sh/audits

Example showing that the pseudo-ternary evaluates to 'bar' when 'foo' is truthy because the true arm '' is falsy.

```yaml
${{ foo && '' || 'bar' }}

```

--------------------------------

### excessive-permissions remediation: set workflow permissions to {} and scope job permissions

Source: https://docs.zizmor.sh/audits

Before and after examples for the excessive-permissions audit. The before example sets workflow-level permissions to id-token: write, which all jobs inherit. The after example sets workflow-level permissions to {} and moves the id-token permission to the publish job, following the principle of least privilege.

```yaml
on:
  release:
    types:
      - published

name: release

permissions:
  id-token: write # trusted publishing + attestations

jobs:
  build:
    name: Build distributions 📦
    runs-on: ubuntu-latest
    steps:
      - # omitted for brevity

  publish:
    name: Publish Python 🐍 distributions 📦 to PyPI
    runs-on: ubuntu-latest
    needs: [build]

    steps:
      - name: Download distributions
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: distributions
          path: dist/

      - name: publish
        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

```

```yaml
on:
  release:
    types:
      - published

name: release

permissions: {}

jobs:
  build:
    name: Build distributions 📦
    runs-on: ubuntu-latest
    steps:
      - # omitted for brevity

  publish:
    name: Publish Python 🐍 distributions 📦 to PyPI
    runs-on: ubuntu-latest
    needs: [build]
    permissions:
      id-token: write # trusted publishing + attestations

    steps:
      - name: Download distributions
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: distributions
          path: dist/

      - name: publish
        uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

```
Tokens:
Raw