DOCSEARCHbyAlgolia
Submit Docs

zizmor

repository·main·Indexed 27 days ago

https://github.com/zizmorcore/zizmor

A static analysis tool for securing CI/CD pipelines, auditing configurations such as GitHub Actions, Dependabot, and pre-commit to prevent template injection, credential leakage, and excessive permissions. The project includes a suite of Rust crates: github-actions-expressions for parsing expressions, github-actions-models and pre-commit-models for data modeling, yamlpath and yamlpatch for format-preserving YAML manipulation, tree-sitter-iter for CST iteration, and zizmor-sarif for SARIF 2.1.0 data models.

Tokens
37.6K
Snippets
96
Records
256
Agent score
91%

What's inside zizmor

  3. Overview of yamlpath

    main
    yamlpath is a tool for format-preserving YAML feature extraction. Unlike standard YAML parsers that are destructive (erasing comments and exact formatting when converting to a document model), yamlpath allows programs to operate on a document view while maintaining the ability to translate actions back to the human-readable YAML input (lines and columns). It is built using tree-sitter and tree-sitter-yaml.

  4. Overview of yamlpatch

    main

    yamlpatch is a Rust library designed for surgical modifications to YAML files while preserving human-readable elements such as comments, indentation, formatting, and style choices (e.g., block vs. flow style).

    Unlike traditional YAML processing that destroys formatting during re-serialization, yamlpatch (which builds on yamlpath) is intended for targeted programmatic changes that are suitable for version control and human review.

  5. Overview of the subfeature crate

    main

    The subfeature crate provides APIs for handling and manipulating subfeatures within the zizmor ecosystem.

    In zizmor terminology, a feature is a syntactically relevant extract of a YAML document. A subfeature is a subset of a feature. This crate allows developers to create subfeatures and perform matching operations against their parent features.

  6. Overview of github-actions-expressions

    main

    github-actions-expressions is a parser and library designed for GitHub Actions expressions. It is a component of the [zizmor] ecosystem.

    Key capabilities include:

    • Faithful parsing of GitHub Actions expressions.
    • Span-aware AST (Abstract Syntax Tree) nodes, which are useful for error reporting and source mapping.
    • Limited support for evaluating constant expressions.

  7. Overview of zizmor

    main

    zizmor is a static analysis tool designed for CI/CD systems. It identifies and helps fix security vulnerabilities in common CI/CD configurations, including GitHub Actions, Dependabot, and pre-commit.

    Key security issues detected include:

    • Template injection vulnerabilities: Preventing attacker-controlled code execution.
    • Credential management: Detecting accidental credential persistence and leakage.
    • Permission scoping: Identifying excessive permission scopes and credential grants to runners.
    • Git security: Finding impostor commits and confusable git references.

  8. Overview of zizmor crates

    main
    The zizmor repository consists of several specialized Rust crates. Depending on your needs, you can use the main CLI for auditing, specialized YAML manipulation tools, or data models for GitHub Actions and pre-commit configurations.

  10. Install zizmor from source

    main

    Warning: Most users should not install directly from the source repository as there are no stability or correctness guarantees. To install the latest unstable version from GitHub using cargo:

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

  11. Ignore findings using `zizmor.yml` configuration

    main

    For managing multiple ignores or entire files, use a zizmor.yml configuration file. You can place it in the project directory for automatic discovery or specify it explicitly using --config or the ZIZMOR_CONFIG environment variable.

    Ignore Syntax: Use the format workflow.yml:line:col to target specific locations. Both line and col are optional and 1-based.

    Example zizmor.yml structure:

    rules:
  template-injection:
    ignore:
      - safe.yml                      # Ignores all findings in this file
      - somewhat-safe.yml:123          # Ignores findings on line 123
      - one-exact-spot.yml:123:456     # Ignores a specific line and column

  12. Add a new audit to zizmor

    main

    To implement a new security audit, follow these steps:

    1. Create the audit file: Define a new file at crates/zizmor/src/audit/my_new_audit.rs.
    2. Define the struct: Create a struct for your audit (e.g., MyNewAudit).
    3. Implement AuditCore: Use the audit_meta! macro to implement AuditCore for your struct.
    4. Implement the Audit trait: Implement the Audit trait for your struct. You can use AuditState (from crates/zizmor/src/state.rs) and github_api::Client (from crates/zizmor/src/github_api.rs) to access necessary data.
    5. Create findings: When creating a Finding, assign the proper location by grabbing it from the relevant Workflow, Job, or Step instance.
    6. Register the audit: Add your new audit to AuditRegistry::default_audits in crates/zizmor/src/registry.rs.
    7. Add integration tests: Add scenarios to the snapshot tests in crates/zizmor/tests/integration/snapshot.rs.
    8. Update documentation: Add documentation for the new audit in docs/audits, ensuring it is added in alphabetical order and includes information about the underlying vulnerability.

    Implementation Tips:

    • Audit provides default implementations. For example, implementing Audit::audit_step allows you to audit individual steps without manually iterating from the workflow downwards.
    • Refer to existing audits in crates/zizmor/src/audit for inspiration.