zuke.tools.security

← Python API reference

@zuke/security 1.0.1: @zuke/security — typed task wrappers for free, open-source security scanners (zizmor, actionlint, gitleaks, osv-scanner, semgrep, trivy) for Zuke builds.

zuke on PyPI ↗ 9 symbols

Symbols

#

ActionlintSettings

class 
class ActionlintSettings(ToolSettings)

Settings for [actionlint](https://github.com/rhysd/actionlint), a linter for GitHub Actions workflow files (and the shell embedded in run: steps).

  • files(*paths: str) -> Self

    Add an explicit workflow file to lint (positional); repeatable.

  • format(template: str) -> Self

    Output format template (-format), e.g. '{{json .}}'.

  • color() -> Self

    Force colored output (-color).

  • no_color() -> Self

    Disable colored output (-no-color).

#

GitleaksDetectSettings

class 
class GitleaksDetectSettings(ToolSettings)

Settings for [gitleaks detect](https://github.com/gitleaks/gitleaks), which scans a directory (and, by default, git history) for committed secrets.

  • source(path: str) -> Self

    Path to scan (--source).

  • config(path: str) -> Self

    Use an explicit gitleaks config (--config).

  • report_format(value: str) -> Self

    Report format (--report-format), e.g. json, sarif, csv.

  • report_path(path: str) -> Self

    Write the report to a file (--report-path).

  • redact() -> Self

    Redact secret values from the output (--redact).

  • no_git() -> Self

    Treat the source as a plain directory, not a git repo (--no-git).

  • verbose() -> Self

    Verbose output (--verbose).

  • log_opts(opts: str) -> Self

    Restrict which commits are scanned, passed straight through to git log (--log-opts). Without this, gitleaks detect walks the whole history reachable from the refs present in the checkout — so on a pull request, where CI typically fetches every branch, a secret-shaped string on an unrelated branch fails the scan and the failure appears on whichever pull request is looked at. Passing a range such as origin/main..HEAD scopes the scan to the commits under review. Has no effect alongside noGit, which makes gitleaks treat the source as a plain directory and ignore history entirely.

#

OsvScannerSettings

class 
class OsvScannerSettings(ToolSettings)

Settings for [osv-scanner](https://github.com/google/osv-scanner), which matches lockfile entries against the OSV vulnerability database.

  • lockfile(path: str) -> Self

    Scan an explicit lockfile (--lockfile); repeatable.

  • paths(*inputs: str) -> Self

    Add a directory to scan (positional); repeatable.

  • format(value: str) -> Self

    Output format (--format), e.g. table, json, sarif.

  • output(path: str) -> Self

    Write the report to a file (--output).

  • recursive() -> Self

    Recurse into subdirectories (--recursive).

#

SecurityTasks

class 
class SecurityTasks

Task functions for running free, open-source security scanners.

  • static async zizmor(ctx: ServiceContext, configure: Callable[[ZizmorSettings], ZizmorSettings] | None=None) -> ExecResult

    Audit GitHub Actions workflows with zizmor.

  • static async actionlint(ctx: ServiceContext, configure: Callable[[ActionlintSettings], ActionlintSettings] | None=None) -> ExecResult

    Lint GitHub Actions workflows with actionlint.

  • static async gitleaks(ctx: ServiceContext, configure: Callable[[GitleaksDetectSettings], GitleaksDetectSettings] | None=None) -> ExecResult

    Scan for committed secrets with gitleaks detect.

  • static async osv_scanner(ctx: ServiceContext, configure: Callable[[OsvScannerSettings], OsvScannerSettings] | None=None) -> ExecResult

    Scan lockfiles for known vulnerabilities with osv-scanner.

  • static async semgrep(ctx: ServiceContext, configure: Callable[[SemgrepScanSettings], SemgrepScanSettings] | None=None) -> ExecResult

    Run source-code static analysis with semgrep scan.

  • static async trivy_fs(ctx: ServiceContext, configure: Callable[[TrivyFsSettings], TrivyFsSettings] | None=None) -> ExecResult

    Scan a filesystem path with trivy fs.

  • static async trivy_config(ctx: ServiceContext, configure: Callable[[TrivyConfigSettings], TrivyConfigSettings] | None=None) -> ExecResult

    Scan configuration / IaC files with trivy config.

#

SemgrepScanSettings

class 
class SemgrepScanSettings(ToolSettings)

Settings for [semgrep scan](https://github.com/semgrep/semgrep), a static analysis engine for source code. Defaults to whatever rules --config selects (e.g. auto or p/ci).

  • config(value: str) -> Self

    Add a rules config (--config), e.g. auto, p/ci; repeatable.

  • paths(*inputs: str) -> Self

    Add a path to scan (positional); repeatable.

  • sarif() -> Self

    Emit SARIF (--sarif).

  • json() -> Self

    Emit JSON (--json).

  • output(path: str) -> Self

    Write output to a file (--output).

  • error() -> Self

    Exit non-zero when findings are present (--error).

#

TrivyConfigSettings

class 
class TrivyConfigSettings(TrivyReportSettings)

Settings for [trivy config](https://github.com/aquasecurity/trivy), which scans IaC / configuration files (Dockerfiles, workflows, etc.) for misconfigurations.

  • target(path: str) -> Self

    The path to scan (default .).

#

TrivyFsSettings

class 
class TrivyFsSettings(TrivyReportSettings)

Settings for [trivy fs](https://github.com/aquasecurity/trivy), which scans a filesystem path for vulnerabilities, secrets, and misconfigurations.

  • target(path: str) -> Self

    The path to scan (default .).

  • scanners(*values: str) -> Self

    Enable specific scanners (--scanners), e.g. vuln, secret, misconfig.

#

TrivyReportSettings

class 
class TrivyReportSettings(ToolSettings)

Shared options for trivy subcommands that produce a report.

  • format(value: str) -> Self

    Report format (--format), e.g. table, json, sarif.

  • output(path: str) -> Self

    Write the report to a file (--output).

  • severity(*values: str) -> Self

    Restrict to these severities (--severity), e.g. HIGH, CRITICAL.

  • exit_code(code: float) -> Self

    Process exit code when issues are found (--exit-code).

#

ZizmorSettings

class 
class ZizmorSettings(ToolSettings)

Settings for [zizmor](https://github.com/woodruffw/zizmor), a static analyzer for GitHub Actions workflows (detects unpinned actions, script injection, over-broad permissions, and more).

  • paths(*inputs: str) -> Self

    Add a workflow file or directory to audit (positional); repeatable.

  • config(path: str) -> Self

    Use an explicit zizmor config file (--config).

  • format(value: str) -> Self

    Output format (--format), e.g. plain, json, or sarif.

  • min_severity(value: str) -> Self

    Only report findings at or above this severity (--min-severity).

  • persona(value: str) -> Self

    Audit persona (--persona), e.g. regular, pedantic, auditor.

  • offline() -> Self

    Do not perform any network access (--offline).