Skip to main content

vulkro gate

Pro

vulkro gate is part of Pro: Release gate (release-gate), fail a build on new findings, with the exit-code contract and the baseline diff. On Free it stops before doing any work, prints what it needs and where to get it, and exits 1. The diff-scoped family is Pro: gate, scan --gate-vs and the ratchet. --fail-on and a plain scan --gate severity exit policy stay Free, because the default preset uses them. See Pricing.

The canonical fail-on-new-only CI gate. vulkro gate scans the working tree AND a baseline git ref, then surfaces only the findings present in the working tree but not the baseline. Exit code 1 fires ONLY on new findings, so the gate never blocks a PR on pre-existing technical debt.

gate vs scan --gate-vs​

Both keep pre-existing debt from failing a PR, but they compare differently:

  • vulkro gate --base <ref> compares the full finding sets across both trees. It catches a new caller that makes an existing sink reachable, because that finding is present in the working tree and absent in the baseline.
  • vulkro scan --gate-vs <ref> filters by changed-line ranges only. It is cheaper, but blind to new findings whose offending line did not itself change (for example a newly added call path into unchanged code).

Use gate for the thorough two-tree comparison; use scan --gate-vs when you want the fast changed-lines lane.

Usage​

vulkro gate --base origin/main
ArgumentDescriptionDefault
PATHPath to the project root..

Flags​

FlagDescription
--base <REF>Git ref to compare against (for example main, origin/main, a SHA). Required unless VULKRO_GATE_BASE is set.
--format <FORMAT>table (default), json, or sarif. JSON includes totals plus the new-findings array; SARIF ships only the new findings (pre-existing findings are deliberately suppressed because they were already in the base ref).

Environment variables​

VariableEffect
VULKRO_GATE_BASEDefault base ref, overridden by --base. Set it once in a CI lane that always compares against origin/main.

Exit codes​

  • 0 no new findings vs the baseline.
  • 1 one or more new findings (the gate is the report).
  • 2 error: bad ref, git not available, or scan failure.

CI snippets​

GitHub Actions:

.github/workflows/gate.yml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # gate needs the base ref in history
- run: curl -fsSL https://dist.vulkro.com/install.sh | bash
- name: Block PR on new findings only
  run: vulkro gate --base origin/${{ github.base_ref }}

GitLab CI:

.gitlab-ci.yml
vulkro-gate:
  stage: test
  script:
    - curl -fsSL https://dist.vulkro.com/install.sh | bash
    - vulkro gate --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"

Command reference​

Generated from vulkro help gate on vulkro 0.26.0. This block is the authoritative flag, usage, and exit-code reference for this command; the prose above is the friendly explanation. Do not edit this block by hand; run npm run docs:cli after a release.

[Pro] Fail a build only on findings that are new compared with a git branch or commit.

Two-tree finding-diff gate. Scans the working tree AND a baseline git ref, then surfaces only the findings present in the working tree but not the baseline. Exit code 1 fires ONLY on new findings, so the gate never blocks a PR on pre-existing technical debt.

This is the canonical "fail-on-new-only" CI gate. The related `scan --gate-vs <ref>` flag filters by changed-line ranges only (cheaper, but blind to new callers that make existing sinks reachable); `gate --base <ref>` catches those because it compares the full finding sets across both trees.

Environment variables: VULKRO_GATE_BASE   Default base ref. Overridden by --base. Useful in CI lanes that always compare against `origin/main`: set it once and forget about it.

Exit codes: 0  no new findings vs the baseline. 1  one or more new findings (the gate is the report). 2  error: bad ref, git not available, scan failure.

Usage: vulkro gate [OPTIONS] [PATH]

Arguments:
  [PATH]
          Path to the project root. Defaults to the current directory
          
          [default: .]

Options:
      --base <REF>
          Git ref to compare against (e.g. `main`, `origin/main`, a SHA). Required unless `VULKRO_GATE_BASE` is set

      --offline
          Hard-disable every outbound network call for this run (sets VULKRO_OFFLINE=1). Blocks the CVE feed, the license heartbeat, the update check, webhooks, and any cloud AI endpoint; a loopback model (http://127.0.0.1, http://localhost) is still allowed. Equivalent to exporting VULKRO_OFFLINE=1, and the flag wins when both are set

      --format <FORMAT>
          Output format: `table` (default), `json`, or `sarif`. JSON includes totals + the new-findings array; SARIF ships only the new findings (the consumer is a PR gate, pre-existing findings are deliberately suppressed because they were already in the base ref)
          
          [default: table]

  -h, --help
          Print help (see a summary with '-h')
Last updated on