5104f7c429
Ship the first feature end-to-end on the UI: users log in with JWT,
admins manage user accounts, and any authenticated user (per RBAC)
can create, list, view, edit, and delete engagements.
Backend (Flask + SQLAlchemy + SQLite, 63 pytest)
- User / Engagement models, Alembic 0001 initial schema
- argon2 password hashing, JWT bearer (60-min TTL), @login_required
and @role_required decorators
- 13 API endpoints under /api/*, including last-admin protection on
DELETE/PATCH user and JSON 404 on unknown /api/* paths
- `flask create-admin` CLI with duplicate / short-password handling
Frontend (React + Vite + Tailwind + TanStack Query, 20 vitest)
- Inter font bundled locally (no CDN), DESIGN.md tokens in Tailwind
- LoginPage / EngagementsList / EngagementForm / EngagementDetail /
UsersAdmin pages with role-aware UI
- Layout, ProtectedRoute, StatusBadge, FormField, LoadingState,
ErrorState, EmptyState, Toast + provider
- Axios client: Bearer interceptor, 401 → purge + /login + "Session
expirée" toast, 403 → "Accès refusé" toast (declarative <Navigate>
for already-authed users, Fragment-keyed admin user rows)
Deployment
- Single multistage Dockerfile (node:20-alpine → python:3.12-slim)
- docker/entrypoint.sh runs `flask db upgrade` before `flask run`
- Makefile: build/start/stop/restart/update/logs/create-admin/
update-mitre/test-{backend,frontend,e2e}/clean
- .env.example documenting MIMIC_JWT_SECRET / MIMIC_DB_PATH / MIMIC_PORT
- SQLite at /data/mimic.sqlite on named volume mimic-data
Acceptance suite (Playwright, 36 tests, all 27 ACs)
- e2e/ scaffold with playwright.config + auth/api fixtures
- One spec per user story (us1-bootstrap through us6-deployment)
- Portable via MIMIC_CONTAINER_CMD / MIMIC_BASE_URL (docker or podman)
Docs
- README.md with quick-start and architecture overview
- CHANGELOG.md updated with Sprint 1 deliverables
- pyrightconfig.json so the Python LSP sees backend/.venv and
resolves the `backend.app.*` absolute imports
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
157 lines
5.4 KiB
Markdown
157 lines
5.4 KiB
Markdown
# Mimic
|
|
|
|
**Mimic** is a Breach and Attack Simulation (BAS) web UI built on the MITRE ATT&CK matrix. It replaces the flat Excel spreadsheets that red-teams and SOC analysts pass around at the end of an engagement, providing a shared workspace for Purple Team handoffs.
|
|
|
|
> Status: **Sprint 1 — Auth + CRUD Engagement**. Simulation workflow and MITRE TTP autocomplete arrive in Sprint 2+.
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
Prerequisites: Docker (or Podman) + GNU Make. Linux/macOS host.
|
|
|
|
```bash
|
|
# 1. Configure secrets
|
|
cp .env.example .env
|
|
# Edit .env and set MIMIC_JWT_SECRET to a strong random value:
|
|
# sed -i "s|replace-me-with-a-strong-random-secret|$(openssl rand -hex 32)|" .env
|
|
|
|
# 2. Build and start the container
|
|
make build
|
|
make start
|
|
|
|
# 3. Bootstrap the first admin (run once, the container must be up)
|
|
make create-admin USER=alice PASS=changeme8
|
|
|
|
# 4. Open the UI
|
|
xdg-open http://localhost:5000 # Linux
|
|
# or visit http://localhost:5000 manually
|
|
```
|
|
|
|
Log in with the credentials from step 3. The admin can create additional users (redteam / soc) from `/admin/users`.
|
|
|
|
To stop or restart:
|
|
|
|
```bash
|
|
make stop
|
|
make restart # stop + start, preserves the SQLite volume
|
|
make logs # tail container logs
|
|
```
|
|
|
|
To override the host port:
|
|
|
|
```bash
|
|
make start PORT=8080
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
Single-container deployment. A multistage Dockerfile builds the Vite frontend, then copies the static assets into the Flask backend image so Flask serves both the API (under `/api/*`) and the SPA (everything else).
|
|
|
|
```
|
|
┌───────────────────────────────────────────┐
|
|
│ Container: mimic:latest │
|
|
│ │
|
|
│ Flask (Python 3.12) │
|
|
│ ├── /api/* ── blueprints (auth, users, │
|
|
│ │ engagements) │
|
|
│ └── / ── SPA fallback → React build │
|
|
│ │
|
|
│ SQLAlchemy ── SQLite at /data/mimic.sqlite │
|
|
│ (volume: mimic-data)│
|
|
└───────────────────────────────────────────┘
|
|
```
|
|
|
|
- **Auth**: JWT Bearer tokens (HS256, 60-min TTL). Stateless — no refresh tokens, no server-side session.
|
|
- **Roles**: `admin` (super-user, manages users + engagements), `redteam` (CRUD engagements + simulations), `soc` (read engagements; will write the SOC half of simulations in Sprint 2).
|
|
- **Password hashing**: argon2 via `argon2-cffi`.
|
|
- **Migrations**: Alembic, applied automatically by the container entrypoint (`flask db upgrade && flask run`).
|
|
|
|
See [`SPEC.md`](SPEC.md) § "Décisions techniques" for the full architecture rationale and [`DESIGN.md`](DESIGN.md) for the UI design system.
|
|
|
|
---
|
|
|
|
## Project layout
|
|
|
|
```
|
|
mimic/
|
|
├── backend/ # Flask app, SQLAlchemy models, Alembic migrations, pytest suite
|
|
├── frontend/ # Vite + React + Tailwind + TanStack Query, Vitest suite
|
|
├── e2e/ # Playwright acceptance tests (one spec per user story)
|
|
├── docker/ # Dockerfile (multistage) + entrypoint.sh
|
|
├── tasks/ # Sprint plans (tasks/todo.md) and lessons (tasks/lessons.md)
|
|
├── .claude/agents/ # Sub-agent definitions for the team (read-only at runtime)
|
|
├── Makefile # all operational entry points
|
|
├── SPEC.md # functional + technical spec
|
|
├── DESIGN.md # UI design system (palette, typography, components)
|
|
└── CHANGELOG.md
|
|
```
|
|
|
|
---
|
|
|
|
## Make targets
|
|
|
|
| Target | What it does |
|
|
|---|---|
|
|
| `make build` | Build the `mimic:latest` Docker image (multistage: Node → Python) |
|
|
| `make start` | Start the container (port from `PORT`, default 5000; mounts `mimic-data` volume) |
|
|
| `make stop` | Stop and remove the container |
|
|
| `make restart` | `make stop && make start` — preserves the SQLite volume |
|
|
| `make update` | `git pull && make build && make restart` |
|
|
| `make logs` | `docker logs -f mimic` |
|
|
| `make create-admin USER=… PASS=…` | Run `flask create-admin` inside the container |
|
|
| `make update-mitre` | No-op placeholder — Sprint 2+ will fetch the MITRE STIX bundle |
|
|
| `make test-backend` | `pytest -q` inside the container |
|
|
| `make test-frontend` | `npm run test -- --run` in `frontend/` |
|
|
| `make test-e2e` | Playwright acceptance suite (container must be running) |
|
|
| `make clean` | Remove container + volume + Python/Node caches |
|
|
|
|
---
|
|
|
|
## Development (without Docker)
|
|
|
|
Backend:
|
|
|
|
```bash
|
|
cd backend
|
|
python -m venv .venv && source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
export MIMIC_JWT_SECRET=dev-secret
|
|
export MIMIC_DB_PATH=./mimic.sqlite
|
|
flask --app backend.app:create_app db upgrade
|
|
flask --app backend.app:create_app run --port 5000
|
|
```
|
|
|
|
Frontend:
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # http://localhost:5173 with /api proxied to :5000
|
|
```
|
|
|
|
Tests:
|
|
|
|
```bash
|
|
cd backend && pytest -q # 63 tests
|
|
cd frontend && npm run test -- --run # 20 tests
|
|
cd e2e && npx playwright test # 36 tests (needs container up)
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
- [`SPEC.md`](SPEC.md) — functional spec, technical decisions, agent team
|
|
- [`DESIGN.md`](DESIGN.md) — UI design system
|
|
- [`CHANGELOG.md`](CHANGELOG.md) — sprint-by-sprint changes
|
|
- [`tasks/todo.md`](tasks/todo.md) — current sprint plan
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Internal project — not yet open-sourced.
|