QualityGate

The tenant’s quality gate: the checks every vulnetix scan in CI must pass. When a check is set here it overrides the matching scan flag; a check left out leaves the flag in charge. One per tenant.

One per tenant, so metadata.name is always default. Each spec field is optional: a field you leave out leaves the matching vulnetix scan flag in charge. A field you set overrides that flag for every authenticated scan in the organization. The engine merges: applying a document changes only the fields it sets.

apiVersion	vulnetix.com/v1
kind	QualityGate
Group	Scanners and gates
Status	Served. The config engine plans and applies it.
Objects per tenant	one (metadata.name: default)
Token and role	An owner or admin session, or a vmt_ config management token with the owner or admin role that lists QualityGate in its kinds. See Management tokens.
Terraform resource	vulnetix_quality_gate, imported by name (see Terraform and OpenTofu)
CLI	vulnetix config apply, CLI v3.153.0 and later.
Pinned schema	v1.15.0/QualityGate.schema.json
Newest schema	latest/QualityGate.schema.json
First released in	v1.0.0
Print the built-in copy	vulnetix config schema QualityGate

Minimal

Only the fields the kind requires. From examples/QualityGate/minimal.yaml.

YAML

# yaml-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/QualityGate.schema.json
apiVersion: vulnetix.com/v1
kind: QualityGate
metadata:
  name: default
spec: {}

HCL (resource vulnetix_quality_gate)

# Only the arguments the kind requires. From config-schemas examples/QualityGate/minimal.yaml.

resource "vulnetix_quality_gate" "default" {
}

CLI (applies it)

export VULNETIX_CONFIG_TOKEN=vmt_...   # a config management token
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/QualityGate.schema.json
apiVersion: vulnetix.com/v1
kind: QualityGate
metadata:
  name: default
spec: {}
EOF

Advanced

Every field the kind supports, with a when expression where it takes one. From examples/QualityGate/advanced.yaml.

YAML

# yaml-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/QualityGate.schema.json
apiVersion: vulnetix.com/v1
kind: QualityGate
metadata:
  name: default
  labels:
    team: platform-security
  annotations:
    ticket: https://jira.example.com/browse/SEC-2212
spec:
  severity: high
  exploits: active
  blockMalware: true
  blockUnpinned: true
  cooldownDays: 7
  versionLag: 1
  eol:
    block: true
    severities:
      nextQuarter: skip
      thisQuarter: low
      within30Days: high
      retired: critical
  scaAutofix:
    strategy: stable
    maxMajorBump: 1

HCL (resource vulnetix_quality_gate)

# Every argument the kind supports. From config-schemas examples/QualityGate/advanced.yaml.

resource "vulnetix_quality_gate" "default" {
  block_malware  = true
  block_unpinned = true
  cooldown_days  = 7
  eol = {
    block = true
    severities = {
      next_quarter   = "skip"
      retired        = "critical"
      this_quarter   = "low"
      within_30_days = "high"
    }
  }
  exploits = "active"
  sca_autofix = {
    max_major_bump = 1
    strategy       = "stable"
  }
  severity    = "high"
  version_lag = 1
  labels = {
    team = "platform-security"
  }
  annotations = {
    ticket = "https://jira.example.com/browse/SEC-2212"
  }
}

CLI (applies it)

export VULNETIX_CONFIG_TOKEN=vmt_...   # a config management token
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/QualityGate.schema.json
apiVersion: vulnetix.com/v1
kind: QualityGate
metadata:
  name: default
  labels:
    team: platform-security
  annotations:
    ticket: https://jira.example.com/browse/SEC-2212
spec:
  severity: high
  exploits: active
  blockMalware: true
  blockUnpinned: true
  cooldownDays: 7
  versionLag: 1
  eol:
    block: true
    severities:
      nextQuarter: skip
      thisQuarter: low
      within30Days: high
      retired: critical
  scaAutofix:
    strategy: stable
    maxMajorBump: 1
EOF

Fields

Paths use dots for nesting and [] for the items of a list. Required means required whenever the parent object is present. A default is what the server uses when the field is left out.

