Scan Engine Overview

The scan engine is vega-core, a stage framework that drives all AI-powered security analysis. vega-backend invokes it through a small, typed API and receives results through structured return values and an event stream.

Responsibilities

Owner	Responsibilities
`vega-backend`	Product state (repos, scans, findings, bugs), SQS queues, Postgres, S3 artifact management, event persistence, dashboard API
`vega-core`	Stage execution, agent orchestration, plugin selection, cancellation, event emission, artifact production

How vega-backend calls vega-core

vega-core is always invoked as a subprocess — the backend never imports it directly. LocalVegaCoreService (in adapters/engine/vega_core/) spawns vega-core/tests/manual/e2e_scan_debug.py with CLI arguments, reads a JSON event stream from stdout, and reads artifact files from the artifact root after the process exits. This subprocess model is used in both local development and ECS production.

Four adapter methods map to subprocess invocations:

Adapter method	`--enabled-stages`	What runs
`run_plan()`	`plan`	Reads source, produces component manifest
`run_threat_model()`	`threat_model`	Generates per-component threat model
`run_audit()`	`audit`	Runs Codex on each component
`run_verification()`	`verify`	Verifies findings, generates patches

Within the subprocess, e2e_scan_debug.py calls vega-core's Python API: plan_repo(PlanRequest), run_scan(ScanRequest), verify_and_patch(VerificationRequest). See the vega-core Contract for both the subprocess interface and the Python API details.

Container roles

Each scan phase runs in its own ECS runner task (vega-scan-runner). The runner executes the appropriate adapter method, which spawns the vega-core subprocess locally:

Runner phase	Adapter method	Engine stage
`plan`	`run_plan()`	PlanStage
`threat_model`	`run_threat_model()`	ThreatModelStage
`audit`	`run_audit()`	AuditStage + SharedTriageService
`verify`	`run_verification()`	VerifyStage + PatchStage

In fast scan mode (enabled by ScanCapacityPolicy), plan → threat_model → audit all run inline in a single vega-scan-runner ECS task, avoiding extra round-trips.

Artifact references (plan artifact, threat model artifact) are passed between phases via S3 URIs stored in scan options.

Stage sequence overview

flowchart TD
    Repo[Repo created] --> Plan[plan_repo → PlanStage]
    Plan --> PA[vega.plan artifact in S3]
    PA --> ScanQ[Scan queued]
    ScanQ --> Plugin[PluginSelectionService]
    Plugin --> TM[ThreatModelStage]
    TM --> Audit[AuditStage]
    Audit --> Triage[SharedTriageService]
    Triage --> Bugs[Deduplicated bugs → backend DB]
    Bugs --> VQ[Verification queued]
    VQ --> Verify[VerifyStage]
    Verify --> Patch[PatchStage]
    Patch --> Artifacts[vega.remediation_results in S3]

Plugin layer

Before running the scan stage sequence, vega-core selects a domain plugin using PluginSelectionService. The selected plugin customizes stage behavior through hooks (prompt sections, schema overrides, static threat models, repro policy, patch policy) without replacing stage code.

Built-in plugins: DefaultPlugin, LinuxPlugin, WebApplicationPlugin.

Shared triage

Raw findings from all scan runners flow through SharedTriageService before backend receives stable bug events. This prevents duplicate bugs when multiple scan containers run concurrently.

Key documentation

Topic	Link
Full vega-core API	Entry Points & API
Contract between backend and core	vega-core Contract
Agent runner (Codex adapter)	Agent Runner
Findings and triage	Findings Persistence
Complete vega-core internals	Vega Core section