Spaces:
Sleeping
Sleeping
| title: CyberArena Backend | |
| emoji: 🛡️ | |
| colorFrom: purple | |
| colorTo: blue | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| license: mit | |
| # CyberArena — Backend | |
| > FastAPI backend for the CyberArena cybersecurity training platform. | |
| > Single source of truth: this directory. The old `Apex/backend/` has | |
| > been removed. | |
| ## Quick start | |
| ```bash | |
| cd CyberArena | |
| pip install -r requirements.txt | |
| python main.py # serves on http://localhost:8090 | |
| ``` | |
| The server loads `.env` automatically from this folder. | |
| ## Project layout | |
| ``` | |
| CyberArena/ | |
| ├── main.py ← 5-line uvicorn entry | |
| ├── requirements.txt | |
| ├── Dockerfile | |
| ├── start.cmd | |
| │ | |
| ├── app/ ← all real code | |
| │ ├── main.py ← FastAPI app, middleware, startup | |
| │ ├── types.py ← Pydantic request models | |
| │ │ | |
| │ ├── core/ ← constants + pure helpers (no I/O) | |
| │ │ ├── config.py ← env-loaded handles (Supabase, AI URLs, keys) | |
| │ │ ├── constants.py ← topic catalog, fallback HTML, cert config | |
| │ │ ├── security.py ← normalize_vuln_key, ip/ioc/time matchers | |
| │ │ ├── text.py ← parse_json_safe (LLM JSON parser) | |
| │ │ └── module_router.py ← module → challenge_type dispatcher | |
| │ │ | |
| │ ├── services/ ← business logic / I/O | |
| │ │ ├── supabase_service.py ← PostgREST client (CRUD on pool tables) | |
| │ │ ├── challenge_loader.py ← row → TrainingData mappers (per type) | |
| │ │ ├── scenario_service.py ← Groq scenario + challenge generation | |
| │ │ ├── evaluator.py ← /evaluate handlers (5 types) | |
| │ │ ├── completion_service.py ← user_completions idempotent tracker | |
| │ │ ├── certificate_service.py ← PDF build + cert issue/verify/download | |
| │ │ └── file_storage.py ← write downloadable files to disk | |
| │ │ | |
| │ ├── generators/ ← per-type AI pool generators | |
| │ │ ├── __init__.py ← REGISTRY: list of (slug, module, teams) | |
| │ │ ├── crypto.py ← owns encryption_challenges | |
| │ │ ├── code_fixing.py ← owns code_fixing_challenges | |
| │ │ ├── log_analysis.py ← owns log_analysis_challenges | |
| │ │ └── vulnerability_hunter.py ← owns vulnerability_hunter_challenges | |
| │ │ | |
| │ ├── sandbox/ ← in-process OS simulator sandbox | |
| │ │ ├── workdir.py ← per-challenge tempdir + safe_join | |
| │ │ ├── tools.py ← built-in cat/ls/sha256sum/base64/… | |
| │ │ └── terminal.py ← shlex parse + whitelist subprocess run | |
| │ │ | |
| │ └── api/ ← FastAPI routers (HTTP shell only) | |
| │ ├── auth.py ← /api/auth | |
| │ ├── xp.py ← /api/xp | |
| │ ├── leaderboard.py ← /api/leaderboard | |
| │ ├── certificates.py ← /api/certificates* | |
| │ ├── training.py ← /api/training/* | |
| │ ├── terminal.py ← /api/training/terminal* | |
| │ └── onevone.py ← /api/onevone/* (head-to-head matches) | |
| │ | |
| ├── db/ ← all database concerns | |
| │ ├── schema/ ← numbered, idempotent SQL migrations | |
| │ │ ├── 000_extensions.sql | |
| │ │ ├── 001_users.sql | |
| │ │ ├── 002_encryption_challenges.sql | |
| │ │ ├── 004_code_fixing_challenges.sql | |
| │ │ ├── 005_log_analysis_challenges.sql | |
| │ │ ├── 006_vulnerability_hunter_challenges.sql | |
| │ │ ├── 007_onevone.sql | |
| │ │ ├── 008_certificates.sql | |
| │ │ ├── 009_user_completions.sql | |
| │ │ ├── 010_challenge_files_bucket.sql | |
| │ │ ├── 011_challenge_type_normalization.sql | |
| │ │ └── 012_onevone_vuln_hunter.sql | |
| │ ├── seed/ ← per-type example JSON (template) | |
| │ │ ├── README.md | |
| │ │ ├── crypto.example.json | |
| │ │ ├── web.example.json | |
| │ │ ├── code_fixing.example.json | |
| │ │ ├── log_analysis.example.json | |
| │ │ └── vulnerability_hunter.example.json | |
| │ ├── apply.py ← apply every schema/*.sql in order | |
| │ └── README.md | |
| │ | |
| ├── scripts/ ← ops utilities | |
| │ ├── check_state.py ← one-page DB health report | |
| │ └── seed_pools.py ← pool size + status (read-only by default) | |
| │ | |
| ├── .env ← secrets (never commit) | |
| └── README.md | |
| > **No local file storage.** AI-generated challenge files are uploaded | |
| > to the `challenge-files` Supabase Storage bucket (see | |
| > `db/schema/010_challenge_files_bucket.sql`) and the public URL is | |
| > returned in the training payload. The backend never writes to its | |
| > own disk. | |
| ``` | |
| ## API surface | |
| The FastAPI app exposes **28 routes** under `/api/`. The full list | |
| lives in `app/main.py`; the most important are: | |
| | Method | Path | Notes | | |
| |--------|-------------------------------------|-------| | |
| | POST | `/api/auth` | proxied to Supabase `apex-auth` edge function | | |
| | POST | `/api/xp` | proxied to Supabase `apex-xp` edge function | | |
| | GET | `/api/leaderboard` | top users by XP | | |
| | GET | `/api/training/list` | dashboard cards | | |
| | POST | `/api/training/generate` | hydrate cached scenario into a full challenge | | |
| | POST | `/api/training/evaluate` | legacy red+blue AI evaluator | | |
| | POST | `/api/training/evaluate-web` | 3-layer web exploitation validator | | |
| | POST | `/api/training/evaluate-code-fix` | AI code-fix grader | | |
| | POST | `/api/training/evaluate-log-analysis` | 4-field exact match + Mistral feedback | | |
| | POST | `/api/training/evaluate-vulnerability-hunter` | exact canonical-key match | | |
| | POST | `/api/training/terminal*` | OS simulator sandbox | | |
| | POST | `/api/certificates` | list / issue | | |
| | GET | `/api/certificates/{id}/pdf` | streamed PDF | | |
| | GET | `/api/certificates/verify/{code}` | public QR landing | | |
| | GET | `/api/certificates/progress` | (completions, required) | | |
| | POST | `/api/onevone/rooms` | 1v1 mode (see `app/api/onevone.py`) | | |
| ## Pool architecture | |
| Each challenge type owns its own table + its own generator. The | |
| orchestrator in `app/main.py::populate_pool_background` walks | |
| `app.generators.REGISTRY` and starts one watcher per (type, team). | |
| Pool model: `POOL_TARGET / POOL_THRESHOLD / POOL_BATCH` are module | |
| constants inside each generator. The watcher refills the table | |
| when the count drops to `POOL_THRESHOLD` and inserts `POOL_BATCH` new | |
| rows in parallel via `asyncio.gather`. | |
| See `../AGENTS.md` "Pool Architecture" for the full contract. | |
| ## Database | |
| Apply the migrations to Supabase with: | |
| ```bash | |
| python db/apply.py # needs SUPABASE_SERVICE_KEY in .env | |
| ``` | |
| Each `.sql` file is idempotent (`CREATE … IF NOT EXISTS`, `DROP | |
| POLICY IF EXISTS + CREATE`). See `db/README.md` for details. | |
| ## Running tests | |
| There is no formal test suite yet. Use: | |
| ```bash | |
| python -c "from app.main import app; print(len(app.routes), 'routes')" | |
| python scripts/check_state.py # requires SUPABASE_URL | |
| ``` | |
| ## Deployment | |
| The provided `Dockerfile` pins `python:3.11-slim` and starts the | |
| server on `PORT` (default 7860, matches Hugging Face Spaces). | |
| ### Hugging Face Spaces (Docker SDK) | |
| 1. Create a new Space → **Docker** SDK. | |
| 2. Push this folder (`CyberArena/`) to the Space's git remote: | |
| ```bash | |
| cd CyberArena | |
| git remote add hf https://huggingface.co/spaces/Alpha-Team/CyberArena | |
| git push hf main | |
| ``` | |
| 3. In the Space's **Settings → Repository secrets**, add every key | |
| the backend needs. HF injects them as environment variables | |
| (the loader in `app/_env.py` does **not** override process env, | |
| so secrets take priority over any `.env` shipped in the repo). | |
| | Secret | Required | | |
| |---|---| | |
| | `SUPABASE_URL` | yes | | |
| | `SUPABASE_ANON_KEY` | yes | | |
| | `CLOUDFLARE_API_TOKEN` | yes (primary AI) | | |
| | `CLOUDFLARE_ACCOUNT_ID` | yes | | |
| | `CLOUDFLARE_MODEL` | optional (default `@cf/qwen/qwen2.5-coder-32b-instruct`) | | |
| | `GROQ_API_KEY` | yes (fallback AI) | | |
| | `GROQ_MODEL` | optional (default `llama-3.1-8b-instant`) | | |
| | `NVIDIA_API_KEY` | yes (tertiary AI) | | |
| | `NVIDIA_MODEL` | optional (default `deepseek-ai/deepseek-v4-pro`) | | |
| | `MISTRAL_API_KEY` | yes (quaternary AI + vuln-hunter grader) | | |
| | `MISTRAL_MODEL` | optional (default `mistral-small-latest`) | | |
| 4. The Space URL will be `https://<user>-<space>.hf.space`. The | |
| frontend's `VITE_API_URL` must be set to that URL + `/api` | |
| (e.g. `https://alpha-team-cyberarena.hf.space/api`). | |
| 5. **Workdir caveat**: per-challenge user scripts (`solve.py`, …) | |
| live in `tempfile.mkdtemp()` on the container's `/tmp`. The | |
| container's disk is **lost on Space sleep / restart**, but | |
| challenge data and user XP live in Supabase and persist. | |
| 6. The Space can sleep after 48h of inactivity. To stay always-on, | |
| upgrade the Space's hardware tier or wake it manually before | |
| class. | |
| > The `.env` file is **never** uploaded — it's listed in | |
| > `.dockerignore`. The HF secrets panel is the only source of | |
| > environment variables in production. | |