Field	Type	Required	Default	Allowed values	Description
apiVersion	string	yes		exactly vulnetix.com/v1	The document format version. Every kind in this release is vulnetix.com/v1.
kind	string	yes		exactly QualityGate	Always QualityGate.
metadata	object	yes		no other keys	Metadata for a kind the tenant has exactly one of. The name is fixed to default.
metadata.name	string	yes		exactly default; pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$	The object’s name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name.
metadata.org	string	no		format uuid	The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant.
metadata.labels	object	no		map of string to string (length 0 to 256); keys match ^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$	Free key/value labels. Stored with the object, never interpreted by the server.
metadata.annotations	object	no		map of string to string (length 0 to 4096)	Free key/value notes for people and tools, such as a ticket link.
spec	object	yes		no other keys	The gate settings. Every field is optional.
spec.severity	string	no		low, medium, high, critical	Fail on any affected vulnerability at or above this severity. Overrides –severity.
spec.exploits	string	no		poc, active, weaponized	Fail on a vulnerability with an exploit at or beyond this maturity. Overrides –exploits.
spec.blockMalware	boolean	no			Fail when a dependency is known malware. Overrides –block-malware.
spec.blockUnpinned	boolean	no			Fail on a dependency declared without a pinned version. Overrides –block-unpinned.
spec.cooldownDays	integer	no		>= 0	Fail on a dependency version published fewer than this many days ago. Overrides –cooldown.
spec.versionLag	integer	no		>= 0	Fail on a dependency whose installed version is among this many most recently published versions of its package: 1 fails on the newest release, 3 on any of the three newest. It holds back releases too fresh to trust, and is not a check for being out of date. 0 turns it off. Overrides –version-lag.
spec.eol	object	no		no other keys	End-of-life policy. A dependency whose product reaches end of life inside a horizon is reported at that horizon’s severity; skip reports nothing for that horizon.
spec.eol.block	boolean	no			Fail the scan on end-of-life dependencies. Overrides –block-eol. It decides only whether the CLI fails: once a tenant has any stored quality gate, the server writes an end-of-life finding at the horizon severity for every scanned dependency that reaches end of life inside a horizon not set to skip, whatever this says. The CLI reads the horizon severities only when this, or –block-eol, is true.
spec.eol.severities	object	no		no other keys	The severity given to a dependency by how close its end of life is. skip ignores that horizon.
spec.eol.severities.nextQuarter	string	no	low	skip, low, medium, high, critical	Severity for a dependency whose end of life falls in the next calendar quarter.
spec.eol.severities.thisQuarter	string	no	medium	skip, low, medium, high, critical	Severity for a dependency whose end of life falls in the current calendar quarter.
spec.eol.severities.within30Days	string	no	high	skip, low, medium, high, critical	Severity for a dependency whose end of life is within the next 30 days.
spec.eol.severities.retired	string	no	critical	skip, low, medium, high, critical	Severity for a dependency already past its end of life.
spec.scaAutofix	object	no		no other keys	How vulnetix fix and scan –sca-autofix choose a target version.
spec.scaAutofix.strategy	string	no		latest, safest, stable, rolling	latest: the newest release. safest: the release with the fewest known vulnerabilities. stable: the newest release past its cooldown. rolling: the newest release that is not malware, known vulnerabilities allowed.
spec.scaAutofix.maxMajorBump	integer	no		>= 0	The most major versions a fix may cross: 0 keeps fixes within the current major, N allows up to N. Any whole number from 0 up, with no upper limit. The –sca-autofix-max-major-bump flag also takes a negative number for no limit, but the gate cannot store one, and a value set here overrides the flag, so a tenant that wants no limit leaves this out.

Applying this kind

• Command. vulnetix config apply -f <file>; the CLI line above says from which release. Plan first with vulnetix config plan: it shows each object as create, update, delete or no change, with a planHash that apply then holds to. Apply writes in one transaction.
• Manager. Each object records the manager that applied it (terraform, console or gitops:<repo>). --prune deletes only objects its own manager owns. See The manager and the config engine.
• Status. Applied, Unchanged or Deleted, with no other status fields. The phases the engine reports are explained under status phases.
• Singleton. There is one per tenant, and its name is always default.

Imperative equivalents

The same values can also be set with the imperative commands, now deprecated aliases that send a QualityGate document to the engine as manager console. Each field maps to one flag:

Field	Command and flag	Scan flag it overrides
spec.severity	vulnetix config set quality-gate --severity	--severity
spec.exploits	vulnetix config set quality-gate --exploits	--exploits
spec.blockMalware	vulnetix config set quality-gate --block-malware	--block-malware
spec.blockUnpinned	vulnetix config set quality-gate --block-unpinned	--block-unpinned
spec.cooldownDays	vulnetix config set quality-gate --cooldown	--cooldown
spec.versionLag	vulnetix config set quality-gate --version-lag	--version-lag
spec.eol.block	vulnetix config set quality-gate --block-eol	--block-eol
spec.eol.severities.nextQuarter	vulnetix config set eol-policy --next-quarter-severity	none
spec.eol.severities.thisQuarter	vulnetix config set eol-policy --this-quarter-severity	none
spec.eol.severities.within30Days	vulnetix config set eol-policy --within-30-days-severity	none
spec.eol.severities.retired	vulnetix config set eol-policy --retired-severity	none
spec.scaAutofix.strategy	vulnetix config set quality-gate --sca-autofix-strategy	--sca-autofix-strategy
spec.scaAutofix.maxMajorBump	vulnetix config set quality-gate --sca-autofix-max-major-bump	--sca-autofix-max-major-bump

The strict.yaml example above, written with the imperative commands:

vulnetix config set quality-gate --severity high --exploits active \
  --block-malware true --block-unpinned true --cooldown 7 --block-eol true \
  --sca-autofix-strategy safest --sca-autofix-max-major-bump 0
vulnetix config set eol-policy --next-quarter-severity skip --this-quarter-severity low \
  --within-30-days-severity high --retired-severity critical

vulnetix config get quality-gate shows what is stored. See Imperative commands for every flag and the null value that unsets a field.

Terraform and OpenTofu

The resource is vulnetix_quality_gate in the vulnetix/resolve provider. Its arguments are the spec in snake case, beside name, labels and annotations from metadata. The Minimal and Advanced HCL are above. The provider’s own reference is vulnetix_quality_gate.

Import an object that already exists by its name (default):

# Import an existing QualityGate by its name (metadata.name).
terraform import vulnetix_quality_gate.default default

Install, authentication and how state is read: Terraform and OpenTofu.

More examples

examples/QualityGate/strict.yaml from Vulnetix/config-schemas:

# yaml-language-server: $schema=https://github.com/Vulnetix/config-schemas/releases/latest/download/QualityGate.schema.json
apiVersion: vulnetix.com/v1
kind: QualityGate
metadata:
  name: default
spec:
  severity: high
  exploits: active
  blockMalware: true
  blockUnpinned: true
  cooldownDays: 7
  eol:
    block: true
    severities:
      nextQuarter: skip
      thisQuarter: low
      within30Days: high
      retired: critical
  scaAutofix:
    strategy: safest
    maxMajorBump: 0

Check a file with vulnetix config validate -f <file>. See Validate documents. In an editor, start the file with the schema comment.