Configuration

How configuration is loaded#

You configure Vectasec through environment variables. The engine (API and worker), the console and the collector each read their own set, and the connections you add carry their own settings.

The engine loads a .env file only from its two entry points: the vectasec CLI, which includes vectasec worker, and the engine API's bundled entry point. It uses the nearest .env at or above the working directory, and a variable already set in the environment always wins. Start the API with its bundled entry point rather than bare uvicorn. That entry point reads the file and applies ENGINE_HOST and ENGINE_PORT, and bare uvicorn does neither. Write plain NAME=value lines: the loader ignores lines with an export prefix and keeps quotes and trailing comments as part of the value.

The collector never reads .env. Its settings come only from its own environment and the files you point it at, so a stray file cannot change its TLS verification.

A minimal engine environment for a real deployment looks like this. Replace every placeholder and supply the secrets from your secret store.

DATABASE_URL=postgresql://USER:PASSWORD@HOST:5432/postgres
SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
VECTASEC_ENGINE_TOKEN=REPLACE_WITH_A_LONG_RANDOM_SECRET
VECTASEC_ENGINE_TOKEN_TENANT=YOUR_TENANT_UUID
VECTASEC_COLLECTOR_TOKEN_SECRET=REPLACE_WITH_A_SEPARATE_RANDOM_SECRET

Engine settings#

Core#

The repository's root .env.example also sets KAFKA_BOOTSTRAP=localhost:9092 for the local dev stack. No scan reads it today, so pass the broker address with --bootstrap or the console form.

Authentication#

Every API route except GET /health and the /collector/* routes needs the service token or a Supabase user JWT. Collectors authenticate separately, with an enrollment token and then a short-lived collector token. Bare X-VectaSec-* headers are trusted only in dev mode, and a request with no token gets 401. See Security model for how tenants and roles are resolved.

AI triage#

AI triage is optional and runs when you triage a finding. Any one key enables it. Providers are tried in the order Anthropic, OpenAI, Gemini, and an unavailable model hands off to the next entry. With every key unset, a deterministic rule-based summary runs locally and nothing is sent to a model provider.

Vulnerability feeds#

After each scan that the engine or worker runs, the engine asks OSV (api.osv.dev) and NVD about the component versions it found. Results that a collector pushes are stored as sent and are not enriched from these feeds today. For the three switches below, any non-empty value turns the switch on, so set them to 1 or leave them unset.

Each run makes at most 25 NVD requests. Components past that budget are named in a not-assessable coverage-gap finding rather than skipped silently. An unreachable feed files the same kind of finding. On an air-gapped engine, set both VECTASEC_OSV_DISABLED and VECTASEC_NVD_DISABLED. A disabled feed is recorded as your choice and files no gap findings.

Notifications#

Destinations (Slack, Teams, webhook, email, Jira and SIEM) are configured per tenant in the console under Settings, Integrations. These engine variables are operator-level. See Compliance, reports and alerts.

Console settings#

The console reads its own .env.local. Next.js does not read the repository root .env, so the console gets only the variables you put there. Its .env.example lists the Supabase and email values. Add VECTASEC_ENGINE_TOKEN, and VECTASEC_ENGINE_URL if the engine is not at the default address.

The console must never receive SUPABASE_SERVICE_ROLE_KEY or DATABASE_URL. Both bypass RLS, and tenant isolation in the console depends on it reading as the authenticated role.

Collector settings#

Target credentials in the targets file can be written as ${VAR} and are filled from the environment at load, so the file itself holds no secrets. A reference to an unset variable is a boot error. Run vectasec-collector check to validate the configuration and print the redacted targets without contacting anything. The console and API do not mint enrollment tokens yet. See Run a collector in your network.

Connection settings#

Each connector declares its own fields and marks which are required and which are secret. GET /connectors returns those declarations. The console form, the CLI and POST /connections all reject a connection that is missing a required field. Secret fields are split out and stored as one Supabase Vault secret per connection, then merged into the config in memory only at scan or test time. The Vault secret is deleted in the same transaction as its connection.

The CLI has named flags for the common fields (--bootstrap, --url, --host, --port, --token, --admin-token, --username, --password). Anything else a connector reads passes through with --set key=value, which you can repeat. Values arrive as strings, and knob names vary by connector. The CLI connects to the database directly through DATABASE_URL, and without --tenant it writes to the built-in demo tenant. Run these from the engine directory of the release:

uv run vectasec connections add --type kafka --name prod-kafka \
  --bootstrap broker-1:9092,broker-2:9092 --set timeout=30 --tenant YOUR_TENANT_UUID
uv run vectasec connections test prod-kafka --tenant YOUR_TENANT_UUID

PATCH /connections/{id} sets scan_interval_minutes to null (unscheduled) or a value from 5 to 10080. Where the pg_cron extension is installed, as it is on Supabase, a job runs every minute and queues scans for active connections that are due. A collector-mode connection is scanned by an enrolled collector using the credentials in its own targets file, so the connection name must match a target name in that file. The job the collector receives names the target and carries no host or credential.

Every connector's fields are listed in the Connector reference.

Related pages#

• Quick start: the minimum settings for a first scan.
• Deployment: running the engine, worker, console and collector.
• Security model: authentication, roles and the credential boundary.
• CLI and API reference: every command and route.