Deployment Hardening

Concrete hardening artifacts and how to apply them

Deployment Hardening Guide

This page covers three concrete hardening artifacts and how to apply them. For enterprise-readiness context (key management, compliance posture, signer rotation), see Enterprise Readiness.

---

Background

QTG is a self-hosted movement control plane. The operator deploys the stack; the copy-and-run scripts below are the security posture.

The foundational threat model is in DB Access Control Boundary: the accepted boundary is “DB-write = game over.” The controls here do not eliminate that boundary — they shrink blast radius and raise the attacker’s effort floor.

---

Artifact 1: Least-Privilege DB Role

File: infra/sql/qtg_least_privilege_role.sql

What it does

Creates a qtg_app PostgreSQL role that can only do what the runtime application needs:

• SELECT / INSERT / UPDATE / DELETE on all app tables in public (global bucket) and qtg_network (per-network bucket)
• USAGE + SELECT on sequences (required for SERIAL / GENERATED columns)
• Cannot execute DDL (CREATE, ALTER, DROP, TRUNCATE)
• Cannot manage roles (NOCREATEROLE, NOINHERIT)
• Cannot access schemas it does not own

The DDL-owner role (qtg) remains separate and is used only by Alembic migrations — never in the runtime app. This maps directly to DB Access Control Boundary § Proportionate investment, item 1.

Schema layout

Physical schema	Alembic bucket	Contains
public	global	api_clients, api_client_keys, nonce_registry, version tables
qtg_network	mainnet or testnet	All movement, executor, signer, audit tables

How to apply

# 1. Apply as superuser / DDL owner (once per DB):
psql "$MG_DATABASE_URL" -f infra/sql/qtg_least_privilege_role.sql

# 2. Set a strong password for the new role (do not commit password):
psql "$MG_DATABASE_URL" -c "ALTER ROLE qtg_app LOGIN PASSWORD '<strong-random>';"

# 3. Update the app DATABASE_URL to use qtg_app:
#    MG_DATABASE_URL=postgresql+asyncpg://qtg_app:<password>@host:5432/qtg_v3

Adding new tables

When a new Alembic migration adds a table, add a corresponding GRANT ... ON TABLE ... TO qtg_app in the SQL file (or rely on the ALTER DEFAULT PRIVILEGES clause at the bottom of the script, which auto-grants for tables created by the qtg DDL role going forward).

Future hardening

The audit tables (movement_events, registry_audit_events, etc.) currently receive full DML. A future pass can add an audit_writer role that has INSERT-only access, so the runtime app cannot rewrite audit history even if compromised.

---

Artifact 2: Hardened Compose Overlay

File: infra/docker-compose.hardened.yml

What it does

A Docker Compose overlay that tightens every service in the base compose without modifying it. Use it by passing both files to docker compose:

docker compose \
  -f infra/docker-compose.yml \
  -f infra/docker-compose.hardened.yml \
  up -d

Controls applied per service:

Control	postgres	qtg-mainnet	qtg-testnet	ccip-sidecar	qtg-dashboard
Non-root user	999	1000	1000	1000	101
read_only: true	—	yes	yes	yes	yes
cap_drop: [ALL]	yes	yes	yes	yes	yes
Minimal cap_add	CHOWN/FOWNER/SETUID/SETGID/DAC_OVERRIDE	—	—	NET_ADMIN	—
no-new-privileges:true	yes	yes	yes	yes	yes
tmpfs for writable scratch	/tmp, /var/run/postgresql	/tmp, /app/.cache	same	/tmp	/tmp, /var/cache/nginx, /var/run
CPU limit	2	2	2	1	0.5
Memory limit	512M	512M	512M	256M	64M

Notes:

• postgres does not get read_only: true because the official postgres image writes to paths in the container root that vary across patch releases. Capability tightening and no-new-privileges still apply.
• ccip-sidecar retains NET_ADMIN because the base compose already adds it for network namespace operations.
• The Python app containers (qtg-mainnet, qtg-testnet) write nothing to the root filesystem at runtime; read_only: true is safe.
• The user: "1000:1000" directive takes effect once the Dockerfile creates the user. Add RUN adduser --uid 1000 --disabled-password --gecos "" qtguser && chown -R qtguser /app to infra/Dockerfile before running hardened mode in production.

Why not modify the base compose?

The base compose works for local development without hardening overhead. The overlay pattern lets developers run the base compose without friction and deploy hardened compose in staging/production without maintaining two diverging files.

---

Artifact 3: Local Dependency Audit Gate

File: scripts/security_audit.sh

What it does

A local shell script that:

1. Lockfile-drift check — runs uv lock --check to verify uv.lock is in sync with pyproject.toml. A drifted lockfile means the running app may not use the versions you pinned.
2. CVE scan — runs uvx pip-audit against the exported locked dependency set. Fails non-zero if any known, non-ignored CVE is found.

How to run

bash scripts/security_audit.sh

Or add to a Makefile:

security-audit:
    @bash scripts/security_audit.sh

Why local-only (not a CI workflow)?

GitHub Actions CI is disabled until release (workflows switched to workflow_dispatch in commit 82a80a0e). The script is the gate. Run it:

• Before every uv lock refresh (catch newly disclosed CVEs)
• Before releasing to staging/production
• After adding/bumping a dependency

Accepting a false-positive CVE

If pip-audit flags a CVE that you have assessed and accepted (e.g., only affects a code path you do not use, or is disputed), add it to the IGNORED_VULNS map in the script:

# In scripts/security_audit.sh, in the IGNORED_VULNS block:
IGNORED_VULNS["PYSEC-YYYY-NNN"]="Reason — assessed YYYY-MM-DD by <who>"

Do not add to the ignore list without a documented rationale.

Current CVE floor

The pyproject.toml already sets explicit security floors from the 2026-06-10 audit:

Package	Floor	CVE(s) covered
PyJWT	>=2.13.0	H3: 4 CVEs incl. C:H/I:H on JWT auth path
starlette	>=1.0.1	H2: CVE-2026-48710 (Host header → path pollution)
urllib3	>=2.7.0	H4: CVE-2026-44431 (redirect header leak) + CVE-2026-44432 (decomp bomb)

The audit script enforces that a uv lock refresh cannot silently drop below these floors.

---

Applying Everything Together (Quick-Start)

# 1. DB least-privilege role (one-time)
psql "$MG_DATABASE_URL" -f infra/sql/qtg_least_privilege_role.sql
psql "$MG_DATABASE_URL" -c "ALTER ROLE qtg_app LOGIN PASSWORD '$(openssl rand -base64 32)';"
# Update MG_DATABASE_URL in .env to use qtg_app

# 2. Run the local security audit gate
bash scripts/security_audit.sh

# 3. Start the stack with hardening overlay
docker compose \
  -f infra/docker-compose.yml \
  -f infra/docker-compose.hardened.yml \
  up -d

---

Cross-References

• Threat model: DB Access Control Boundary
• Enterprise readiness (key management, compliance): Enterprise Readiness
• Security audit (prior wave): commit f122b3bd (H1–H5 secure defaults, dep CVE floors, dashboard opt-out gating)