docs/SECURITY.md

SECURITY — arac-hasar-v2

Owner: Security Engineer Scope: pilot-production. Stores customer PII (vehicle images, user emails) and produces damage / cost estimates that may flow into invoice / claim workflows.

---

1. Threat Model

1.1 System overview

Layer	Component	Notes
Edge	TLS terminator (Render / Cloudflare / nginx)	HTTPS only; no plaintext listener in prod
API	FastAPI (services/backend)	JWT-authenticated REST + WebSocket; this document covers it
ML	YOLO inference service (services/ml)	Internal; reachable only from backend
Storage	PostgreSQL (managed), Redis (rate-limit + pubsub), S3/MinIO (images)	Network-isolated; no public exposure
Clients	Next.js web, Tauri 2 desktop, React Native mobile	All consume the same API

1.2 Trust boundaries

Public Internet
   |  (TLS)
[Edge / CDN]
   |  (private network)
[FastAPI]
   |  (private network, IAM)
[Postgres]  [Redis]  [S3]  [ML service]

Every arrow crossing a boundary is an authentication checkpoint.

1.3 Sensitive data inventory

Data	Classification	Where it lives	Controls
User email	PII	Postgres users.email, access logs (redacted on auth paths)	TLS in transit; encrypted-at-rest (managed Postgres)
Password	secret	Postgres users.password_hash (bcrypt cost 12)	Never logged; never returned
Vehicle images	PII (may contain plates, faces, location via EXIF)	S3 bucket	EXIF stripped on upload; private bucket; signed URLs only
JWT access/refresh	secret	Client-held; never persisted server-side	Short TTL (30 min / 7 d); HS256 signed
API keys (pilot integrations)	secret	Postgres api_keys.key_hash (sha256)	Shown plaintext once on issue; revocable
ML inference results / cost estimates	business data	Postgres + S3 reports	Tenant isolation enforced at handler

1.4 STRIDE summary

Threat	Vector	Risk	Mitigation
Spoofing	Stolen credentials, token replay	High	Bcrypt cost 12, short access-token TTL, refresh rotation (TODO: backend wire), per-route rate limits on /auth/login
Tampering	Modified upload, tampered cost estimate	Med	Server-side decode + revalidation of images; cost computed server-side from cost_table.yaml; never trust client-supplied totals
Repudiation	"I never uploaded that" / "I never approved that estimate"	Med	Structured JSON access log w/ request_id, user_id, sha256 of uploaded image
Information disclosure	IDOR on /api/v1/inspect/{id}, EXIF GPS leak	High	Mandatory ownership check pattern (section 3); EXIF stripped before storage
Denial of Service	Image bomb, hot loop on /inspect, brute-force login	High	20 MB cap, decompression-bomb guard (Image.MAX_IMAGE_PIXELS), slowapi limits
Elevation of privilege	role claim tampering, missing admin check	Crit	JWT signature verification; require_admin dependency; role re-read from DB on refresh

1.5 Out of scope (for now)

• Multi-region failover
• DDoS at the transport layer (delegated to CDN)
• Hardware security modules / KMS-managed JWT signing keys (flagged for production-scale)
• SSO / SAML (pilot uses local accounts + API keys)

---

2. OWASP Top 10 (2021) — Mitigations

A01 — Broken Access Control

• Every protected route depends on require_user (or require_admin).
• IDOR pattern is mandatory; see section 3.
• WebSocket connections must authenticate within 5 s of accept() (Backend Architect owns the WS handler — flagged in section 6).
• Default policy is deny: a route without an explicit auth dependency is treated as a review failure.

A02 — Cryptographic Failures

• Passwords: bcrypt (passlib), cost factor 12, BCRYPT_ROUNDS env-tunable.
• JWT: HS256 (acceptable for monolithic backend; migrate to RS256 if signing moves to a separate service).
• API keys: 256 bits of entropy, prefixed ahv2_, stored as sha256 hash, compared with hmac.compare_digest.
• Secrets exclusively via env vars; .env is gitignored.
• TLS terminated at edge; HSTS sent in staging/prod by SecurityHeadersMiddleware.
• No custom crypto. Period.

