.env.example

# =============================================================================
# vulnerator-ai — environment variables template.
# Copy this file to .env and fill in the values. Do NOT put real secrets here.
#   cp .env.example .env
#
# EASIEST PATH: run ./install.sh instead. It only asks for OPENROUTER_API_KEY,
# auto-generates HERMES_API_SERVER_KEY and VULNERATOR_MCP_INBOUND_TOKEN, writes
# this file for you, and brings the default stack up.
# =============================================================================

# --- LLM (OpenRouter) ---------------------------------------------------------
# REQUIRED. This is the SAME OpenRouter key Hermes uses as the LLM provider.
# Hermes reads it directly from this variable (not from HERMES_LLM_API_KEY).
OPENROUTER_API_KEY=

# OPTIONAL. Overrides the OpenRouter model Hermes reasons with. Empty = use the profile
# default (mistralai/mistral-large-4-0, see agent-ooda/profile/config.yaml).
# WARNING: the project deliberately uses Mistral Large because models like Claude (anthropic/*)
# refuse the authorized-offensive pentest framing (the OpenRouter/Anthropic safety filter returns
# "violative cyber content" and does not respond). Overriding with such a model may make the
# agent refuse to work.
#
# FALLBACK AUTOMATICO: Hermes tiene configurado GLM-5.3 Flash (z-ai/glm-5.3-flash) como
# fallback automático en agent-ooda/profile/config.yaml (fallback_providers). Si Mistral Large 4
# falla por rate-limiting (429), server error (500/502/503) o auth failure (401/403), Hermes
# cambia AUTOMATICAMENTE a GLM-5.3 Flash mid-session sin perder contexto. El fallback es
# per-turn: cada mensaje nuevo intenta Mistral de nuevo; si vuelve a fallar, reactiva GLM.
#
# Para cambiar el modelo PRIMARIO manualmente (sin esperar fallo):
#   OPENROUTER_MODEL=z-ai/glm-5.3-flash
#
# GLM-5.3 Flash vs Mistral Large 4:
#   • Mismo Cyber Index (50% ambos)
#   • 20x más barato ($0.07/$0.21 vs $1.36/$4.18 per M tokens)
#   • Probado: end-to-end exploits, 0-days en navegador, caso Hugging Face
#   • Multimodal (screenshots de targets)
#   • CyberGym 84.5% (top), pero NexBench 29/100 (pentesting autónomo largo)
#
# Ver agent-ooda/profile/config.yaml sección fallback_providers para detalles completos.
OPENROUTER_MODEL=

# --- Local/remote Ollama inference (OPTIONAL, opt-in) -------------------------
# Empty = use OpenRouter (default behavior; OPENROUTER_API_KEY is required above).
# Set OLLAMA_BASE_URL to an Ollama OpenAI-compatible endpoint to use Ollama INSTEAD of
# OpenRouter. In that case OPENROUTER_API_KEY is NOT required.
#   - Local Ollama on the host:  http://host.docker.internal:11434/v1
#   - Remote Ollama host:        http://<host>:11434/v1
# On Linux, reaching a host-run Ollama relies on the extra_hosts
# "host.docker.internal:host-gateway" mapping (already set on ooda-agent in docker-compose.yml).
# Also start Ollama listening on all interfaces so the container can reach it: OLLAMA_HOST=0.0.0.0.
OLLAMA_BASE_URL=

# OLLAMA_MODEL: the Ollama model name used when OLLAMA_BASE_URL is set, e.g. qwen2.5-coder:32b.
OLLAMA_MODEL=
# CAVEAT 1 (context window): Hermes refuses to start against an endpoint serving less than
#   ~64K tokens of context, and Ollama defaults to as low as 4K. Raise it SERVER-SIDE when you
#   run Ollama: OLLAMA_CONTEXT_LENGTH=64000 (it cannot be raised via the API).
# CAVEAT 2 (model suitability): the chosen model MUST support reliable tool/function-calling
#   (every pentest action routes through MCP) and must not refuse the authorized-offensive
#   pentest framing. Parity with Mistral-Large-on-OpenRouter is NOT guaranteed; treat local
#   inference as experimental and validate the model before relying on it.

