StillWorking's picture
Upload SECURITY.md with huggingface_hub
092d7fb verified
|
Raw History Blame Contribute Delete
6.22 kB

Security Guide — Sentinel-AI

This project is a hackathon/demo system that performs face recognition and biometric attribute search. Treat it as sensitive infrastructure, not a normal web app.

The default configuration is intentionally convenient for a local demo. It is not safe to expose to a network as-is.


1. Deployment profiles

Profile Auth Rate limit TLS Suitable for
Local demo (default) Off (SENTINEL_API_KEY empty) On, loopback only No Your own machine
Shared / internal Bearer token On Reverse proxy Trusted team network
Public Bearer token + SSO/WAF On (proxy + app) Required Not recommended

The local demo binds to 127.0.0.1 unless you deliberately use --host 0.0.0.0. If you bind to all interfaces, set SENTINEL_API_KEY first.


2. Secrets

Where keys live

  • E:\AI Infra\.env and E:\AI Infra\backend\.env (gitignored; backend wins).
  • Provider console keys: GEMINI_API_KEY / GOOGLE_API_KEY, GROQ_API_KEY, COHERE_API_KEY.
  • The dashboard never receives provider keys. VITE_API_KEY is only an application access token and is visible in the browser bundle; never put a provider key there.

Rotation

The audit found plaintext keys in .env files. Because those files may have been copied or archived, rotate all three keys before sharing the folder:

  1. Gemini — https://aistudio.google.com/app/apikey → revoke the old key, create a new one.
  2. Groq — https://console.groq.com/keys → delete, create a new key.
  3. Cohere — https://dashboard.cohere.com/api-keys → revoke, create a new key.

Then update both .env files (or remove the duplicate and keep one), restart the backend, and verify /health plus one live alert.

# Check nothing secret is staged for sharing
python scripts/check_secrets.py

Do not paste keys into chat, issues, screenshots, logs, or commits. If a key leaks, rotate it; deleting the file is not enough because the value may already be in history or a backup.


3. API access control

Enable the built-in Bearer-token check:

SENTINEL_API_KEY=change-me-to-a-long-random-demo-key
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_BURST=20

Every /api/v1/* request must then send either:

Authorization: Bearer <key>

or:

X-API-Key: <key>

/health, /docs, /redoc, and /openapi.json stay open for probes and documentation. OPTIONS preflight requests bypass auth so CORS works.

Generate a key with:

# PowerShell
-join ((48..57) + (65..90) + (97..122) | Get-Random -Count 48 | ForEach-Object { [char]$_ })

The rate limiter is an in-process token bucket keyed by API key (authenticated) or client IP (anonymous). It is per-worker: if you run multiple uvicorn workers, enforce a shared limit at the reverse proxy as well.


4. TLS and reverse proxy

Terminate TLS in front of uvicorn. A sample nginx configuration is in deploy/nginx.conf.example. Minimum requirements:

  • HTTPS only, HSTS enabled.
  • client_max_body_size slightly above MAX_UPLOAD_BYTES (default 10 MiB).
  • Forward X-Forwarded-For / X-Forwarded-Proto.
  • Set TRUST_PROXY_HEADERS=1 only when the proxy is trusted and overwrites those headers.
  • Do not expose port 8000 directly when a proxy is in use.
# Backend behind nginx
cd backend
python -m uvicorn main:app --host 127.0.0.1 --port 8000

5. CORS

CORS_ORIGINS is a comma-separated allow-list. The default includes the local Vite dev server on ports 8080/5173 and the preview server on 4173. Add your real frontend origin for a deployment. Avoid CORS_ORIGINS=*; it is incompatible with credentialed deployments and makes every site able to call the API.

Allowed headers include Content-Type, Authorization, and X-API-Key.


6. Input handling

  • /analyze-frame rejects empty uploads (422), oversized uploads (413), and undecodable images (422). The size cap is MAX_UPLOAD_BYTES.
  • Uploaded bytes are decoded in memory and are not written to disk.
  • /images/{id} accepts only zero-padded six-digit .jpg names inside CELEBA_IMAGES_DIR; traversal attempts are rejected before filesystem access.
  • /generate-person returns sanitised errors and preserves meaningful HTTP status codes. It does not echo provider internals.
  • Error responses never include stack traces or absolute paths.

Keep MAX_UPLOAD_BYTES aligned with the proxy limit, and keep the image directory outside any path served by the proxy.


7. Dependency isolation

The project pins a tested environment in requirements.lock and targets Python 3.11. Use a virtual environment; do not install into a global interpreter that contains unrelated packages.

.\scripts\bootstrap.ps1          # CUDA 12.6 (verified environment)
.\scripts\bootstrap.ps1 -Cpu     # CPU-only

The bootstrap script creates .venv, installs the lock/requirements, runs the secret check, and warns about missing AdaFace assets. It never overwrites an existing .env.


8. Logging and incident response

  • The API logs provider failures (exception text) but not prompts containing biometric attributes at INFO level.
  • Access logs contain client IPs. Treat them as personal data; shorten retention.
  • If a key is exposed: revoke it at the provider, issue a replacement, restart the backend, and search logs/archives for the old value.
  • If a biometric image or report is exposed: follow the incident process in PRIVACY.md.

9. Pre-sharing checklist

  • Gemini, Groq, and Cohere keys rotated.
  • .env files contain the new keys and are gitignored.
  • python scripts/check_secrets.py exits 0.
  • SENTINEL_API_KEY set if the API is reachable by anyone else.
  • CORS_ORIGINS limited to the real frontend origin.
  • TLS/reverse proxy configured; port 8000 not public.
  • Data/, backend/index_artifacts/, and backend/models_cache/ excluded from the shared archive.
  • Privacy notice and lawful basis reviewed for your jurisdiction.