docs.how_it_works()

how a virgil audit works

one credit runs one audit: you hand virgil a repository (a github url, a zip, or your working directory via the cli), and about three minutes later you get a ranked triage instead of a wall of scanner output. this page walks the pipeline end to end.

## 1. intake

submissions arrive as a git url or an uploaded zip. the repo is fetched once, then everything downstream runs against that snapshot — your code is read, never executed. submissions that get rejected at intake (wrong archive type, clone failure, size limits) refund the credit automatically.

## 2. sandboxed scanning

virgil doesn't invent its own detectors. it runs the scanners the industry already trusts — semgrep for code patterns, trivy for dependency CVEs and misconfigurations, gitleaks for committed secrets — inside a locked-down container: --network=none, --read-only, --cap-drop=ALL, bounded cpu, memory and process count, non-root. the scanners can see the snapshot and nothing else. details in the security model.

## 3. normalize + redact

raw scanner output is normalized into one finding schema, and secrets are scrubbed before anything is stored or shown to a model: aws keys, github tokens, jwts, slack tokens, google api keys, private-key blocks, internal ips. each finding keeps a redacted ~30-line code slice so later stages can point at your actual lines.

## 4. cluster, don't list

47 sql-injection findings that all flow through one query helper are not 47 problems — they're one problem with 47 symptoms. virgil groups findings that share a root cause into a single cluster pointed at the shared code, so the fix count you scroll is the real one.

## 5. reachability

a dependency CVE in a package your code never imports is noise. virgil checks whether the vulnerable package is actually reachable from your code across five language families (python, js/ts, go, ruby, java/kotlin); unreachable CVEs drop a severity rung and hide by default. the full logic is on the reachability page.

## 6. rank: the fix-this-week queue

the surviving clusters get ranked into a short queue with a one-line rationale each — severity, blast radius, whether the CVE appears in CISA's known-exploited list. an llm writes the rationale and the narrative report; every model output passes a safety validator that rejects payloads, patches, and step-by-step reproduction. if no model is available, a deterministic fallback ranks the queue the same shape.

## 7. read it your way

+the web console: triage queue, full findings table, attack-surface profile, executive report
+a chat grounded in the audit — answers cite the stored code slices, not generalities
+exports: json, markdown, sarif, pdf, plus cyclonedx/spdx sbom
+the cli prints the same triage in your terminal with ci-friendly exit codes

## try it

pipx install virgilhq
virgil login        # 3 free audits on every new account
virgil scan .

or paste a repo url on the home page — same pipeline, same three minutes. pricing is per audit, nothing recurring.