zizmorcore/zizmor-action

Purpose and Entry Point

zizmor-action is a container-based GitHub Action that runs the external zizmor security auditor against workflow/action inputs. The action contract and runtime launcher are defined by action.yml and action.sh; consumers invoke it through uses: in a GitHub Actions job.

Action Contract

action.yml exposes user-facing inputs for target collection, auditing behavior, filtering, version selection, GitHub token access, output mode, configuration, and no-input handling. Its principal output is output-file, a SARIF path when Advanced Security mode is enabled. Runtime behavior is implemented by action.sh.

Paths: action.yml, action.sh

Execution and Analysis Pipeline

The shell entrypoint reads Action inputs, obtains/runs the selected zizmor version in a container runtime, and forwards collection/audit options such as inputs, persona, online audits, severity/confidence filters, and config path. zizmor is the analysis engine and may inspect local checkout content, remote repositories, and GitHub metadata depending on inputs and enabled audits.

Paths: action.sh, action.yml

Result Delivery Modes

Advanced Security is the default boundary: analysis emits SARIF, exposes its path through output-file, and relies on GitHub code-scanning ingestion. In non-Advanced-Security mode, findings are written to logs; optional GitHub workflow annotations are supported but mutually exclusive with SARIF/Advanced Security. Advanced Security findings do not fail the workflow merely because findings exist; tool/runtime failures remain meaningful failures.

Paths: action.yml, action.sh

External Services, Permissions, and Runtime

Execution requires Docker or a compatible container runtime, making Linux GitHub-hosted runners the intended environment. Online audits use the GitHub REST API through the supplied/default github.token. SARIF integration requires security-events: write; private-repository Advanced Security analysis can additionally require contents: read and actions: read.

Paths: action.yml, README.md

Version Supply and Maintenance

The action supports an exact zizmor version or latest. Version metadata is maintained under support/versions, with a synchronization script that is likely invoked by repository automation. This separates the user-selected tool version from the action’s own implementation.

Paths: support/versions, support/sync-zizmor-versions.sh, .github/workflows/sync-zizmor-versions.yml

Repository Automation Boundary

GitHub workflows validate the action itself and run security scanning/maintenance automation. These workflows are repository-internal consumers rather than the product runtime; the shipped product surface remains the action metadata plus shell launcher.

Paths: .github/workflows/selftest.yml, .github/workflows/zizmor.yml, action.yml