e4a672c443
- README "Status" bumped to sprint 6 + test counts (253 backend, 136 frontend, 223 e2e). - CHANGELOG [Unreleased] section for sprint 6: backend, frontend, e2e, security, and changed-section notes (SPEC commit-first + mimic team). - 6 sprint-6 lessons in tasks/lessons.md: 1. SPEC.md commit-first tamed the 4-sprint recurrence 2. Persistent team mimic + idle members > "never idle" 3. Security plugin caught CSV formula injection mid-sprint 4. Stdlib first before custom helpers 5. Tests that mock at module level can't exercise the target's branches 6. _engagement param for signature symmetry across render trio This is the team-lead wrap-up commit. PR body in tasks/pr-body-sprint-6.md will be ingested by make open-pr.
161 lines
6.9 KiB
Markdown
161 lines
6.9 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 6 — Engagement export**. Admin/redteam can now export an engagement to Markdown, CSV, or PDF in one click from `EngagementDetailPage`. The export contains the engagement header and all simulations with both Red Team and SOC fields — closing the "replace the shared Excel" loop. CSV cells are defused against spreadsheet formula injection. SOC has no access to the export.
|
|
|
|
---
|
|
|
|
## 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 |
|
|
| `make open-pr TITLE="…" BODY=path` | Open a PR on the Gitea repo for the current branch via the REST API. Reads credentials from `~/.git-credentials` (same source as `git push`) — no token in env. Wraps `scripts/open-pr.sh`. Defaults `BASE=main`. |
|
|
|
|
---
|
|
|
|
## 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 # 253 tests
|
|
cd frontend && npm run test -- --run # 136 tests
|
|
cd e2e && npx playwright test # 223 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.
|