# --- Hermes API server --------------------------------------------------------
# REQUIRED. Key for Hermes' internal API server (min. 8 chars). Generate one with:
#   openssl rand -hex 32
# It is also the Bearer token to drive Hermes over HTTP from an external assistant:
#   Authorization: Bearer <HERMES_API_SERVER_KEY>
HERMES_API_SERVER_KEY=

# OPTIONAL. HOST port where Hermes' OpenAI-compatible API server is published
# (the container's internal port stays 8642). Empty = 8642. You need to publish it
# to drive Hermes from an external assistant (Kiro/Claude) over HTTP without entering the TUI.
# Access is protected by the HERMES_API_SERVER_KEY Bearer; publish the port only in a
# controlled environment. If you don't want to open the port, use 'docker compose exec' (see README).
HERMES_API_HOST_PORT=

# --- Hermes web UIs (dashboard + webapp) --------------------------------------
# OPTIONAL. HOST ports where Hermes' browser UIs are published (container ports stay 9119 / 9120).
# Both sit behind the dashboard sign-in (basic auth admin / vulnerator by default — change it in
# agent-ooda/profile/config.yaml). Empty = defaults (9119 / 9120).
#   - Dashboard (admin panel):                              http://localhost:9119
#   - Webapp (Desktop workspace in a browser, Hermes >=0.23): http://localhost:9120
# If the Webapp bundle is not built yet, build it once with:
#   docker compose exec ooda-agent hermes webapp --no-open
# SECURITY: a signed-in Webapp user can run commands as the account running the no-guardrails
# agent — publish these ports only on a controlled machine (prefer an SSH tunnel / trusted VPN).
HERMES_DASHBOARD_HOST_PORT=
HERMES_WEBAPP_HOST_PORT=

# --- vulnerator-mcp (MCP front door — UP BY DEFAULT in docker-compose.yml) ----
# The vulnerator-mcp service is part of the DEFAULT stack (4th container). It exposes Hermes'
# :8642 runs API as MCP tools so an MCP client (Claude Code / Kiro / BugTraceAI) can drive a
# pentest. Because it comes up by default in streamable-HTTP mode, the token below is REQUIRED.
#
# REQUIRED (the default stack is fail-closed on this). Inbound Bearer that gates the
# clients -> vulnerator-mcp edge. Generate one with:
#   openssl rand -hex 32
# It is a SEPARATE secret from HERMES_API_SERVER_KEY and protects a DIFFERENT edge (it does
# NOT re-protect the :8642 host exposure). The service is FAIL-CLOSED: `docker compose up` will
# abort without it, and every request must carry 'Authorization: Bearer <this>'.
# NOTE: the LOCAL stdio mode for Claude Code / Kiro (`docker run -i …`, see README) needs
# NEITHER this token NOR a host port — it has zero network surface.
VULNERATOR_MCP_INBOUND_TOKEN=

# OPTIONAL. HOST port where the vulnerator-mcp streamable-HTTP server is published. By DEFAULT
# the service publishes NO host port and is reachable only on the internal docker network at
# vulnerator-mcp:8700 (in-docker consumers like BugTraceAI reach it there). To publish on a
# CONTROLLED machine, set this AND uncomment the 'ports:' block of the vulnerator-mcp service
# in docker-compose.yml. WARNING: publishing exposes the no-guardrails engine's trigger API to
# the host; do it deliberately and keep VULNERATOR_MCP_INBOUND_TOKEN secret.
VULNERATOR_MCP_HOST_PORT=

# --- AWS read-only (OPTIONAL) -------------------------------------------------
# Only if you are going to use the cloud collection tools (Prowler/ScoutSuite/Cloudsplaining).
# If you don't use them, leave these variables empty. Use read-only credentials for the account
# you are AUTHORIZED to audit.
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
# Only for temporary credentials (STS).
AWS_SESSION_TOKEN=
AWS_REGION=

# --- Kali MCP port on the host (OPTIONAL) -------------------------------------
# HOST port where the kali-mcp server is published (the container's internal port
# stays 8900). Empty = 8900. ooda-agent reaches kali over the internal network
# (kali:8900) without relying on this; it only matters for inspection from the host.
KALI_MCP_HOST_PORT=

