# QualityGate

The tenant's quality gate: the checks every vulnetix scan in CI must pass. Fields, YAML, HCL and CLI samples, and how apply treats it.

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](/platform-iac/kinds/catalogue.md#scanners-and-gates) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | one (`metadata.name: default`) |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Terraform resource | [`vulnetix_quality_gate`](/platform-iac/terraform/resources.md#vulnetix_quality_gate), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.153.0 and later. |
| Pinned schema | [`v1.19.1/QualityGate.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/QualityGate.schema.json) |
| Newest schema | [`latest/QualityGate.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/QualityGate.schema.json) |
| First released in | [`v1.0.0`](https://github.com/Vulnesis/config-schemas/releases/tag/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
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/QualityGate.schema.json
apiVersion: vulnetix.com/v1
kind: QualityGate
metadata:
  name: default
spec: {}
```

**HCL** (resource `vulnetix_quality_gate`)

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

resource "vulnetix_quality_gate" "default" {
}
```

Every field that has a schema default, set to that default: [`terraform/quality_gate.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/quality_gate.tf) and [`yaml/QualityGate.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/QualityGate.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/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
# yaml-language-server: $schema=https://github.com/Vulnesis/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`)

```hcl
# 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"
  }
}
```

Every field that has a schema default, set to that default: [`terraform/quality_gate.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/quality_gate.tf) and [`yaml/QualityGate.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/QualityGate.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/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 |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `QualityGate` | Always QualityGate. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys | Metadata for a kind the tenant has exactly one of. The name is fixed to default. |
| <span id="metadata-name"></span>`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. |
| <span id="metadata-org"></span>`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. |
| <span id="metadata-labels"></span>`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. |
| <span id="metadata-annotations"></span>`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. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys | The gate settings. Every field is optional. |
| <span id="spec-severity"></span>`spec.severity` | string | no |  | `low`, `medium`, `high`, `critical` | Fail on any affected vulnerability at or above this severity. Overrides --severity. |
| <span id="spec-exploits"></span>`spec.exploits` | string | no |  | `poc`, `active`, `weaponized` | Fail on a vulnerability with an exploit at or beyond this maturity. Overrides --exploits. |
| <span id="spec-blockMalware"></span>`spec.blockMalware` | boolean | no |  |  | Fail when a dependency is known malware. Overrides --block-malware. |
| <span id="spec-blockUnpinned"></span>`spec.blockUnpinned` | boolean | no |  |  | Fail on a dependency declared without a pinned version. Overrides --block-unpinned. |
| <span id="spec-cooldownDays"></span>`spec.cooldownDays` | integer | no |  | >= 0 | Fail on a dependency version published fewer than this many days ago. Overrides --cooldown. |
| <span id="spec-versionLag"></span>`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. |
| <span id="spec-eol"></span>`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. |
| <span id="spec-eol-block"></span>`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. |
| <span id="spec-eol-severities"></span>`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. |
| <span id="spec-eol-severities-nextQuarter"></span>`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. |
| <span id="spec-eol-severities-thisQuarter"></span>`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. |
| <span id="spec-eol-severities-within30Days"></span>`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. |
| <span id="spec-eol-severities-retired"></span>`spec.eol.severities.retired` | string | no | `critical` | `skip`, `low`, `medium`, `high`, `critical` | Severity for a dependency already past its end of life. |
| <span id="spec-scaAutofix"></span>`spec.scaAutofix` | object | no |  | no other keys | How vulnetix fix and scan --sca-autofix choose a target version. |
| <span id="spec-scaAutofix-strategy"></span>`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. |
| <span id="spec-scaAutofix-maxMajorBump"></span>`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. |

> [!CAREFUL] `spec.versionLag`
> The schema description says "more than this many releases behind the newest". The CLI gate does the opposite: `vulnetix scan --version-lag N` fails a dependency whose installed version is one of the N most recently published versions. The CLI behaviour is what runs.

> [!CAREFUL] `spec.eol.block`
> The description is true of the CLI gate only: `vulnetix scan` reads the horizon severities only when the EOL gate is on. On the platform, once the organization has a quality gate record, uploaded scans get a synthetic `VULNETIX-EOL` finding at the horizon severity whatever `block` says.

> [!CAREFUL] `spec.scaAutofix.maxMajorBump`
> The `--sca-autofix-max-major-bump` scan flag also accepts a negative number, meaning no limit. The schema has `minimum: 0`, so a document cannot express "no limit"; leave the field out to keep the flag in charge.

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): 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](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Status.** Applied, Unchanged or Deleted, with no other status fields. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#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:

```sh
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](/platform-iac/cli/imperative-commands.md) 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](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/quality_gate).

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

```shell
# 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](/platform-iac/terraform.md).

## More examples

`examples/QualityGate/strict.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/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](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
