Skip to content

Local Scripts

Local scripts are useful during development when you want to run workers, execute a specific scan or ingest job, run migrations, or test Codex container behavior without deploying to AWS.

Scan worker

python scripts/run-scan-worker.py

Starts the long-running scan worker process. Required when VEGA_SCAN_EXECUTION_MODE=external (the API queues scans but doesn't run them). The worker:

  1. Sends heartbeats to track liveness
  2. Runs ReconcileScansUseCase to recover stale scans (stuck running scans where the runner crashed)
  3. Runs RunQueuedScanUseCase to claim and execute the next queued scan — either locally or by launching an ECS task

When to use: any time you want to test the scan pipeline in a realistic multi-process setup.

Scan runner (run one scan manually)

python scripts/run-scan-runner.py <scan_id>
# or
VEGA_SCAN_ID=<scan_id> python scripts/run-scan-runner.py

Runs a single already-queued scan directly, mimicking exactly what the ECS runner task does. The most direct way to debug scan execution without spinning up AWS infrastructure.

The --phase flag controls which phase to run:

Flag Default Description
--phase scan ✓ Full scan (plan + audit)
--phase plan Planning step only
--phase audit Audit step for a specific set of components
--phase verify Verification step for a batch of findings 
# Run the full scan flow
python scripts/run-scan-runner.py abc123 --phase scan

# Run a verification phase manually (matches what ECS does)
python scripts/run-scan-runner.py abc123 \
  --phase verify \
  --finding-ids finding_1,finding_2

The --finding-ids argument (comma-separated, also via VEGA_ASSIGNED_FINDING_IDS env var) seeds the verification phase with specific finding IDs to verify.

When to use: when you have a specific failing scan or verification phase and want to debug its execution with local logging.

Repository ingest worker

python scripts/run-repo-ingest-worker.py

Starts the long-running repository ingest worker process. Required when VEGA_REPO_INGEST_EXECUTION_MODE=sqs (the API queues ingest jobs but doesn't run them). The worker:

  1. Sends heartbeats
  2. Runs ReconcileRepositoryIngestUseCase to recover stale ingest jobs
  3. Runs RunQueuedRepositoryIngestUseCase to claim and execute the next queued ingest job

When to use: when testing the full ingest pipeline in a multi-process setup.

Repository ingest runner (run one ingest manually)

python scripts/run-repo-ingest-runner.py <ingest_job_id>
# or
VEGA_INGEST_JOB_ID=<ingest_job_id> python scripts/run-repo-ingest-runner.py

Runs a single already-queued ingest job directly, mimicking what the ECS ingest runner task does. Downloads or clones source, creates a SourceSnapshot, and transitions the repository to ready.

When to use: when debugging a failing repository ingest without AWS infrastructure.

Repository ingest dispatcher

python scripts/run-repo-ingest-dispatcher.py

A utility that dispatches ingest jobs for repositories that are in a state requiring re-ingest. Useful for bulk operations or recovering from a failed batch.

Database migrations

python scripts/run-db-migrations.py

Applies any pending SQL migrations to the Postgres database configured in VEGA_DATABASE_URL. Safe to run multiple times — it skips migrations that have already been applied.

When to use: after pulling code that contains new migration files, or after switching to a fresh Postgres database.

Maintenance jobs

python scripts/run-maintenance.py
# or for a single run
python scripts/run-maintenance.py --once

Runs maintenance tasks: stale scan reconciliation, cleanup of expired planning artifacts, old session removal, and orphaned record cleanup. Use --once to run all jobs and exit.

When to use: when you want to clean up local state or test that maintenance logic works correctly.

Build Codex runner image

scripts/build-codex-runner-image.sh

Builds the vega-codex-runner:latest Docker image from docker/codex-runner/Dockerfile. This image is used by scripts/codex-in-target-container.sh to run Codex in an isolated Docker sandbox during local scans.

Required before running scans locally if VEGA_CORE_CODEX_BIN is set to the default container script (which it is by default).

When to use: first-time setup, or after changes to docker/codex-runner/Dockerfile.

AWS helper scripts (scripts/aws/)

Script Purpose
build-and-push-images.sh Build Docker images for linux/amd64 and push to ECR
terraform-plan.sh Run terraform plan for an environment
terraform-apply.sh Run terraform apply for an environment
deploy.sh Force-update ECS services to pick up new images
run-migrations.sh Run database migrations via the maintenance ECS task
smoke-test.sh Run the smoke test against the deployed API