# --- Artifacts channel (OPTIONAL) ---------------------------------------------
# Shared token for the kali container's data channel.
KALI_ARTIFACTS_TOKEN=

# --- Prowler (OPTIONAL) -------------------------------------------------------
# These scope the cloud scan if you use Prowler. Empty = compose defaults.
PROWLER_STATUS=
PROWLER_REGIONS=
PROWLER_SERVICES=
PROWLER_TIMEOUT=

# --- Recon / fingerprint APIs (OPTIONAL) --------------------------------------
# DNSDumpster API key for the `dns_recon` tool (DNS + attack-surface recon: subdomains,
# IPs, ASN/PTR and HTTP/HTTPS banners for a domain). Get a free key from your account at
# https://dnsdumpster.com/ (free tier: 50 records/domain; Plus raises limits + pagination).
# Without it, `dns_recon` fails fail-closed and reports the missing key.
DNSDUMPSTER_API_KEY=

# WPScan API token for the `webtech_scan` tool. OPTIONAL: wpscan enumerates WordPress
# (core/plugins/theme versions) WITHOUT a token; the token only adds known-vulnerability
# (CVE) data to the results. Get one at https://wpscan.com/profile (free tier: 25 req/day).
WPSCAN_API_TOKEN=

# --- Caido (web toolkit: proxy + Replay + HTTPQL + scope + workflows) ---------
# Powers the caido_graphql / caido_request / caido_history tools in kali-mcp (see docs/caido.md).
# The `caido` service (docker-compose.yml) runs the toolkit; kali-mcp reaches it on the internal
# network as http://caido:8080. ZERO-TOUCH BY DEFAULT: the service starts with --allow-guests and
# kali-mcp logs in headlessly (`loginAsGuest`) and picks/creates a project on its own, so with
# the defaults NOTHING in this section needs to be set.
#
# Leave CAIDO_URL empty to use the bundled service, or point it at an external Caido instance
# (e.g. an SSH tunnel to a remote host).
CAIDO_URL=

# OPTIONAL. Only if you use a Caido instance WITHOUT --allow-guests (e.g. an external one, or
# you published the bundled port and removed --allow-guests): a Personal Access Token from the
# Caido GUI (Developer page). Takes precedence over the guest login. CAIDO_ACCESS_TOKEN is the
# shorter-lived (~7 days) GUI session token, used only if CAIDO_PAT is empty.
CAIDO_PAT=
CAIDO_ACCESS_TOKEN=

# OPTIONAL. 0 disables the headless guest login, so ONLY CAIDO_PAT/CAIDO_ACCESS_TOKEN are valid
# (the tools return `unauthenticated` without one). Empty/1 = guest login allowed (default).
CAIDO_ALLOW_GUEST=

# OPTIONAL. 1 = route kali_run's HTTP tool traffic (curl/nuclei/ffuf/sqlmap/wget) THROUGH Caido's
# proxy so it is captured in Caido's history, and install Caido's CA for HTTPS interception. Empty/0
# = off. Only HTTP(S)_PROXY-aware clients are captured (raw-socket tools like nmap are not); kali-mcp's
# own calls to Caido are excluded from the proxy (NO_PROXY) to avoid a loop.
CAIDO_PROXY_CAPTURE=

# OPTIONAL. Caido image. Empty = caido/caido:0.59.0, the release the caido_request/
# caido_history queries were verified against (Caido's GraphQL schema changes between
# releases; the caido_graphql passthrough stays version-agnostic).
CAIDO_IMAGE=

# OPTIONAL tuning (empty = built-in default): per-HTTP-call timeout in seconds (60); cap in
# bytes of the response returned by caido_request (20000); name of the project created when
# the instance has none (vulnerator).
CAIDO_TIMEOUT=
CAIDO_MAX_RESPONSE_BYTES=
CAIDO_PROJECT=

# OPTIONAL. HOST port to publish the Caido GUI/proxy on a CONTROLLED machine (also uncomment
# the caido service 'ports:' block). Empty = 7000. By default NOTHING is published (internal
# docker network only). If you publish it, drop --allow-guests from the service command and use
# CAIDO_PAT: a guest token would be obtainable by anyone who can reach the port.
CAIDO_HOST_PORT=