# VexSource

VEX documents read back as suppression rules. Fields, YAML, HCL and CLI samples, and how apply treats it.

VEX documents read back as suppression rules. A not_affected statement (CycloneDX not_affected or false_positive) becomes a suppression with the document's justification, timestamp and author; fixed or resolved marks the finding remediated; affected, in_triage and exploitable are recorded as triage context; under_investigation is an annotation. Products are matched to findings by purl. A later statement wins. Suppressions a source creates are owned by it: they go when the statement leaves the document, and cannot be deleted by hand. Name exactly one of tea, s3, git, path or urls.

How sources are fetched, how statements become suppressions and how a `path` source is uploaded are on [VEX documents as suppression rules](/platform-iac/guides/vex-sources.md). The Advanced sample applies as written. The fields the schema accepts but plan blocks are listed under [what plan refuses](#what-plan-refuses-today), and the schema release carries them in `examples/VexSource/unsupported-features.yaml`.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `VexSource` |
| Group | [Suppression](/platform-iac/kinds/catalogue.md#suppression) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | many, keyed by `metadata.name` |
| 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). |
| Applied after | [`VaultEntry`](/platform-iac/kinds/vault-entry.md) (deleted before them) |
| Terraform resource | [`vulnetix_vex_source`](/platform-iac/terraform/resources.md#vulnetix_vex_source), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.157.0 and later. |
| Pinned schema | [`v1.19.1/VexSource.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/VexSource.schema.json) |
| Newest schema | [`latest/VexSource.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json) |
| First released in | [`v1.1.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.1.0) |
| Print the built-in copy | `vulnetix config schema VexSource` |

## Minimal

Only the fields the kind requires. From `examples/VexSource/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: local-vex
spec:
  path:
    path: .vulnetix/vex.openvex.json
```

**HCL** (resource `vulnetix_vex_source`)

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

resource "vulnetix_vex_source" "local_vex" {
  name = "local-vex"
  path = {
    path = ".vulnetix/vex.openvex.json"
  }
}
```

Every field that has a schema default, set to that default: [`terraform/vex_source.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/vex_source.tf) and [`yaml/VexSource.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/VexSource.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/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: local-vex
spec:
  path:
    path: .vulnetix/vex.openvex.json
EOF
```

## Advanced

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

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vendor-tea-product
  labels:
    team: product-security
  annotations:
    ticket: https://jira.example.com/browse/SEC-2217
spec:
  format: auto
  scope:
    org: true
  trust:
    allowedAuthors: [security@acme.example]
  refresh: { interval: 6h }
  onError: keep-last
  tea:
    product: 7f3c1a52-1b8e-4d0e-9c3f-2a6b8e5d4c10
    server: https://tea.acme.example
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vendor-tea-release
spec:
  format: cyclonedx
  refresh: { interval: 1d }
  tea:
    productRelease: "urn:tei:uuid:products.acme.example:4b2e9d17-6a3c-4f81-b5d0-8e1c7a9f2d36"
    server: https://tea.acme.example
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vendor-tea-collection
spec:
  scope:
    repos: [acme/payments-api]
  refresh: { webhook: true }
  tea:
    collection: 2c8f4e61-9d7a-4b35-a0e2-5f6c3b8d1e94
    server: https://tea.vendor.example.com
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vex-bucket
spec:
  format: openvex
  refresh: { webhook: true }
  onError: keep-last
  s3:
    bucket: acme-vex-statements
    prefix: openvex/
    region: us-east-1
    roleArn: arn:aws:iam::123456789012:role/VulnetixVexRead
    externalId: acme-vex-read-7f3c1a52
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vex-bucket-object
spec:
  format: openvex
  refresh: { interval: 30m }
  s3:
    bucket: acme-vex-public
    region: us-east-1
    key: products/ledger/ledger.openvex.json
    roleArn: arn:aws:iam::123456789012:role/VulnetixVexRead
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: platform-repo
spec:
  scope:
    repos: [acme/payments-api, acme/ledger]
  git:
    url: https://github.com/acme/security-advisories.git
    ref: main
    paths: ["vex/**/*.openvex.json", "vex/**/*.cdx.json"]
    credentialRef: github-advisories-token
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: local-vex
spec:
  format: cyclonedx
  path:
    path: .vulnetix/vex.cdx.json
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: upstream-urls
spec:
  refresh: { interval: 1d }
  onError: clear
  urls:
    - https://downloads.example.org/vex/product.openvex.json
    - url: https://vendor.example.com/vex/all.cdx.json
      sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
      auth:
        header: Authorization
        credentialRef: vendor-vex-token
```

**HCL** (resource `vulnetix_vex_source`)

```hcl
# Every argument the kind supports. From config-schemas examples/VexSource/advanced.yaml.

resource "vulnetix_vex_source" "vendor_tea_product" {
  name     = "vendor-tea-product"
  format   = "auto"
  on_error = "keep-last"
  refresh = {
    interval = "6h"
  }
  scope = {
    org = true
  }
  tea = {
    product = "7f3c1a52-1b8e-4d0e-9c3f-2a6b8e5d4c10"
    server  = "https://tea.acme.example"
  }
  trust = {
    allowed_authors = ["security@acme.example"]
  }
  labels = {
    team = "product-security"
  }
  annotations = {
    ticket = "https://jira.example.com/browse/SEC-2217"
  }
}

resource "vulnetix_vex_source" "vendor_tea_release" {
  name   = "vendor-tea-release"
  format = "cyclonedx"
  refresh = {
    interval = "1d"
  }
  tea = {
    product_release = "urn:tei:uuid:products.acme.example:4b2e9d17-6a3c-4f81-b5d0-8e1c7a9f2d36"
    server          = "https://tea.acme.example"
  }
}

resource "vulnetix_vex_source" "vendor_tea_collection" {
  name = "vendor-tea-collection"
  refresh = {
    webhook = true
  }
  scope = {
    repos = ["acme/payments-api"]
  }
  tea = {
    collection = "2c8f4e61-9d7a-4b35-a0e2-5f6c3b8d1e94"
    server     = "https://tea.vendor.example.com"
  }
}

resource "vulnetix_vex_source" "vex_bucket" {
  name     = "vex-bucket"
  format   = "openvex"
  on_error = "keep-last"
  refresh = {
    webhook = true
  }
  s_3 = {
    bucket      = "acme-vex-statements"
    external_id = "acme-vex-read-7f3c1a52"
    prefix      = "openvex/"
    region      = "us-east-1"
    role_arn    = "arn:aws:iam::123456789012:role/VulnetixVexRead"
  }
}

resource "vulnetix_vex_source" "vex_bucket_object" {
  name   = "vex-bucket-object"
  format = "openvex"
  refresh = {
    interval = "30m"
  }
  s_3 = {
    bucket   = "acme-vex-public"
    key      = "products/ledger/ledger.openvex.json"
    region   = "us-east-1"
    role_arn = "arn:aws:iam::123456789012:role/VulnetixVexRead"
  }
}

resource "vulnetix_vex_source" "platform_repo" {
  name = "platform-repo"
  git = {
    credential_ref = "github-advisories-token"
    paths          = ["vex/**/*.openvex.json", "vex/**/*.cdx.json"]
    ref            = "main"
    url            = "https://github.com/acme/security-advisories.git"
  }
  scope = {
    repos = ["acme/payments-api", "acme/ledger"]
  }
}

resource "vulnetix_vex_source" "local_vex" {
  name   = "local-vex"
  format = "cyclonedx"
  path = {
    path = ".vulnetix/vex.cdx.json"
  }
}

resource "vulnetix_vex_source" "upstream_urls" {
  name     = "upstream-urls"
  on_error = "clear"
  refresh = {
    interval = "1d"
  }
  urls = jsonencode(["https://downloads.example.org/vex/product.openvex.json", {
    auth = {
      credentialRef = "vendor-vex-token"
      header        = "Authorization"
    }
    sha256 = "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    url    = "https://vendor.example.com/vex/all.cdx.json"
  }])
}
```

Every field that has a schema default, set to that default: [`terraform/vex_source.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/vex_source.tf) and [`yaml/VexSource.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/VexSource.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/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vendor-tea-product
  labels:
    team: product-security
  annotations:
    ticket: https://jira.example.com/browse/SEC-2217
spec:
  format: auto
  scope:
    org: true
  trust:
    allowedAuthors: [security@acme.example]
  refresh: { interval: 6h }
  onError: keep-last
  tea:
    product: 7f3c1a52-1b8e-4d0e-9c3f-2a6b8e5d4c10
    server: https://tea.acme.example
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vendor-tea-release
spec:
  format: cyclonedx
  refresh: { interval: 1d }
  tea:
    productRelease: "urn:tei:uuid:products.acme.example:4b2e9d17-6a3c-4f81-b5d0-8e1c7a9f2d36"
    server: https://tea.acme.example
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vendor-tea-collection
spec:
  scope:
    repos: [acme/payments-api]
  refresh: { webhook: true }
  tea:
    collection: 2c8f4e61-9d7a-4b35-a0e2-5f6c3b8d1e94
    server: https://tea.vendor.example.com
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vex-bucket
spec:
  format: openvex
  refresh: { webhook: true }
  onError: keep-last
  s3:
    bucket: acme-vex-statements
    prefix: openvex/
    region: us-east-1
    roleArn: arn:aws:iam::123456789012:role/VulnetixVexRead
    externalId: acme-vex-read-7f3c1a52
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vex-bucket-object
spec:
  format: openvex
  refresh: { interval: 30m }
  s3:
    bucket: acme-vex-public
    region: us-east-1
    key: products/ledger/ledger.openvex.json
    roleArn: arn:aws:iam::123456789012:role/VulnetixVexRead
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: platform-repo
spec:
  scope:
    repos: [acme/payments-api, acme/ledger]
  git:
    url: https://github.com/acme/security-advisories.git
    ref: main
    paths: ["vex/**/*.openvex.json", "vex/**/*.cdx.json"]
    credentialRef: github-advisories-token
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: local-vex
spec:
  format: cyclonedx
  path:
    path: .vulnetix/vex.cdx.json
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: upstream-urls
spec:
  refresh: { interval: 1d }
  onError: clear
  urls:
    - https://downloads.example.org/vex/product.openvex.json
    - url: https://vendor.example.com/vex/all.cdx.json
      sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
      auth:
        header: Authorization
        credentialRef: vendor-vex-token
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 `VexSource` | Always VexSource. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | 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 |  |
| <span id="spec-format"></span>`spec.format` | string | no | `auto` | `openvex`, `cyclonedx`, `auto` | openvex: OpenVEX 0.2.0. cyclonedx: CycloneDX VEX 1.4 to 1.7 (vulnerabilities[].analysis). auto: decided per document. |
| <span id="spec-scope"></span>`spec.scope` | object | no |  | no other keys | Which findings the statements may suppress. Left out, the whole tenant. |
| <span id="spec-scope-org"></span>`spec.scope.org` | boolean | no |  | exactly `true` | The whole tenant. |
| <span id="spec-scope-repos"></span>`spec.scope.repos` | array of string | no |  | 1 to any items; items unique; each item: pattern `^[^\s/]+(/[^\s/]+)+$` |  |
| <span id="spec-scope-products"></span>`spec.scope.products` | array of string | no |  | 1 to any items; items unique; each item: pattern `^urn:tei:[a-z0-9-]+:.+`, or format `uuid` | TEA products, by TEI or uuid. |
| <span id="spec-trust"></span>`spec.trust` | object | no |  | no other keys |  |
| <span id="spec-trust-requireSignature"></span>`spec.trust.requireSignature` | boolean | no | `false` |  | Refuse a document that is not signed. |
| <span id="spec-trust-allowedAuthors"></span>`spec.trust.allowedAuthors` | array of string | no |  | 1 to any items; items unique; each item: length 1 to any | Only statements by these authors (the VEX author field) are used. |
| <span id="spec-refresh"></span>`spec.refresh` | object | no |  | no other keys | When the documents are fetched again: every interval, or when a webhook says they changed. |
| <span id="spec-refresh-interval"></span>`spec.refresh.interval` | string | no |  | pattern `^[1-9][0-9]*(m\|h\|d)$` | A whole number of minutes, hours or days: 30m, 6h, 1d. |
| <span id="spec-refresh-webhook"></span>`spec.refresh.webhook` | boolean | no |  | exactly `true` |  |
| <span id="spec-onError"></span>`spec.onError` | string | no | `keep-last` | `keep-last`, `clear` | When a fetch fails: keep-last keeps the suppressions from the last good fetch; clear removes them. |
| <span id="spec-tea"></span>`spec.tea` | object | no |  | no other keys | VEX artifacts from a TEA collection, on the Vulnesis TEA publisher or any TEA server. Name exactly one of product, productRelease or collection. |
| <span id="spec-tea-product"></span>`spec.tea.product` | string | no |  | pattern `^urn:tei:[a-z0-9-]+:.+`, or format `uuid` | A TEA identifier (urn:tei:...) or a uuid. |
| <span id="spec-tea-productRelease"></span>`spec.tea.productRelease` | string | no |  | pattern `^urn:tei:[a-z0-9-]+:.+`, or format `uuid` | A TEA identifier (urn:tei:...) or a uuid. |
| <span id="spec-tea-collection"></span>`spec.tea.collection` | string | no |  | pattern `^urn:tei:[a-z0-9-]+:.+`, or format `uuid` | A TEA identifier (urn:tei:...) or a uuid. |
| <span id="spec-tea-server"></span>`spec.tea.server` | string | yes |  | pattern `^https://`; format `uri` | The TEA API root, or the host whose /.well-known/tea discovery names it. |
| <span id="spec-s3"></span>`spec.s3` | object | no |  | no other keys | Documents in an S3 bucket, read through a cross-account role whose external id is the tenant uuid (the cloud onboarding trust pattern), or from an S3-compatible endpoint (R2, MinIO). Name exactly one of prefix or key. |
| <span id="spec-s3-bucket"></span>`spec.s3.bucket` | string | yes |  | pattern `^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$` |  |
| <span id="spec-s3-prefix"></span>`spec.s3.prefix` | string | no |  |  | Every object under this prefix. |
| <span id="spec-s3-key"></span>`spec.s3.key` | string | no |  | length 1 to any | One object. |
| <span id="spec-s3-region"></span>`spec.s3.region` | string | no |  | pattern `^[a-z]{2}(-[a-z]+)+-[0-9]$` |  |
| <span id="spec-s3-roleArn"></span>`spec.s3.roleArn` | string | no |  | pattern `^arn:aws[a-z-]*:iam::[0-9]{12}:role/.+$` | The role to assume. Required unless endpoint is set. |
| <span id="spec-s3-externalId"></span>`spec.s3.externalId` | string | no |  | length 2 to any | The external id the role's trust policy requires. Defaults to the tenant uuid. |
| <span id="spec-s3-endpoint"></span>`spec.s3.endpoint` | string | no |  | pattern `^https://`; format `uri` | An S3-compatible endpoint instead of AWS. |
| <span id="spec-s3-credentialRef"></span>`spec.s3.credentialRef` | string | no |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | With endpoint: the VaultEntry holding the access key for it. |
| <span id="spec-git"></span>`spec.git` | object | no |  | no other keys | Documents in a git repository over HTTPS (GitHub, GitHub Enterprise Server, GitLab, Gitea, Forgejo or any git server). A matching ForgeConnection is used when there is one. |
| <span id="spec-git-url"></span>`spec.git.url` | string | yes |  | pattern `^https://`; format `uri` |  |
| <span id="spec-git-ref"></span>`spec.git.ref` | string | no |  | length 1 to any | A branch, tag or commit. Defaults to the default branch. |
| <span id="spec-git-paths"></span>`spec.git.paths` | array of string | yes |  | 1 to any items; each item: length 1 to any | Globs, relative to the repository root, selecting the documents. |
| <span id="spec-git-credentialRef"></span>`spec.git.credentialRef` | string | no |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The metadata.name of a VaultEntry holding a credential. The value is read from the tenant's vault when it is needed and is never copied into the referring object. |
| <span id="spec-path"></span>`spec.path` | object | no |  | no other keys | A file or directory, absolute or relative to the config or repository root. Read by the CLI only: at scan time it applies locally, and config apply uploads a snapshot so server views match. |
| <span id="spec-path-path"></span>`spec.path.path` | string | yes |  | length 1 to any |  |
| <span id="spec-urls"></span>`spec.urls` | array of string or object | no |  | 1 to any items | Plain HTTPS URLs, each fetched with ETag and If-Modified-Since. |
| <span id="spec-urls-url"></span>`spec.urls[].url` | string | yes |  | pattern `^https://`; format `uri` |  |
| <span id="spec-urls-sha256"></span>`spec.urls[].sha256` | string | no |  | pattern `^[a-f0-9]{64}$` | Refuse the document unless its SHA-256 matches. |
| <span id="spec-urls-auth"></span>`spec.urls[].auth` | object | no |  | no other keys | A request header carrying a credential from the vault. |
| <span id="spec-urls-auth-header"></span>`spec.urls[].auth.header` | string | yes |  | pattern `^[A-Za-z0-9-]+$` |  |
| <span id="spec-urls-auth-credentialRef"></span>`spec.urls[].auth.credentialRef` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The metadata.name of a VaultEntry holding a credential. The value is read from the tenant's vault when it is needed and is never copied into the referring object. |

## Rules

Conditions the schema enforces beyond each field's own type. `vulnetix config validate` and the engine's plan report a document that breaks one.

| On | Rule |
|---|---|
| `spec` | Exactly one of `tea`, `s3`, `git`, `path` or `urls` is set. |
| `spec.scope` | Exactly one of these holds: (1) `org` is required, `repos` is not allowed and `products` is not allowed; (2) `org` is not allowed and At least one of `repos` or `products` is set.. |
| `spec.refresh` | Exactly one of `interval` or `webhook` is set. |
| `spec.tea` | Exactly one of `product`, `productRelease` or `collection` is set. |
| `spec.s3` | When `endpoint` is set: `credentialRef` is required. Otherwise: `roleArn` is required and `credentialRef` is not allowed. |
| `spec.s3` | Exactly one of `prefix` or `key` is set. |

## 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).
- **Order.** Applied after [`VaultEntry`](/platform-iac/kinds/vault-entry.md), so a document that refers to one by `metadata.name` can be in the same apply. Deleted before them.
- **Status.** The latest fetch: status `ok`, `partial` or `error`, document, statement and suppression counts, and per-document errors. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).

## What plan refuses today

The schema accepts these, and plan blocks them with the condition `unsupported`:

| Field | Why |
|---|---|
| `spec.trust.requireSignature: true` | The server does not verify signatures on fetched VEX documents. Narrow trust with `trust.allowedAuthors` instead. |
| `spec.scope.products` | Findings do not record the TEA product they belong to, so the scope could not be enforced. Use `scope.repos`. |
| `spec.s3.endpoint` | An S3-compatible store is not supported yet. Use `roleArn` on AWS. |

A `path` source plans with the warning `cli_only`: the server never fetches it. The guide has [the rest](/platform-iac/guides/vex-sources.md).

## Terraform and OpenTofu

The resource is `vulnetix_vex_source` 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_vex_source](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/vex_source).

Import an object that already exists by its name:

```shell
# Import an existing VexSource by its name (metadata.name).
terraform import vulnetix_vex_source.local_vex local-vex
```

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

## More examples

`examples/VexSource/sources.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vendor-tea
spec:
  format: auto
  scope:
    products: ["urn:tei:uuid:products.acme.example:7f3c1a52-1b8e-4d0e-9c3f-2a6b8e5d4c10"]
  trust:
    requireSignature: true
    allowedAuthors: [security@acme.example]
  refresh: { interval: 6h }
  onError: keep-last
  tea:
    product: 7f3c1a52-1b8e-4d0e-9c3f-2a6b8e5d4c10
    server: https://tea.acme.example
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vex-bucket
spec:
  format: openvex
  refresh: { webhook: true }
  s3:
    bucket: acme-vex-statements
    prefix: openvex/
    region: us-east-1
    roleArn: arn:aws:iam::123456789012:role/VulnetixVexRead
---
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: platform-repo
spec:
  scope:
    repos: [acme/payments-api, acme/ledger]
  git:
    url: https://github.com/acme/security-advisories.git
    ref: main
    paths: ["vex/**/*.openvex.json"]
    credentialRef: github-advisories-token
---
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: local-vex
spec:
  format: cyclonedx
  path:
    path: .vulnetix/vex.cdx.json
---
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: upstream-urls
spec:
  refresh: { interval: 1d }
  onError: clear
  urls:
    - https://downloads.example.org/vex/product.openvex.json
    - url: https://vendor.example.com/vex/all.cdx.json
      sha256: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
      auth:
        header: Authorization
        credentialRef: vendor-vex-token
```

`examples/VexSource/unsupported-features.yaml` from `Vulnesis/config-schemas`:

```yaml
# Fields the VexSource schema accepts and a plan blocks as `unsupported` until
# the server can honour them. This file validates against the schema but is not
# an applicable example: minimal.yaml and advanced.yaml are. Move a field back
# into advanced.yaml when the engine supports it.
#
#   trust.requireSignature   The server does not verify signatures on fetched
#                            VEX documents yet.
#   scope.products           Findings do not record the TEA product they belong
#                            to, so a product scope cannot be enforced yet.
#   s3.endpoint, credentialRef
#                            An S3-compatible store (R2, MinIO) has no vault
#                            shape for its access key yet. Use roleArn on AWS.
#
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: signed-vendor-tea
spec:
  format: auto
  scope:
    products: ["urn:tei:uuid:products.acme.example:7f3c1a52-1b8e-4d0e-9c3f-2a6b8e5d4c10"]
  trust:
    requireSignature: true
    allowedAuthors: [security@acme.example]
  refresh: { interval: 6h }
  tea:
    product: 7f3c1a52-1b8e-4d0e-9c3f-2a6b8e5d4c10
    server: https://tea.acme.example
---
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/VexSource.schema.json
apiVersion: vulnetix.com/v1
kind: VexSource
metadata:
  name: vex-r2-object
spec:
  format: openvex
  refresh: { interval: 30m }
  s3:
    bucket: acme-vex-public
    key: products/ledger/ledger.openvex.json
    endpoint: https://0123456789abcdef0123456789abcdef.r2.cloudflarestorage.com
    credentialRef: r2-vex-reader
```

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).
