How audits work
What happens during a Veriom audit, which scanners run, what each AI agent role does, and why an audit can finish with gaps.
This page is for anyone who wants to understand where Veriom's results come from. An audit reads one repository at one commit, runs security scanners, and asks a team of AI agents to review the evidence. It produces findings, a map of your architecture, and a report.
What starts an audit
| Trigger | When |
|---|---|
| First audit | When you connect a repository or upload a ZIP |
| Push | Each push or merged pull request on the default branch |
| Schedule | Weekly, Monday at 09:00 UTC, unless you change it |
| Pull request check | Each pull request, if you turn it on. See Run Veriom in CI |
| By hand | Audits → Start audit |
| CI or MCP | The architecture-check action, or the start_audit tool |
Veriom sets up the first audit, the push trigger, and the weekly schedule for you. See Autopilot and autonomy.
Full or Architecture assessment
When you start an audit, choose what it runs. Full assessment is selected first.
| Assessment | What it runs | Use it when |
|---|---|---|
| Full assessment | Everything in the Architecture assessment, plus the dependency vulnerability, secret, code pattern and configuration checks below, mapped onto your architecture | You want your architecture and its security findings. This is the default |
| Architecture assessment | A partial assessment: the architecture model, structural checks, style detection and threat scenarios. No vulnerability checks | You only want the map and its structural risks, for example to share a diagram with your team |
A Full assessment also stands for an Architecture assessment, so a trigger never starts an Architecture assessment of a commit that already had a Full one. Results unchanged since an earlier audit are reused, so a repeat assessment uses fewer processing units.
Schedules and push triggers each name their assessment. Autopilot's push trigger runs an Architecture assessment and its weekly schedule a Full assessment. In the API, assessment_type is security for a Full assessment and architecture for an Architecture assessment; a request that names none runs a Full assessment, as does the architecture-check action and the MCP start_audit tool.
One source has one active audit at a time. A second request for the same source gets 409 source_audit_already_active.
The five stages
| Stage | What happens |
|---|---|
| Ingestion | Veriom fetches the code at the chosen commit. Git hooks, submodules, and Git LFS files are not fetched |
| Scanning | Security scanners run on the code. See the list below |
| Context Engine | Veriom gathers what it knows about the system: code, scanner results, connected tools, cloud inventory, and earlier audits |
| Analysis | A team of AI agents reviews the evidence. See the roles below |
| Reporting | Veriom writes the report and runs your release checks |
If Ingestion or Reporting fails, the audit fails. If a scanner fails, the audit continues without that scanner's results and finishes with gaps.
Scanners
Every Full assessment runs these checks in Veriom's runner, from pinned open-source scanner images built to work offline. An Architecture assessment runs none of them. Veriom names each check by what it looks for.
| Check | What it looks for |
|---|---|
| Code pattern analysis | Insecure code patterns |
| Secret detection | Secrets committed to the repository. Matches are stored redacted |
| Dependency vulnerability check | Vulnerable dependencies, from several advisory databases including OSV |
| SBOM inventory | A list of every package (an SBOM) |
| IaC misconfiguration check | Infrastructure-as-code misconfigurations |
| Policy-as-code check | Policy checks on configuration files |
| Container build check | Dockerfile problems |
| CI workflow analysis | GitHub Actions workflow problems |
The agent team
Sixteen AI agent roles review each audit. Some always run. Others run only when the code shows they are needed.
| Role | What it does | Runs |
|---|---|---|
| Audit Coordinator | Plans the audit and sets each specialist's questions | Always |
| Context Curator | Packs the relevant facts into a bounded context for the other agents | Always |
| Security Engineer | Reads scanner and code evidence along paths an attacker can reach | Always |
| Security Auditor | Hunts for trust-boundary failures, one attack class at a time | Always |
| Security Architect | Checks trust boundaries, exposure, isolation, and blast radius | Always |
| Cloud and IaC Analyst | Reconciles cloud, Kubernetes, and infrastructure-as-code evidence | When the code has cloud, IaC, or Kubernetes files |
| CI/CD Analyst | Reviews build, deploy, and credential flows | When the code has CI/CD configuration |
| Compliance Control Analyst | Maps evidence to control questions. It does not certify compliance | Always |
| Architecture Diagnostic Analyst | Finds coverage gaps, contradictions, and stale facts | Always |
| Architecture History Analyst | Explains what changed since earlier audits | When earlier audits exist |
| Threat Modeler | Writes STRIDE threats tied to real assets and paths | Always |
| Remediation Engineer | Proposes bounded fixes for confirmed findings | When there are findings |
| Evidence Verifier | Rejects claims without evidence and confidence that is too high | Always |
| Finding Impact Adjudicator | Decides whether each scanner result affects the architecture | When there are findings |
| Diagram Architect | Draws the architecture diagrams | Always |
| Report Synthesizer | Writes the final judgment from verified work | Always |
The Security Auditor
The Security Auditor looks for places where a trust boundary fails, such as missing authorization, data leaking between tenants, or unsafe AI agent tools. For each problem it reports one of:
- a confirmed risk, with evidence;
- a hypothesis that needs a person to validate it;
- nothing, when the evidence rules the problem out.
The Evidence Verifier checks the auditor's work before it reaches the report. The auditor can search code and read evidence, findings, and architecture facts. It never runs your code.
Why an audit finishes "Done, with gaps"
Done, with gaps means the audit finished but some evidence is missing. The results are still usable. Common causes:
- a scanner failed;
- the agent team did not run;
- the workspace ran out of processing units. The audit records the gap "Processing units ran out before the architecture analysis finished."
Open the audit from Audits to see which stage has gaps.
The Audits page
| Tab | What it shows |
|---|---|
| Runs | The audit running now or the latest one, its steps, any other active runs, and each repository with its latest run |
| History | Every past run, filtered by source and sorted by date. Click a run to open it |
| Remediations | Each fix from proposal to pull request and verified resolution. See Ask Veriom to fix it |
| Schedules, Changes, Branches | Continuous audits, architecture changes between revisions, and branch comparisons |
Each run shows its high-level steps. Its detailed activity log and agent artifacts are kept for compliance reviews and third-party auditors, collapsed under the steps: click Show activity log to open them.
Watch audits live
Click the activity button in the header to open the Activity panel. It shows:
- Running now: each live audit, its stage, and its agents;
- Queue: work waiting for scanners, reports, pull requests, collections, or agents;
- Recent: what finished. Turn on Automation only to see what Veriom did on its own.
Ask Veriom
Click Ask Veriom in the header to ask a question about your architecture, findings, and evidence. Answers are grounded in this workspace's audits and cite their evidence. The Priorities tab lists the most important things to work on next.
Was this guide useful?
Your response stays in this browser unless you open a GitHub issue.Use Veriom from an AI assistant (MCP)
Connect Cursor, Claude, or another MCP client to Veriom so it can send evidence, upload repositories, and start audits in your workspace.
Work with findings
Read a Veriom finding, triage it, mark false positives, accept a risk, merge duplicates, and ask Veriom to open a fix pull request.