.env.example

# ExactSurface configuration. Copy to .env and fill in. All vars are EXACTSURFACE_-prefixed.
# Secrets must NEVER be committed. .env is gitignored.

# -- environment --
EXACTSURFACE_ENV=dev                 # dev | staging | prod
EXACTSURFACE_DEBUG=true

# -- datastore (self-hosted MongoDB by default — free; Atlas is optional) --
EXACTSURFACE_MONGO_URI=mongodb://localhost:27017
EXACTSURFACE_MONGO_DB=exactsurface

# -- redis (task queue + politeness rate-limit buckets) --
EXACTSURFACE_REDIS_URI=redis://localhost:6379/0

# -- auth / crypto (CHANGE THESE IN PROD — startup refuses insecure defaults) --
EXACTSURFACE_JWT_SECRET=dev-insecure-change-me
EXACTSURFACE_JWT_ALGORITHM=HS256
EXACTSURFACE_JWT_TTL_SECONDS=3600
EXACTSURFACE_SECRET_HASH_KEY=dev-insecure-secret-hash-key

# -- scanning politeness / compliance (§3.8b) --
EXACTSURFACE_GLOBAL_RATE_PER_TARGET=10     # max packets/requests per second per target IP
EXACTSURFACE_SCAN_COOLOFF_SECONDS=2
# MUST be >= your real worker replica count. Only used when Redis (the shared
# rate-limit store) is unreachable: each worker then falls back to a local bucket at
# 1/this of the ceiling, so even a full-fleet outage stays within the cap. Set too
# low and a degraded fleet exceeds it — the AUP breach ADR-0012 exists to prevent.
EXACTSURFACE_WORKER_FLEET_SIZE=3
# Cloud asset inventory (optional). Path to a cloudlist provider config listing your
# own AWS/GCP/Azure/DigitalOcean accounts. USE READ-ONLY CREDENTIALS — the module only
# lists resources. The file is read by YOUR deployment and never leaves it; ExactSurface
# has no vendor-side component that could see it.
# EXACTSURFACE_CLOUDLIST_CONFIG=/etc/exactsurface/cloudlist.yaml

# DEV ONLY — allow scanning RFC1918 private IPs (e.g. a local lab VM). Refused in prod.
EXACTSURFACE_LAB_ALLOW_PRIVATE=false

# -- retention (days) --
EXACTSURFACE_RETENTION_FINDINGS_DAYS=730
EXACTSURFACE_RETENTION_RAW_SCAN_DAYS=90
EXACTSURFACE_RETENTION_RAW_SECRET_DAYS=30

# -- worker --
EXACTSURFACE_WORKER_CONCURRENCY=4
EXACTSURFACE_TOOL_DEFAULT_TIMEOUT=300

# -- external API keys (optional; features degrade gracefully if unset) --
# EXACTSURFACE_SHODAN_API_KEY=
# EXACTSURFACE_CENSYS_API_ID=
# EXACTSURFACE_CENSYS_API_SECRET=
# EXACTSURFACE_GITHUB_TOKEN=
# EXACTSURFACE_GOOGLE_CSE_KEY=
# EXACTSURFACE_GOOGLE_CSE_CX=
# EXACTSURFACE_BRAVE_API_KEY=
# EXACTSURFACE_SERPAPI_KEY=

# -- transactional email (signup verification) --
# "log" (default) prints the verification link to the log — no account needed, ideal
# for local dev. Switch to "smtp" and fill the creds below to send real mail. Any
# provider works (they all speak SMTP): Resend (3k/mo free), Brevo (300/day free),
# Amazon SES ($0.10/1k), Postmark, Mailgun.
EXACTSURFACE_EMAIL_TRANSPORT=log
# EXACTSURFACE_EMAIL_FROM=ExactSurface <no-reply@yourdomain.com>
# Public URL of the frontend — verification links are built from it.
EXACTSURFACE_APP_BASE_URL=http://localhost:3000
# Require a verified email before a program can be created. Off in dev, ON in prod.
EXACTSURFACE_REQUIRE_EMAIL_VERIFICATION=false
# -- SMTP (only when EXACTSURFACE_EMAIL_TRANSPORT=smtp) --
# Resend:  smtp.resend.com : 587   user=resend           pass=<api key>
# Brevo:   smtp-relay.brevo.com : 587
# SES:     email-smtp.<region>.amazonaws.com : 587
# EXACTSURFACE_SMTP_HOST=
# EXACTSURFACE_SMTP_PORT=587
# EXACTSURFACE_SMTP_USER=
# EXACTSURFACE_SMTP_PASSWORD=
# EXACTSURFACE_SMTP_STARTTLS=true

# -- observability (§7 Phase G) --
# Each process serves its own in-memory registry; the worker/scheduler expose it
# on this port (the api serves /metrics from its own app). Scraping only the api
# shows HTTP counters and nothing about scanning. See docs/DEPLOYMENT.md.
# EXACTSURFACE_METRICS_ENABLED=true
# EXACTSURFACE_METRICS_PORT=9100
# Errors from every long-running process (api, worker, scheduler). Optional —
# omit and Sentry stays off. PII is never sent.
# EXACTSURFACE_SENTRY_DSN=
# Grafana admin password for the compose stack. CHANGE before exposing Grafana —
# it can query every metric the platform emits. (Not EXACTSURFACE_-prefixed: it is read
# by the grafana container, not by Settings.)
# GRAFANA_ADMIN_PASSWORD=admin

# -- backups (§7 Phase G, §9 retention) --
# age PUBLIC key (age1...) generated with `age-keygen`. Encrypt-only: this host can
# write backups and CANNOT read them, so compromising it does not yield the backup
# history. Keep the identity (private) file OFF this host. Prod refuses to write an
# unencrypted backup of customer attack-surface data without this.
# EXACTSURFACE_BACKUP_AGE_RECIPIENT=age1...
# EXACTSURFACE_BACKUP_DIR=./backups
# EXACTSURFACE_BACKUP_RETENTION_DAYS=30

# -- scope-feed auto-update (§7 Phase G, ADR-0014) --
# The scheduler refreshes the shared Mongo copy of the CDN/cloud range feed this
# often (hours). Provider ranges change slowly, so daily is ample. 0 disables it —
# then cron `python -m scripts.update_scope_feeds` yourself. Workers load the feed
# at startup, so a refresh applies on their next (rolling) restart.
# EXACTSURFACE_SCOPE_FEED_REFRESH_HOURS=24

# -- prod compose only (docker-compose.prod.yml) --
# These are read by the compose file itself, NOT by Settings (no EXACTSURFACE_ prefix).
# Required by the prod stack; unused by the dev stack.
# DOMAIN=exactsurface.example.com            # Caddy obtains a TLS cert for this
# MONGO_ROOT_USER=exactsurface
# MONGO_ROOT_PASSWORD=                   # strong; applied on first mongo init only
# REDIS_PASSWORD=                        # strong; enables redis requirepass
# GRAFANA_ADMIN_PASSWORD=                # required — compose errors if unset

# -- api CORS (prod only; dev allows localhost:3000 automatically) --
# Comma-separated origins allowed to call the API cross-origin in prod. Leave unset
# for the shipped stack (frontend + API are same-origin behind one proxy — no CORS
# needed). Set ONLY for a split-origin deploy. NEVER "*" with credentials.
# EXACTSURFACE_CORS_ALLOWED_ORIGINS=["https://app.yourdomain.com"]