Skip to content

Scan Engine

The scan engine is the AI-powered core of Vega. It takes a source code repository and a threat profile, figures out what to audit, runs AI-assisted code analysis on each component, and streams findings back to the backend.

What is v16?

v16 is the scan engine, stored in the v16/ git submodule. The name refers to an internal versioning scheme. The backend treats v16 as a black box with a well-defined API — it doesn't reach into v16's internal planning or auditing code directly.

The backend communicates with v16 through a two-layer adapter:

Backend (app/projects/service.py)
    ↓
Backend adapter (app/projects/v16_adapter.py)
    ↓
v16 API (v16/adapter.py)
    ↓
v16 internals (planning, auditing, Codex runner)

What is Codex?

Codex is an AI CLI tool that v16 uses to perform the actual code analysis. It's an npm package that you give a source directory and a task, and it calls an LLM (via an OpenAI-compatible API) to analyze the code.

v16 orchestrates Codex in two phases:

  1. Planning — Codex reads the repository structure and the threat profile to produce a scan plan: which components to audit and in what order.
  2. Auditing — for each component in the plan, Codex reads the relevant source files and produces findings based on the threat profile.

Each Codex invocation is handled by v16/codex_runner.py. Codex runs as a subprocess. Its stdout is a stream of JSON events that v16 parses.

High-level pipeline

flowchart TD
    A[ProjectService calls\nV16ServiceAdapter.scan_source]
    B[app/projects/v16_adapter.py\nmaps backend objects to v16 inputs]
    C[v16/adapter.py\nvalidates and orchestrates]
    D[Planning step\nCodex analyzes structure and threat profile]
    E[Component selection\npick which files to audit]
    F[Audit step per component\nCodex analyzes code with threat profile]
    G[Emit V16Events\nfinding_updated, scan_progress, scan_completed, etc.]
    H[Backend event sink\napp/projects/v16_adapter.py]
    I[ProjectService\npersist events and findings]

    A --> B --> C
    C --> D --> E --> F --> G --> H --> I
    F --> F

Submodule setup

v16/ is a git submodule. If you've just cloned the repo, you need to initialize it:

git submodule update --init --recursive

If the API fails to import v16.adapter, the submodule isn't initialized. Check with ls v16/ — it should contain Python files, not an empty directory.

What the backend adapter does

app/projects/v16_adapter.py is the glue between the backend domain and the v16 engine:

  • Input mapping — converts backend objects (repository ID, snapshot path, threat profile) into the format v16's scan_source() function expects
  • Event sink — provides a callback function that v16 calls for each event it emits
  • Event mapping — converts raw v16 events into Vega's event and finding format
  • Cancellation — passes a cancellation token to v16 so in-progress scans can be stopped

Pages in this section