This document is the security contract for Infra Pilot. It states who can do what through which interface, what the trust boundaries are, and how to report problems. Pre-1.0 status: there are no tagged releases yet; treat every change as unreleased.

Do not post security issues in public. Email the maintainers instead (the address is in the repository profile / commit history).

Please include:

• What the problem is
• Which component and endpoint are affected
• How to reproduce it
• How severe you think it is

We will: acknowledge within 48 hours, then provide a fix timeline. Critical issues (remote code execution, credential disclosure, auth bypass) get a fix before any other work.

                      ┌────────────────────────────┐
   Public Internet ──▶│ Orchestrator Agent          │
                      │  - webhook server (:8500)   │
                      │  - Discord bot              │
                      └──────┬───────────┬──────────┘
                             │           │
             Docker socket   │           │  HTTP/DB
                             ▼           ▼
                     Containers (VPS)   PostgreSQL / Redis

• Secrets live in environment variables / .env files, never in code or committed files. Placeholders in .env.example are CHANGE_ME.
• The orchestrator refuses to start in production while placeholder secrets are set (fail fast).
• Production requires an explicit POSTGRES_PASSWORD; no hardcoded defaults.
• The secrets manager encrypts values at rest; keys stay out of the repo.
• Gitleaks scans the full git history on every push; npm audit and pip-audit run for dependency CVEs.

• Terraform state contains the RDS password even though it is omitted from outputs. The state bucket requires versioning, default SSE-S3/AES256, blocked public access, and restricted IAM access.
• Production deployment reads infra-pilot-prod-postgres-password from Secrets Manager into infra-pilot-secrets under db-password before Helm runs with secrets.create=false. The deployment role needs secretsmanager:GetSecretValue on that secret, plus kms:Decrypt if a customer managed KMS key is used. Kubernetes access must permit Secret creation and patching in the deployment namespace.
• Provision the other required keys (postgres-password, redis-password, and api-key) in that Secret through your secret manager before deployment. The sync preserves those keys. Passwords must stay out of Helm values, Terraform outputs, and deployment logs.
• Compose node-exporter uses the host network namespace and listens only on the private Docker bridge address configured by NODE_EXPORTER_HOST_IP. Prometheus reaches that address from infra-pilot-net; port 9100 is not bound on public interfaces. This configuration targets Linux Docker hosts.
• Helm allows panel egress and orchestrator ingress on TCP 8500 within the same release. When the panel's token Secret is configured, the Secret and orchestrator-api-token key must exist for the Pod to start.
• Encrypted backups upload only the .gpg artifact to S3. Plaintext may remain locally unless --no-plaintext is set.

Container spawns MUST NOT:

• run with --privileged or --cap-add=ALL
• take image/name/command strings built via string interpolation or a shell
• bypass the per-VPS resource limits
• bind host ports < 1025 (privileged; requires operator override outside the manifest), accept LD_PRELOAD/LD_LIBRARY_PATH/DOCKER_HOST env vars, or pull images outside the optional ALLOWED_IMAGES prefix allow-list

Regression tests assert these properties on every CI run (test_create_vps_never_spawns_privileged_containers, test_container_name_validation_rejects_injection, services/orchestrator-agent/tests/unit/test_hardening_p0.py).

• docker-compose.yml defaults to the production panel image. compose.override.yml (auto-loaded) restores HMR dev servers for local work only. Before running docker compose -f docker-compose.yml up -d in production, change the management-panel port mappings to bind to 127.0.0.1 (for example, 127.0.0.1:3001:3001 and 127.0.0.1:5173:5173). Alternatively, remove the panel's host port mappings and connect the TLS proxy through the Compose network. The unmodified file publishes panel ports on all interfaces. Terminate TLS at the proxy / ingress; Express and the orchestrator must not serve public traffic directly.
• Manifests are strictly validated on the API path (validate(strict=True)): privileged host ports, denied env vars, oversized payloads (MAX_BODY_BYTES, default 256 KiB, 413 on excess) and unbounded maps are rejected with 400/413 before reconciliation.
• /api/* and /webhook/gitops are rate-limited per client IP (429 with Retry-After); limits are intentionally modest on deploy/webhook routes.
• The Docker socket is host-root equivalent. In production never mount /var/run/docker.sock directly — put an allowlisted socket proxy (e.g. tecnativa/docker-socket-proxy) in front and point DOCKER_HOST at it. The direct mount in compose is trusted-dev/lab only.

• Never put passwords or API keys in code. Use environment variables.
• Validate user input; use parameterized database queries everywhere.
• New HTTP endpoints require a guard: HMAC, Bearer token, or RBAC — no "trusted by default" routes.
• New container-spawn code paths must keep the isolation contract above.
• Update SECURITY.md when you change a trust boundary.