A03 — Injection

• SQL: SQLAlchemy ORM + parameterized text() for any raw SQL. Never f-string user input into queries. Reviewed in PR template.
• Command: no subprocess with shell=True. Image processing stays in-process (PIL).
• Path: sanitize_filename strips .., backslashes, control chars, and prefixes a uuid4. S3 keys are never user-supplied raw.
• Header: request IDs whitelisted to [A-Za-z0-9_-], capped at 128 chars (CRLF injection guard).

A04 — Insecure Design

• Threat model (section 1) reviewed before each release.
• Cost estimates computed server-side from cost_table.yaml; clients cannot override.
• Refresh tokens carry role="user" by design — privilege is re-derived from the DB on refresh so a leaked refresh token cannot escalate.

A05 — Security Misconfiguration

• _validate_config() hard-fails at import time if JWT_SECRET_KEY is < 32 chars in staging/production.
• Default-deny CSP (default-src 'none') on all API responses.
• CORS allowlist (ALLOWED_ORIGINS); allow_credentials=False because we use bearer tokens, not cookies.
• Server header stripped.
• Debug / docs (/docs, /redoc) must be disabled in production (flagged for Backend Architect — see section 6).

A06 — Vulnerable & Outdated Components

• requirements.txt is the canonical lock; CI must run pip-audit (or trivy fs) on every PR.
• Renovate / Dependabot recommended for weekly updates.

A07 — Identification & Authentication Failures

• /auth/login rate-limited to 5/min per IP via slowapi.
• Generic error messages on bad credentials ("invalid email or password") — no user enumeration.
• Access tokens: 30 min. Refresh tokens: 7 d, single-use rotation (Backend Architect to implement jti blocklist in Redis — section 6).
• Password requirements (length / complexity) are owned by the user model layer (Database Optimizer) — flagged.

A08 — Software & Data Integrity Failures

• Pinned dependencies in requirements.txt.
• Container images built from pinned base + reproducible build.
• ML model weights checksummed at load time (Backend Architect owns ml_service.py — flagged in section 6).

A09 — Security Logging & Monitoring Failures

