b001f57774
- README: status bump to sprint 3, test counts refreshed (164/86/105), IPv6 note for the e2e runner - CHANGELOG: sprint 3 entry under [Unreleased] (multi-tech model + matrix endpoint + auto-save UI); sprint 2 moved to its own [Sprint 2] section (merged 2026-05-27) - tasks/lessons.md: 6 lessons captured (2-pass spec-review, inline summary scoping, "test in brief means test in commit" discipline, SQLite batch_alter_table, real migration round-trip, modal Apply 0 disambiguation) - tasks/todo.md: status flipped to 🟢 SPRINT COMPLET, execution sequence ticks updated with commit hashes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
160 lines
6.6 KiB
Markdown
160 lines
6.6 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 3 — Multi-technique simulations + MITRE matrix modal**. A simulation can now be tagged with multiple MITRE techniques (top-level and sub-techniques) via either autocomplete or a clickable ATT&CK matrix modal. Tags auto-save on add/remove; the rest of the Sprint 2 Purple Team workflow (workflow states, RBAC, etc.) is unchanged.
|
|
|
|
---
|
|
|
|
## 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, simulations,│
|
|
│ │ mitre) │
|
|
│ └── / ── 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 — cumulates redteam rights on engagements/simulations), `redteam` (CRUD engagements + simulations, full field access), `soc` (read everything, write-only on the SOC half of simulations once the redteam marks them `review_required`).
|
|
- **Password hashing**: argon2 via `argon2-cffi`.
|
|
- **Migrations**: Alembic, applied automatically by the container entrypoint (`flask db upgrade && flask run`).
|
|
- **MITRE ATT&CK**: STIX 2.1 Enterprise bundle committed at `backend/data/mitre/enterprise-attack.json` and indexed at app boot. `make update-mitre` re-fetches the latest bundle and (if the container is running) restarts it to reload the index. The endpoint `GET /api/mitre/techniques?q=` powers the autocomplete on simulations.
|
|
- **Simulation workflow**: Pending → In progress (auto-transition when redteam saves any non-empty field) → Review required (manual, redteam) → Done (manual, redteam or SOC). The state machine is enforced server-side; the UI surfaces the appropriate transition button per role + current state.
|
|
|
|
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` container image (multistage: Node → Python). Uses `docker` if installed, otherwise `podman` — override with `make build CONTAINER_CMD=podman` |
|
|
| `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` | Fetch the latest MITRE STIX 2.1 Enterprise bundle into `backend/data/mitre/`; auto-restart the container if running. Commit the resulting file change manually. |
|
|
| `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 # 164 tests
|
|
cd frontend && npm run test -- --run # 86 tests
|
|
cd e2e && npx playwright test # 105 tests (needs container up — use MIMIC_BASE_URL=http://127.0.0.1:5000 if localhost resolves to IPv6)
|
|
```
|
|
|
|
---
|
|
|
|
## 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.
|