f1fdf27012
- Repo scaffolding: .gitignore, .env.example, Makefile, docker-compose.yml, README.md, CHANGELOG.md, pre-commit config. - Three-service stack: api (Flask 3), db (postgres:16-alpine), front (nginx serving the Vite bundle). Named volumes metamorph_db + metamorph_evidence. - Backend skeleton: Flask app factory, JSON structured logging on stdout, GET /api/v1/health, multi-stage Dockerfile, pyproject.toml driven by uv, Pydantic Settings with secret guard rails (refuses to boot in non-dev with placeholders), APP_ENV gating. - Frontend skeleton: Vite + React 18 + TypeScript strict + TailwindCSS, RTOps design tokens from tasks/design.md, self-hosted JetBrains Mono / IBM Plex Sans via @fontsource, base UI primitives (Card/Tag/SectionHeader/FlowNode/ Button), home page wired to /api/v1/health. - Engine-agnostic Makefile: auto-detects docker or podman, picks the matching compose driver. Targets: up/down/build/rebuild/dev/lint/fmt/test/migrate/ seed-mitre/print-install-token/e2e/inspect-health. - Playwright suite: e2e/tests/m0-smoke.spec.ts (8 tests) + HTML + JUnit reports + traces on retry. - Docs: tasks/spec.md (finalized after Q&A), tasks/design.md, tasks/todo.md (14 milestones), tasks/testing-m0.md, tasks/lessons.md. DoD: make up + make health + make e2e all pass on podman 5.x (Fedora) and docker. TLS terminated by external reverse proxy (spec §6 NF-network). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
130 lines
4.9 KiB
Markdown
130 lines
4.9 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 (bootstrap). 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.
|
|
- **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>
|
|
|
|
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-m0.md) (currently `testing-m0.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: **M0 — bootstrap**.
|
|
|
|
## License
|
|
|
|
TBD.
|