• AccessLogMiddleware emits structured JSON: ts, method, path, status, duration_ms, user_id, request_id, ip, ua.
• Auth paths (/auth/*, /login, /token, /refresh, /password) suppress query string from logs.
• Request bodies are never logged.
• Bcrypt / JWT failures log at INFO with reason class only, never the input.
• Recommend shipping access log to a SIEM / log aggregator (Loki / CloudWatch) with retention >= 90 days.

A10 — Server-Side Request Forgery (SSRF)

• The backend never fetches user-supplied URLs.
• Image uploads are received as multipart bytes — no fetch-by-URL path exists.
• If a "fetch from URL" feature is added later, it MUST:
  1. Resolve DNS server-side once and reject private / link-local ranges.
  2. Disallow redirects to private ranges.
  3. Run in a dedicated egress-restricted network namespace.

---

3. Authorization pattern (mandatory)

Every endpoint that touches a tenant-scoped resource MUST follow this shape:

from fastapi import APIRouter, Depends, HTTPException, status
from security import require_user, TokenPayload

router = APIRouter()

@router.get("/api/v1/inspect/{inspection_id}")
async def get_inspection(
    inspection_id: UUID,
    user: TokenPayload = Depends(require_user),
    db: AsyncSession = Depends(get_db),
):
    row = await db.get(Inspection, inspection_id)
    if row is None:
        # 404, not 403, to avoid leaking existence
        raise HTTPException(status.HTTP_404_NOT_FOUND)
    if row.user_id != user.user_id and user.role != "admin":
        # IDOR check. Same 404 to prevent enumeration.
        raise HTTPException(status.HTTP_404_NOT_FOUND)
    return row

Rules:

1. Always check ownership before returning a row.
2. Always return 404, never 403, when the user isn't the owner (no existence oracle).
3. Admin override goes through user.role == "admin", never a query param.
4. Bulk endpoints (e.g. GET /api/v1/inspect) MUST filter WHERE user_id = :uid in the query — never in Python.

---

4. File upload pipeline

multipart bytes
   -> validate_image_upload(buf)
        size cap (20 MB)
        magic-byte MIME sniff (jpeg / png / webp only)
        PIL decode + verify()
        decompression-bomb guard
        EXIF orientation applied
        EXIF metadata stripped (PII: GPS, camera serial, timestamps)
        dimension cap (10000 x 10000)
   -> sanitize_filename(orig_name)
   -> upload to S3 with server-generated key
        Content-Type forced to sniffed MIME
        bucket policy: private, no public-read
        served via short-lived presigned URLs

Hard rules:

• Never trust client-supplied Content-Type.
• Never store the raw user-supplied filename as the S3 key.
• Never serve images from a domain that can execute scripts (use a separate static / signed-URL domain).
• S3 bucket policy must deny *:GetObject to the public.

---

5. CSRF

The API is bearer-token only (Authorization: Bearer <jwt>). Browsers do not automatically attach Authorization headers cross-origin, so the classic CSRF vector (auto-submit a form, browser attaches cookie) does not apply.

This is enforced by:

• allow_credentials=False on CORS.
• No Set-Cookie issued anywhere in the backend.
• Tight ALLOWED_ORIGINS.

If cookie-based sessions are ever introduced (e.g. SSR Next.js with httponly cookies), CSRF tokens become mandatory — flagged in section 6.

---

6. Open items for follow-up (NOT owned by Security)

Items below are flagged for the corresponding owner; Security has not modified those files.

#	Item	Owner	Severity
1	Refresh-token rotation: persist used jti in Redis with TTL = refresh lifetime; reject reuse	Backend Architect	High
2	Disable /docs and /redoc in production (docs_url=None when ENVIRONMENT=production)	Backend Architect	Med
3	WebSocket auth: enforce JWT within 5 s of accept(), close 4401 otherwise	Backend Architect (ws.py)	High
4	Password policy (min 12 chars, breach check via HIBP k-anonymity) at registration	Database Optimizer (models.py) + Backend Architect (handler)	Med
5	ML weights integrity: sha256 manifest verified before load in ml_service.py	Backend Architect	Med
6	S3 bucket policy review: confirm BlockPublicAcls, IgnorePublicAcls, BlockPublicPolicy, RestrictPublicBuckets all true; encryption at rest enabled	Backend Architect (storage.py) + Infra	High
7	Audit log: separate immutable stream for security events (login success/failure, role change, api-key issue/revoke)	Backend Architect	Med
8	Secret rotation runbook (JWT key, DB password, S3 keys)	Infra / Ops	Med
9	Penetration test before GA (target: OWASP ASVS L2)	External	High
10	KMS-managed JWT signing (migrate HS256 -> RS256/EdDSA) at scale	Backend Architect	Low (deferred)
11	CI security gates: pip-audit, gitleaks, semgrep on every PR	DevOps	High
12	Brute-force / credential-stuffing detection beyond simple rate limit (e.g. account lockout after N failures with cool-down)	Backend Architect	Med

---

7. Deploy checklist

Before tagging a release that goes to staging or production:

• JWT_SECRET_KEY is set, >= 32 chars, unique per environment.
• ENVIRONMENT set to staging or production (enables HSTS + strict config validation).
• ALLOWED_ORIGINS populated with the exact production origins.
• RATE_LIMIT_REDIS_URL points to a managed Redis (not memory://).
• BCRYPT_ROUNDS=12 (or higher; benchmark target ~250 ms per hash on prod CPU).
• /docs and /redoc disabled.
• Postgres / Redis / S3 reachable only over private network.
• S3 bucket: private, encryption-at-rest, lifecycle rule to purge after retention window.
• TLS cert valid; HSTS preload submitted if appropriate.
• pip-audit and gitleaks green on the build SHA.
• Access log is shipping to the aggregator and is searchable by request_id.
• Incident-response runbook (who to page, how to revoke a leaked JWT secret, how to rotate API keys) is current.
• Backup + restore tested in the last 30 days.

---

8. Reporting a vulnerability

Send to security@ (mailbox TBD). Include reproduction, impact, and a sane timeline. We commit to acknowledging within 72 h and patching critical issues within 7 days.