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.

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

make stop
make restart      # stop + start, preserves the SQLite volume
make logs         # tail container logs

To override the host port:

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 § "Décisions techniques" for the full architecture rationale and 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:

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:

cd frontend
npm install
npm run dev          # http://localhost:5173 with /api proxied to :5000

Tests:

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 — functional spec, technical decisions, agent team
• DESIGN.md — UI design system
• CHANGELOG.md — sprint-by-sprint changes
• tasks/todo.md — current sprint plan

---

License

Internal project — not yet open-sourced.