Your First Check

This page explains what happens inside vyb check — the scanning logic, how patterns are matched, what the exit codes mean, and how to read the Evidence Pack that is produced on a passing run.

What vyb check scans

By default, vyb check diffs the current HEAD against the merge base of the default branch. It evaluates every changed file line-by-line against every active rule in .vyb/spec.yaml.

vyb check
  ├── Reads .vyb/spec.yaml
  ├── Computes diff (HEAD vs. merge base)
  ├── For each changed file:
  │     └── For each active rule in spec:
  │           └── Test pattern against added/modified lines
  ├── Aggregates violations by severity
  ├── Writes Evidence Pack (if no block violations)
  └── Exits with 0 (pass) or 1 (block violation found)

Rules are only tested against added or modified lines, not deleted lines. Removing a banned pattern is always safe.

Pattern matching

Each rule defines a pattern field — a regular expression tested against each line. For example:

rules:
  - id: sec-001
    name: no-eval
    pattern: "eval\\("
    severity: block

The pattern eval\( will match any line containing eval( anywhere in the line. Patterns are case-sensitive by default and match against the raw source text including whitespace.

Multiline patterns

Some rules need to match across lines — for instance, detecting a function signature followed by a forbidden body. Use the pattern-mode: multiline option:

rules:
  - id: sec-007
    name: no-hardcoded-secrets
    pattern: "(password|secret|api_key)\\s*=\\s*['\"][^'\"]{8,}"
    pattern-mode: multiline
    severity: block

Exclusions

Rules support per-rule exclusion globs to avoid false positives:

rules:
  - id: fe-003
    name: no-direct-dom
    pattern: "document\\.getElementById"
    severity: warn
    exclude:
      - "**/*.test.ts"
      - "**/test-utils/**"
      - "**/__fixtures__/**"

Severity levels

Severity	Exit code	Behavior
info	0	Reported in output, never fails the check
warn	0 (default)	Reported; fails only if --fail-on-warn is set
block	1	Always causes a non-zero exit — PR is blocked

The severity floor in your spec sets the minimum allowed severity:

settings:
  severity-floor: warn  # rules below this level are silently skipped

Reading the output

A typical vyb check output:

vyb check  v1.0.0
───────────────────────────────────────────────────────────
  Project:   acme-platform
  Spec:      .vyb/spec.yaml
  Diff:      HEAD..origin/main  (7 files, 312 lines added)
  Timestamp: 2026-05-18T14:03:22Z

  Rules evaluated: 31
  Files scanned:   7
  Violations:      3

  ── BLOCK ──────────────────────────────────────────────
  [sec-003]  hardcoded-jwt-secret
             src/auth/tokens.ts:88
             const JWT_SECRET = "my-dev-secret-please-change"
             → Use process.env.JWT_SECRET and rotate via secrets manager

  ── WARN ───────────────────────────────────────────────
  [fe-003]   no-direct-dom
             src/components/LegacyWidget.tsx:34
             document.getElementById('root')
             → Use React refs (useRef) instead

  [dep-002]  no-lodash
             package.json:+  "lodash": "^4.17.21"
             → Use native Array methods or the subset package lodash-es

  FAIL  (1 block, 2 warn)
───────────────────────────────────────────────────────────
Exit code: 1

Each violation shows:

• Rule ID and name — cross-referenceable with your spec
• File and line number — with the exact matching line
• Remediation hint — from the rule's remediation field

The Evidence Pack

On a passing run, vyb check writes an Evidence Pack to .vyb/evidence/:

.vyb/
  evidence/
    2026-05-18T14-03-22Z.pdf     ← Human-readable PDF
    2026-05-18T14-03-22Z.json    ← Machine-readable JSON with signature

The JSON file contains:

• SHA-256 hash of the diff
• Ed25519 signature of the payload
• A chain link referencing the previous Evidence Pack hash
• Per-rule pass/fail status with timestamps
• Framework control mappings (SOC 2, EU AI Act, HIPAA, DORA)

See Evidence Pack Overview for the full format specification.

Exit codes reference

Code	Meaning
0	All rules passed (or only info/warn violations, default mode)
1	One or more block-severity violations
2	Spec file not found or invalid YAML
3	Git repository not found
4	Internal engine error

Flags reference

vyb check [options]

Options:
  --base <ref>          Base ref to diff against (default: merge base)
  --staged              Check only staged changes (pre-commit mode)
  --files <glob>        Limit scan to matching files
  --dry-run             Report violations without failing (exit 0)
  --fail-on-warn        Treat warn-severity as block (exit 1)
  --ci                  CI-friendly output: no color, structured lines
  --output <path>       Write JSON results to file instead of stdout
  --evidence-dir <path> Override evidence output directory
  --no-evidence         Skip Evidence Pack generation
  --quiet               Suppress output, use exit code only

---

Next: Spec YAML Reference