Vetrix Docs

10-minute quickstart

From a fresh repo to a first actionable finding list.

0. Prerequisites

  • A Vetrix account with PermPolicyEdit on the repo you are configuring (owners and instance admins have this implicitly).
  • A local checkout of the repo. Git CLI is optional — the Configure UI writes .vetrix/tooling.yml for you.
  • The repo has a go.mod, package.json, requirements.txt, pom.xml, Gemfile, or composer.json so the auto-detector has something to chew on.

1. Run Configure

Visit /<owner>/<repo>/security/configure.

The wizard will:

  1. Fetch the repo's default branch HEAD.
  2. Scan for language + framework markers. The full detection matrix lives in auto-detect.md.
  3. Propose a scanner set. You see exactly which scanners will run, what ruleset each uses, and what severity floor triggers a finding.
  4. On Confirm, commit the proposed .vetrix/tooling.yml to the default branch — you can also hand-edit the YAML before confirming.

Nothing is applied silently. The repo now owns the config.

2. Watch the first scan run

Push any commit to the default branch (or an arbitrary branch with a PR open). The vetrix/security-scan@<SHA> composite action fires on the next pipeline run, dispatches every enabled scanner in parallel, and POSTs SARIF output to /api/v1/repos/{owner}/{repo}/security/ingest.

The Pipelines tab shows the scan as a workflow run; the Findings tab populates as each scanner reports.

3. Triage

Go to /<owner>/<repo>/security/findings. Each row is one unique defect across every scan — re-scans collapse into a single fingerprint. Filter by severity / category / state. Click a row to open the drawer with the full occurrence log.

If PermFindingDismiss is granted, checkboxes and a Dismiss N button appear. Dismissals are bulk in a single transaction, with one audit_log row per fingerprint.

4. Baseline legacy debt (optional)

Sometimes a greenfield scan drops 400 findings on day one. Baseline them:

# From the repo root.
vetrix-security-scan --snapshot > .vetrix/tooling.baseline.sarif
git add .vetrix/tooling.baseline.sarif
git commit -m "Baseline security findings as of <date>"

Baselined fingerprints still land on the dashboard, but the PR annotator and OPA merge gate treat them as pre-approved. You can remove the baseline entry to re-open it at any time.

5. Gate merges (optional)

The default is warn-only. When you want hard blocks on new verified secrets or critical SCA findings, edit the merge gate — see policies.md.

10-minute budget

At 2.5 min per phase the four phases fit inside the budget on every repo we tested. If you are under 2 min on phase 1 you either have a very narrow project or the auto-detector missed a language — add it manually in .vetrix/tooling.yml and re-run the Configure wizard.