mimic/README.md

# 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.