Skip to content

Vega Core

vega-core is the scan engine that drives all AI-powered analysis in the Vega platform. It is a small, explicit stage framework — not a collection of ad-hoc scripts. Each analysis step is a typed stage. All common behavior (lifecycle events, cancellation, artifact access, agent calls, error mapping, plugin hooks) belongs to the framework; stages implement only their own logic.

Role in the system

flowchart LR
    backend[vega-backend] -->|PlanRequest| core[vega-core]
    backend -->|ScanRequest| core
    backend -->|VerificationRequest| core
    core -->|CoreResult| backend
    core -->|CoreEvent stream| backend
    core --> s3[(S3 artifacts)]
    core --> agent[Agent / Codex]

vega-backend owns product state: repositories, scans, findings, queues, and the database. vega-core owns analysis: stage execution, agent orchestration, cancellation, event emission, and artifact production.

Three public operations

Entrypoint Purpose
plan_repo(PlanRequest) Read a source snapshot, produce a vega.plan artifact
run_scan(ScanRequest) Select a plugin, run threat modeling and auditing, send raw findings to shared triage
verify_and_patch(VerificationRequest) Verify deduplicated bugs and produce patch artifacts

All three return a typed CoreResult and emit CoreEvent values through the caller-supplied event sink.

Stage sequence

flowchart TD
    A[plan_repo] --> B[PlanStage]

    C[run_scan] --> D[PluginSelectionService]
    D -->|plugin chosen| E[ThreatModelStage]
    E --> F[AuditStage]
    F --> G[SharedTriageService]
    G --> H[CoreResult + bug events]

    I[verify_and_patch] --> J[VerifyStage]
    J --> K[PatchStage]
    K --> L[CoreResult + patch artifact]

Stage sequences and their inter-stage data handoffs are owned by StageOrchestrator and concrete SequenceTransition implementations — not by the stages themselves.

Package layout

src/
  api/          # plan_repo, run_scan, verify_and_patch entrypoints + request/result types
  framework/    # BaseStage, RunContext, PipelineState, RunPolicy, SequenceTransition
  orchestrator/ # StageOrchestrator + workflow wiring
  stages/       # Concrete stage implementations (plan, threat_model, audit, verify, patch)
  plugins/      # Plugin protocol, registry, resolver, PluginSelectionService, built-ins
  agents/       # AgentRunner, AgentAdapter protocol, CodexAdapter, FakeAgentAdapter
  artifacts/    # ArtifactRef, LocalArtifactStore, S3ArtifactStore
  events/       # CoreEvent, EventBus, EventSink
  triage/       # SharedTriageService, RawFindingBatch, DeduplicatedBugBatch
  services/     # Service protocol re-exports used by RunContext
  runtime/      # RuntimeConfig.from_env(), build_runtime_services()
  source/       # SourceView, path normalization helpers
  testing/      # FakeAgentAdapter, test fixtures

Framework design principles

  • Thin stages. Stages implement execute(context, input) and declare artifact requirements. They do not reimplement cancellation, event emission, plugin dispatch, or raw subprocess management.
  • Typed artifacts. Stages exchange ArtifactRef values. Whether the backing store is local disk or S3 is invisible to stage code.
  • Plugin hooks, not forks. Domain customizations (Linux kernel, web application) are plugins that inject prompt sections, schema overrides, and policy — not separate stage classes.
  • Provider-neutral agents. AgentRunner selects from registered adapters. Codex is one adapter behind a stable interface.
  • Shared triage. Raw findings from parallel audit workers flow through one SharedTriageService to produce stable deduplicated bugs.

Reading guide

Topic Where
Package structure Package Architecture
Public API and request types Entry Points & API
Orchestrator and stage sequences Orchestrator & Pipeline
PlanStage Plan Stage
Threat model stages Threat Model Stage
Audit stages Audit Stage
VerifyStage Verify Stage
PatchStage Patch Stage
RunPolicy and env vars Configuration
Stage-owned prompts Prompt System
AgentRunner and CodexAdapter Agent Runner
Plugin system Plugin System
CoreEvent and EventBus Event System
CancellationManager Cancellation
SharedTriageService and findings Findings & Triage
ArtifactRef and stores Artifact Store
Bug class taxonomy Bug Class Taxonomy
Test structure Testing