00b7557e30
Adds the mission layer that materialises template snapshots, plus the SPA list / 3-step wizard / detail page. Backend: - app/services/missions.py — create_mission snapshots scenarios, tests, MITRE tags in a 4-query write; list/get apply a non-admin membership filter that collapses to 404 (no existence leak); status state machine enforces draft → in_progress → completed → archived with archived as a sink; the non-admin creator is auto-added as role_hint='red' to retain visibility. - app/api/missions.py — 8 endpoints (list, get, create, update, add scenarios, set members, transition, soft-delete) with strict pydantic schemas. The transition endpoint splits the perm gate manually so archive requires mission.archive while other targets use mission.update. - app/api/users.py — new GET /users/roster returning (id, email, display_name) only, gated by user.read OR mission.create OR mission.update — lets non-admin wizard users see assignable peers without exposing the admin /users payload. - app/api/diag.py — /diag/reset truncates the mission_* tables before the template tables because the source_*_template_id FKs are ON DELETE SET NULL, which is cheaper to short-circuit by removing the children first. Frontend: - lib/missions.ts — typed client, queryKey factory, status accent map. - pages/MissionsListPage.tsx — list cards with status accent + filters (q, client, status). - pages/MissionsCreatePage.tsx — 3-step wizard (meta → scenarios → members) with member roster fed by /users/roster. - pages/MissionDetailPage.tsx — header + transition buttons (legal next states only) + Tests/Members/Synthesis/Export tabs. - Routes + nav entry (visible to anyone with mission.read or admin). Tests: - backend/tests/test_missions.py — 22 pytest covering snapshot fidelity, MITRE propagation, membership visibility, transition state machine, perm gating, member set replace, append scenarios, soft-delete, partial update, inverted-date rejection. - e2e/tests/m6-missions.spec.ts — 5 Playwright (snapshot freezing, non-admin visibility, status transitions + 409, SPA wizard end-to-end, list filter). Docs: - CHANGELOG, tasks/testing-m6.md, tasks/lessons.md (snapshot tradeoffs, membership=404 pattern, /diag/reset order, auto-creator add). - README + tasks/todo.md updated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
145 lines
6.7 KiB
Markdown
145 lines
6.7 KiB
Markdown
# Metamorph
|
||
|
||
Collaborative purple-team platform. Red team logs the tests they execute (procedure, command, timestamp); blue team annotates each test with detection evidence (alerts, logs, files). At the end of an engagement, Metamorph generates a standalone reveal.js slide deck classified by MITRE ATT&CK tactic.
|
||
|
||
> **Status**: M0–M5 delivered (bootstrap → DB schema → auth → RBAC → MITRE ATT&CK reference → test & scenario templates). See `tasks/spec.md` for the full specification and `tasks/todo.md` for the milestone-by-milestone plan.
|
||
|
||
## Stack
|
||
|
||
- **Backend**: Python 3.12, Flask 3, SQLAlchemy 2 + Alembic (M1+), PostgreSQL 16.
|
||
- **Frontend**: React 18 + TypeScript + Vite + TailwindCSS (RTOps design tokens, see `tasks/design.md`).
|
||
- **Auth (M2+)**: JWT access (1h) + refresh (30d), Argon2id, invite-link enrollment.
|
||
- **RBAC (M3+)**: atomic permissions (31 codes) bundled into custom groups; 3 system groups seeded (`admin` / `redteam` / `blueteam`).
|
||
- **MITRE ATT&CK (M4+)**: Enterprise reference catalogue pinned to v19.0, seedable via `make seed-mitre`.
|
||
- **Template catalogue (M5+)**: reusable `test_templates` (markdown procedure, OPSEC level, free tags, expected IOCs, MITRE tags) + ordered `scenario_templates` with drag-and-drop reordering. Admin pages at `/admin/tests` and `/admin/scenarios`.
|
||
- **Missions (M6+)**: `missions` snapshot one or more scenario templates at creation time; template edits don't drift live missions (`mission_*` tables freeze every field, including MITRE tags). Non-admin members see only their own missions (membership filter, 404 on existence-leak attempts). Status state machine `draft → in_progress → completed → archived`, archive perm gated separately. SPA: list/filter at `/missions`, 3-step create wizard at `/missions/new`, detail page with Tests / Members / Synthesis / Export tabs.
|
||
- **Delivery**: docker-compose. TLS termination is expected to be handled by an external reverse proxy in production.
|
||
|
||
## Quickstart
|
||
|
||
Works with **Docker** *or* **Podman**. The Makefile auto-detects the available engine and picks the matching compose driver (`docker compose`, `podman compose`, or `podman-compose`).
|
||
|
||
Requires one of:
|
||
|
||
- Docker Engine 24+ with the Compose v2 plugin, **or**
|
||
- Podman 4.0+ with `podman compose` (or the legacy `podman-compose` ≥ 1.0.6)
|
||
|
||
```bash
|
||
git clone <this repo>
|
||
cd Metamorph
|
||
make engine # confirm which engine the Makefile picked up
|
||
make env # creates .env from .env.example
|
||
$EDITOR .env # set strong values for POSTGRES_PASSWORD and JWT_SECRET
|
||
make up # builds and starts api + db + front
|
||
make logs # tail logs
|
||
```
|
||
|
||
Override the auto-detection if you have both engines installed:
|
||
|
||
```bash
|
||
make up ENGINE=podman # force podman + auto-pick its compose driver
|
||
make up ENGINE=docker COMPOSE="docker compose"
|
||
COMPOSE=podman-compose make up # force the legacy wrapper specifically
|
||
```
|
||
|
||
Then:
|
||
|
||
- Front: <http://localhost:8080>
|
||
- API health: <http://localhost:8080/api/v1/health> (proxied) or <http://localhost:8000/api/v1/health>
|
||
|
||
### First-time setup
|
||
|
||
```bash
|
||
make migrate # apply DB schema
|
||
make print-install-token # prints the bootstrap admin token (logs banner)
|
||
# visit http://localhost:8080/setup, paste the token, create the admin account
|
||
make seed-mitre # populate the MITRE ATT&CK reference (~50 MB, ~1 s)
|
||
```
|
||
|
||
The MITRE bundle is cached in the named volume `metamorph_mitre` (`/data/mitre/<file>.json` inside the api container). For air-gapped operators, pre-populate the volume with your own STIX 2.1 file and run `podman compose exec api flask --app app.cli metamorph seed-mitre --source /data/mitre/your-file.json --skip-checksum`.
|
||
|
||
To stop:
|
||
|
||
```bash
|
||
make down # keep volumes
|
||
make clean # also drop volumes (DESTRUCTIVE)
|
||
```
|
||
|
||
## Local dev (no Docker)
|
||
|
||
Requires:
|
||
|
||
- [uv](https://github.com/astral-sh/uv) for Python deps
|
||
- Node.js 20+ and `npm`
|
||
- A reachable Postgres (or `make up db` to run only the db container)
|
||
|
||
```bash
|
||
make dev-api # in one terminal
|
||
make dev-front # in another
|
||
```
|
||
|
||
## Environment variables
|
||
|
||
See `.env.example`. The most important ones:
|
||
|
||
| Variable | Purpose |
|
||
|--------------------|------------------------------------------------------|
|
||
| `APP_ENV` | `dev` allows placeholder secrets; anything else (prod/staging) refuses to boot with defaults |
|
||
| `POSTGRES_*` | DB credentials (used by `db` and `api`) |
|
||
| `JWT_SECRET` | HS256 signing key — generate 64+ random bytes (`python -c "import secrets; print(secrets.token_urlsafe(64))"`) |
|
||
| `LOG_LEVEL` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
|
||
| `FRONT_ORIGIN` | Allowed CORS origin for the SPA |
|
||
| `EVIDENCE_DIR` | Path inside the api container where uploads land |
|
||
| `HOST_API_PORT` | Host port mapped to the api (default 8000) |
|
||
| `HOST_FRONT_PORT` | Host port mapped to the front nginx (default 8080) |
|
||
|
||
## Testing
|
||
|
||
- **Manual + automated checklist for the current milestone**: see [`tasks/testing-m<N>.md`](tasks/testing-m6.md) (current: `testing-m6.md`).
|
||
- **Backend unit tests**: `make test-api`
|
||
- **End-to-end (Playwright)**: `make e2e-install` (once), then `make up && make e2e`. Reports land in `e2e/playwright-report/` (HTML + JUnit XML); open with `make e2e-report`.
|
||
|
||
## Pre-commit hooks
|
||
|
||
After cloning, install hooks once:
|
||
|
||
```bash
|
||
pipx install pre-commit # or: pip install --user pre-commit
|
||
pre-commit install
|
||
pre-commit run --all-files # initial sweep
|
||
```
|
||
|
||
The hooks run `ruff` + `ruff-format` on the backend and `eslint` / `tsc --noEmit` / `prettier --check` on the frontend (see `.pre-commit-config.yaml`).
|
||
|
||
## Project layout
|
||
|
||
```
|
||
.
|
||
├── backend/ # Flask API
|
||
│ └── app/
|
||
│ ├── api/ # HTTP layer (blueprints)
|
||
│ ├── core/ # config, logging, errors
|
||
│ ├── db/ # SQLAlchemy session, migrations (M1+)
|
||
│ ├── models/ # ORM models (M1+)
|
||
│ ├── services/ # domain logic (M2+)
|
||
│ └── i18n/ # message catalogs (M13)
|
||
├── frontend/ # Vite + React + TS + Tailwind
|
||
│ └── src/components/ui/ # RTOps design system primitives
|
||
├── tasks/
|
||
│ ├── spec.md # source of truth for requirements
|
||
│ ├── design.md # RTOps design system
|
||
│ ├── todo.md # milestone plan
|
||
│ └── lessons.md # session retrospectives
|
||
├── docker-compose.yml
|
||
├── Makefile
|
||
└── CHANGELOG.md
|
||
```
|
||
|
||
## Roadmap
|
||
|
||
See `tasks/todo.md`. Current milestone: **M6 — Missions & snapshot** (done). Next: M7 (red/blue execution on a mission test).
|
||
|
||
## License
|
||
|
||
TBD.
|