Glossary
Quick definitions for terms used throughout the codebase and documentation.
Product terms
Project
The top-level workspace container. A project holds one or more repositories, all their scans, and all the findings those scans produced. Think of it as a folder that groups related security work.
Repository
A source code target inside a project. Users add a repository by providing a Git URL or uploading a zip archive. The backend fetches the source, stores a snapshot, and associates scans and findings with this repository.
Snapshot
An immutable capture of a repository's source code at a specific point in time. Scans run against snapshots, not live Git branches, so the scan result is always tied to a known state of the code.
Threat profile
A structured description of what the application does and which risks matter most for it (e.g., "This is an API that handles payments and stores user PII — focus on injection, auth bypass, and data exposure"). The scan engine uses the threat profile to focus its audit.
Scan
A single audit run over selected paths in a repository snapshot. A scan goes through states: queued → claimed → running → completed (or failed / cancelled).
Finding
A specific security issue discovered during a scan. Each finding has a severity, a title, a file location, and evidence from the scan engine. Findings are durable records — they survive after the scan finishes.
Event
A time-ordered log record emitted during a scan. Events carry progress updates, log lines, warnings, and finding notifications. The frontend uses events to show live scan progress.
Service terms
vega-api
The FastAPI HTTP service. It handles all user-facing requests: authentication, project/repository management, scan creation, and reading findings and events.
vega-worker
A background process that watches SQS for scan jobs. When it receives one, it claims the scan in the database and either runs it locally or launches a vega-v16-runner ECS task.
vega-v16-runner
An isolated container that runs exactly one scan and then exits. It downloads the source snapshot from S3, runs the v16 scan engine, writes findings and events to the database, and uploads artifacts to S3.
vega-llm-proxy
An internal proxy between scan runners and the AI provider (e.g., OpenAI). Runners never hold the raw provider API key — they get a short-lived scan-scoped token from the proxy. The proxy enforces per-scan usage limits.
vega-maintenance
A task definition for one-off jobs: running database migrations, cleaning up stale artifacts, etc.
v16
The scan engine submodule. It takes a source root and a threat profile, plans which parts of the code to audit, runs Codex (an AI CLI tool) on each component, and streams events back to the backend.
Infrastructure terms (AWS)
VPC (Virtual Private Cloud)
A private network inside AWS. All Vega services run inside a VPC so they can talk to each other without being exposed to the internet.
Subnet
A section of a VPC, scoped to one availability zone. Public subnets can receive internet traffic (API load balancer). Private subnets are for internal services (worker, runner, database, LLM proxy).
Security group
An AWS firewall attached to a resource. Security groups control which services can talk to which others. For example, the database only accepts connections from application task security groups, not from the internet.
ECS (Elastic Container Service)
AWS's container orchestration service. Vega runs all its backend services as Docker containers managed by ECS.
Fargate
The serverless compute runtime for ECS. With Fargate, you don't manage EC2 instances — you just tell ECS how much CPU and memory a container needs, and AWS handles the rest.
ECR (Elastic Container Registry)
AWS's Docker image registry. Vega builds Docker images locally and pushes them to ECR. ECS pulls images from ECR when starting containers.
SQS (Simple Queue Service)
AWS's managed message queue. The API sends a scan job message to SQS when a scan is created. Workers consume messages from SQS to claim and execute scans.
RDS / Aurora Postgres
AWS's managed relational database service. Vega uses a Postgres-compatible RDS instance to store projects, repositories, scans, findings, and operational state.
S3 (Simple Storage Service)
AWS's object storage. Vega uses S3 buckets to store source snapshots (code zips), scan artifacts (reports, debug bundles), and the built frontend files.
CloudWatch
AWS's logging, metrics, and alerting service. Every ECS container logs to a CloudWatch log group. When debugging AWS deployments, CloudWatch logs are the primary source of truth.
Secrets Manager
AWS's encrypted secret storage. Database credentials, API keys, and provider keys are stored in Secrets Manager and injected into ECS containers at runtime.
Cognito
AWS's managed user authentication service. In production, Vega stores users in a Cognito user pool. Users sign in through the frontend, which calls Cognito and receives a JWT. The backend validates that JWT on every protected request.
CloudFront
AWS's CDN (Content Delivery Network). The frontend static files are uploaded to S3, and CloudFront serves them to users from edge locations worldwide. CloudFront also routes /v1/* API calls to the backend load balancer.
Terraform
An infrastructure-as-code tool. Instead of manually creating AWS resources through the console, Vega defines them in .tf files under infra/terraform/. Terraform applies those files to create or update the actual AWS resources.