.vetrix/tooling.yml schema reference

The repo-committed .vetrix/tooling.yml is the single source of truth for per-repo security + quality tooling. The Configure UI generates it; hand-editing is fully supported. Unknown top-level keys are rejected at parse time to preserve schema versioning.

Top-level fields

version: 1             # only 1 is accepted today
detected:              # informational, written by the Configure UI
  languages: [go, typescript]
  frameworks: [next]
secrets:   { ... }     # gitleaks + trufflehog
sca:       { ... }     # trivy, osv-scanner, govulncheck, dependency-check
sast:      { ... }     # semgrep, gosec, bandit, brakeman, psalm, eslint, ruff, rubocop
iac:       { ... }     # checkov
standards: { ... }     # phpcs + per-language code-standard checkers
paths:     [ ... ]     # monorepo path-scoped overrides
policy:    { ... }     # severity gate for merge + deploy
baseline:  { ... }     # path to .vetrix/tooling.baseline.sarif

secrets

secrets:
  enabled: true
  gitleaks:
    enabled: true
    rulesets: [default, aws]
    severity: high
  trufflehog:           # CI-stage verification, opt-in
    enabled: true
    verify: true

• gitleaks.enabled: true arms the in-process pre-receive hook.
• trufflehog.verify: true turns on live credential verification on the runner sidecar (AGPL stays out of the server binary — see scanners/trufflehog.md).

timeout and runner_tags

Every <scanner> block accepts two performance knobs:

sast:
  semgrep:
    enabled: true
    timeout: 30m
    runner_tags: [linux, heavy-io]

• timeout is a Go duration ("2m", "15m", "30s"). Zero / empty falls back to the per-family default (fast tools 2 minutes, heavy tools 15 minutes — see internal/tooling/timeouts.go). A scanner that hits its timeout is cancelled and emits a SARIF invocation with exitCode=124; sibling scanners keep running.
• runner_tags restricts dispatch to runners advertising every listed tag. Empty means "any runner". Heavy scans can be pinned to a dedicated runner group via runner_tags: [heavy-io] so they cannot starve the pool.

sca

sca:
  enabled: true
  trivy:           { enabled: true }
  osv_scanner:     { enabled: true }
  govulncheck:     { enabled: true }
  dependency_check: { enabled: false }
  severity: high

Multiple SCA scanners coexist because each has different strengths (OSV covers more ecosystems, Trivy handles container images, Dependency-Check is the Java-CPE gold standard). Fingerprints across tools dedupe on the same CVE + package tuple — see scanners/dependency-check.md.

sast

sast:
  enabled: true
  semgrep: { enabled: true, rulesets: [p/security-audit, p/owasp-top-ten] }
  gosec:   { enabled: true }
  bandit:  { enabled: true }
  brakeman:{ enabled: true }
  psalm:   { enabled: true }
  eslint:  { enabled: true }
  ruff:    { enabled: true }
  rubocop: { enabled: true }
  severity: medium

• semgrep.rulesets accepts any Semgrep Registry reference plus your own pinned rules under .vetrix/rules/.
• Per-scanner severity overrides the block-level floor.

iac

iac:
  enabled: true
  checkov: { enabled: true }
  severity: high

standards

standards:
  enabled: true
  phpcs: { enabled: true, rulesets: [Magento2, PSR12] }

standards.<tool> accepts any linter that emits SARIF. Currently phpcs is the shipping first-party integration; others plug in via the scanner adapter framework.

paths

paths:
  - match: services/api/**
    sast: { enabled: true, gosec: { enabled: true } }
  - match: apps/web/**
    sast: { enabled: true, eslint: { enabled: true } }
    sca:  { enabled: true }

Overrides are match-order-preserving: later entries win on overlap.

policy

policy:
  merge:
    block_on:
      - category: secret
        verified: true
      - category: sca
        severity: critical
        direct: true
  deploy:
    require:
      - sbom
      - image-signed
    block_on:
      - category: any
        severity: critical
        baseline: false

Policy blocks are consumed by the merge + deploy gates. See policies.md for the full evaluation rules.

baseline

baseline:
  path: .vetrix/tooling.baseline.sarif

Default path is what the Configure UI scaffolds. Custom paths are honoured as long as the file exists on the default branch at scan time.

Full example

version: 1
detected:
  languages: [go, typescript]
secrets:
  enabled: true
  gitleaks: { enabled: true }
sca:
  enabled: true
  trivy: { enabled: true }
  govulncheck: { enabled: true }
  severity: high
sast:
  enabled: true
  gosec: { enabled: true }
  eslint: { enabled: true }
iac:
  enabled: true
  checkov: { enabled: true }
policy:
  merge:
    block_on:
      - category: secret
        verified: true