Download SECURITY.md from StillWorking/sentinel-face-recognition: direct link, hf CLI and curl.
- Browser
- Download file 6.22 kB
-
https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/SECURITY.md
- Command line
-
hf download hf://StillWorking/sentinel-face-recognition/SECURITY.md
-
curl -L -o SECURITY.md https://huggingface.co/StillWorking/sentinel-face-recognition/resolve/main/SECURITY.md
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\.envandE:\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_KEYis 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:
- Gemini — https://aistudio.google.com/app/apikey → revoke the old key, create a new one.
- Groq — https://console.groq.com/keys → delete, create a new key.
- 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_sizeslightly aboveMAX_UPLOAD_BYTES(default 10 MiB).- Forward
X-Forwarded-For/X-Forwarded-Proto. - Set
TRUST_PROXY_HEADERS=1only 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-framerejects empty uploads (422), oversized uploads (413), and undecodable images (422). The size cap isMAX_UPLOAD_BYTES.- Uploaded bytes are decoded in memory and are not written to disk.
/images/{id}accepts only zero-padded six-digit.jpgnames insideCELEBA_IMAGES_DIR; traversal attempts are rejected before filesystem access./generate-personreturns 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.
-
.envfiles contain the new keys and are gitignored. -
python scripts/check_secrets.pyexits 0. -
SENTINEL_API_KEYset if the API is reachable by anyone else. -
CORS_ORIGINSlimited to the real frontend origin. - TLS/reverse proxy configured; port 8000 not public.
-
Data/,backend/index_artifacts/, andbackend/models_cache/excluded from the shared archive. - Privacy notice and lawful basis reviewed for your jurisdiction.