# Sprint 2 — Simulations + MITRE ATT&CK

**Branche** : `sprint/2-simulations`
**Statut** : 🟢 SPRINT COMPLET — 32 acceptance tests sprint 2 verts, code-review traité (2 MAJOR + 2 MINOR + 2 NITs fixés), PR prête
**Base** : `main` (sprint 1 mergé en `7fc79cc`)
**Objectif** : livrer les simulations (CRUD + workflow Pending→In progress→Review required→Done) à l'intérieur d'un engagement, avec autocomplete MITRE ATT&CK alimenté par un bundle STIX local. C'est le cœur métier — l'app remplace enfin le fichier Excel partagé redteam/SOC.

---

## 1. User stories

### US-7 — En tant que redteam, je crée une simulation dans un engagement
**Pourquoi** : c'est la feature centrale du sprint 2.

**Critères d'acceptation**
- [ ] AC-7.1 : `POST /api/engagements/<eid>/simulations {name}` (admin|redteam) → 201 + simulation `{id, engagement_id, name, status: "pending", ...}`. `name` requis, non vide.
- [ ] AC-7.2 : autres rôles (soc) → 403.
- [ ] AC-7.3 : engagement inexistant → 404. Engagement existant mais aucune simulation → liste vide.
- [ ] AC-7.4 : `GET /api/engagements/<eid>/simulations` (auth) → liste des simulations de l'engagement, ordonnée `created_at desc`.
- [ ] AC-7.5 : page `/engagements/:eid` (EngagementDetailPage) remplace le placeholder Sprint 2 par une section "Simulations" : liste (colonnes: name, MITRE id, status badge, executed_at) + bouton "Nouvelle simulation" pour admin/redteam.
- [ ] AC-7.6 : depuis cette liste, click sur une ligne → ouvre `/engagements/:eid/simulations/:sid/edit` (page d'édition role-aware, unique URL pour view+edit).

### US-8 — En tant que redteam, je renseigne les détails techniques d'une simulation
**Pourquoi** : c'est la trace de ce que la redteam a exécuté.

**Critères d'acceptation**
- [ ] AC-8.1 : `PATCH /api/simulations/<sid>` (admin|redteam) accepte les champs redteam : `name`, `mitre_technique_id`, `mitre_technique_name`, `description`, `commands` (texte multiligne, une commande par ligne), `prerequisites`, `executed_at` (ISO datetime), `execution_result`. Champs partiels OK.
- [ ] AC-8.2 : règle d'auto-transition pending → in_progress. Trigger PRÉCIS : `PATCH /api/simulations/<sid>` par admin|redteam où **le payload JSON contient au moins une clé parmi les champs redteam** (`name`, `mitre_technique_id`, `mitre_technique_name`, `description`, `commands`, `prerequisites`, `executed_at`, `execution_result`) **dont la valeur n'est ni `null` ni une string vide ni une liste vide**, ET status courant == `pending`. La comparaison se fait sur le payload entrant — pas sur l'état final de la simulation. Un PATCH qui ne ré-envoie qu'un champ inchangé (ex: même `name`) déclenche quand même la transition, car c'est une action explicite "la redteam saisit". L'auto-transition ne se déclenche jamais sur un PATCH `soc`.
- [ ] AC-8.3 : `commands` est stocké en colonne `text` (chaîne multiligne, une commande par ligne). Sérialisation API = texte brut tel que stocké. Le frontend affiche dans un `<textarea>`.
- [ ] AC-8.4 : `executed_at` valide ISO 8601 ou null. Si invalide → 400 `{error: "invalid executed_at"}`.
- [ ] AC-8.5 : page `/engagements/:eid/simulations/:sid` affiche un formulaire avec deux sections visibles ("Red Team" et "SOC"). Pour admin/redteam, les deux sections sont éditables. Validation client : `name` non vide.
- [ ] AC-8.6 : autocomplete MITRE dans le champ "Technique" — voir US-10.

### US-9 — En tant qu'analyste SOC, je remplis ma partie de la simulation
**Pourquoi** : le SOC documente la détection sans toucher au scope redteam.

**Critères d'acceptation**
- [ ] AC-9.1 : `PATCH /api/simulations/<sid>` envoyé par un user `soc` n'accepte QUE les champs SOC : `log_source`, `logs`, `soc_comment`, `incident_number`. Si la requête contient un champ redteam → 403 `{error: "soc cannot edit redteam fields"}`.
- [ ] AC-9.2 : un user `soc` ne peut PATCH une simulation que si son status est `review_required` ou `done`. Avant ça → 403 `{error: "simulation not ready for SOC review"}`.
- [ ] AC-9.3 : page `/engagements/:eid/simulations/:sid` pour un user `soc` : la section "Red Team" est rendue en read-only (champs grisés) ; la section "SOC" est éditable.
- [ ] AC-9.4 : si la simulation est en `pending` ou `in_progress` et qu'un soc visite la page, un bandeau "Simulation pas encore en revue — la redteam doit la marquer comme 'Review required' avant que vous puissiez intervenir" s'affiche, les champs SOC sont désactivés.

### US-10 — En tant que redteam, j'autocomplète une technique MITRE ATT&CK
**Pourquoi** : éviter de taper l'id à la main, garantir la cohérence.

**Critères d'acceptation**
- [ ] AC-10.1 : `make update-mitre` télécharge le bundle STIX 2.1 Enterprise depuis `https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json` et l'écrit dans `backend/data/mitre/enterprise-attack.json`. Le bundle est COMMITTÉ dans le repo (`make build` reste autosuffisant). `make update-mitre` reste l'unique méthode de rafraîchissement et le diff résultant est committé manuellement.
- [ ] AC-10.2 : `GET /api/mitre/techniques?q=<query>` (auth, tous rôles) → liste max 20 résultats `[{id, name, tactics: ["initial-access", ...]}]`. Recherche full-text sur `id` (ex: "T1059") OU `name` (ex: "Command and Scripting Interpreter"), case-insensitive, ordonnée : match exact id > match préfixe id > match nom.
- [ ] AC-10.3 : si le bundle local est absent → endpoint répond 503 `{error: "mitre bundle not loaded"}`. Le team-lead documente `make update-mitre` dans le README.
- [ ] AC-10.4 : sous-techniques (id format `T1059.001`) incluses dans l'index.
- [ ] AC-10.5 : composant frontend `MitreTechniquePicker` : input + dropdown des matches (debounce 200ms, navigation clavier ↑↓ + Enter, Escape ferme le dropdown), affichage `T1059 — Command and Scripting Interpreter (initial-access)`. La sélection d'une suggestion remplit `mitre_technique_id` ET `mitre_technique_name` du form. Pas de fallback free-text : si l'utilisateur tape sans sélectionner, le champ technique reste vide en sortie de form (id et name `null`).

### US-11 — En tant qu'utilisateur, je transitionne le workflow d'une simulation
**Pourquoi** : la coordination redteam ↔ soc passe par le statut.

**Critères d'acceptation**
- [ ] AC-11.1 : `POST /api/simulations/<sid>/transition {to: "review_required"}` → 200, requiert status courant ∈ {`pending`, `in_progress`} et role ∈ {admin, redteam}. Refuse les autres transitions → 409 `{error: "invalid transition"}`.
- [ ] AC-11.2 : `POST /api/simulations/<sid>/transition {to: "done"}` → 200, requiert status courant == `review_required` et role ∈ {admin, redteam, soc}. Autres transitions → 409.
- [ ] AC-11.3 : aucune transition arrière (ex: done → pending) n'est permise. Pas de transition `→ pending` ni `→ in_progress` via cet endpoint (le passage à `in_progress` est strictement automatique cf AC-8.2).
- [ ] AC-11.4 : sur la page d'édition simulation, deux boutons contextuels :
  - Pour admin/redteam, status ∈ {pending, in_progress} : bouton "Marquer en revue".
  - Pour admin/redteam/soc, status == review_required : bouton "Clôturer".
  - Sinon : boutons cachés.
- [ ] AC-11.5 : après transition réussie, la query simulation et la liste sont invalidées (TanStack Query), le badge se met à jour.

### US-12 — En tant qu'admin ou redteam, je supprime une simulation
**Critères d'acceptation**
- [ ] AC-12.1 : `DELETE /api/simulations/<sid>` (admin|redteam) → 204.
- [ ] AC-12.2 : `soc` → 403.
- [ ] AC-12.3 : suppression d'engagement (cascade) supprime toutes ses simulations.
- [ ] AC-12.4 : bouton "Supprimer" sur la page d'édition (admin/redteam uniquement), avec confirmation modal.

---

## 2. Brief technique — Backend Builder

**Scope strict** : `backend/`, `docker/`, `Makefile` (target `update-mitre`).

### Livrables

**Modèle `Simulation`** (`backend/app/models/simulation.py`)
| Champ | Type | Notes |
|---|---|---|
| id | int PK | |
| engagement_id | int FK Engagement, CASCADE | requis |
| name | str, NOT NULL | redteam-side |
| mitre_technique_id | str, nullable | ex "T1059" / "T1059.001" |
| mitre_technique_name | str, nullable | snapshot pour résilience aux maj MITRE |
| description | text, nullable | redteam-side |
| commands | text, nullable | chaîne multiligne, une commande par ligne — pas de JSON |
| prerequisites | text, nullable | redteam-side |
| executed_at | datetime, nullable | redteam-side |
| execution_result | text, nullable | redteam-side |
| log_source | text, nullable | soc-side |
| logs | text, nullable | soc-side |
| soc_comment | text, nullable | soc-side |
| incident_number | str, nullable | soc-side |
| status | enum(pending/in_progress/review_required/done), défaut `pending` | |
| created_at | datetime | |
| updated_at | datetime, nullable | mis à jour à chaque PATCH |
| created_by_id | int FK User | |

**Migration Alembic** `0002_add_simulations.py` — table `simulations` + FK indexes (`engagement_id`, `created_by_id`).

**Endpoints** (nouveau blueprint `backend/app/api/simulations.py`)
- `GET /api/engagements/<eid>/simulations` — list, auth, all roles
- `POST /api/engagements/<eid>/simulations` — create, admin|redteam
- `GET /api/simulations/<sid>` — get, auth
- `PATCH /api/simulations/<sid>` — update avec RBAC field-level (voir AC-8/9)
- `DELETE /api/simulations/<sid>` — admin|redteam
- `POST /api/simulations/<sid>/transition` — state machine
- `GET /api/mitre/techniques?q=` — autocomplete (200 OK + array, 503 si bundle absent)

**Serializer** : retourne `created_by={id, username}` (pattern existant). `commands` → string brut (tel que stocké en DB, peut être `null` ou chaîne multiligne).

**Service workflow** (`backend/app/services/simulation_workflow.py`)
- `apply_patch(simulation, payload, user)` :
  - sépare champs redteam vs soc
  - vérifie RBAC field-level
  - détecte auto-transition pending → in_progress (AC-8.2)
  - applique le patch + commit
- `transition(simulation, to_status, user)` :
  - vérifie state machine (transitions autorisées)
  - vérifie RBAC role
  - met à jour status + updated_at

**Service MITRE** (`backend/app/services/mitre.py`)
- Au boot de l'app : tente de charger `backend/data/mitre/enterprise-attack.json` en mémoire ; si absent ou parse error → flag `mitre_loaded = False` (logue warning, app démarre quand même).
- Indexe les objets STIX `type == "attack-pattern"` : extract `external_id` (T-id), `name`, `kill_chain_phases[].phase_name`.
- Fonction `search(query, limit=20)` : ranking par exact-id > prefix-id > substring-name.

**`Makefile`** : remplacer le no-op de `update-mitre` par :
```makefile
MITRE_URL ?= https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json
update-mitre:
	@mkdir -p backend/data/mitre
	@curl -fsSL "$(MITRE_URL)" -o backend/data/mitre/enterprise-attack.json
	@echo "MITRE bundle updated"
	@if docker ps --format '{{.Names}}' | grep -q "^$(CONTAINER)$$"; then \
		echo "Restarting $(CONTAINER) to reload MITRE bundle..."; \
		docker restart $(CONTAINER); \
	fi
```

**Dockerfile** : copier `backend/data/mitre/` dans l'image (présent dans le repo, donc fonctionne au premier build).

**Bundle MITRE** : committé dans le repo à `backend/data/mitre/enterprise-attack.json`. Le backend-builder l'inclut dans son premier commit via `make update-mitre`.

**Tests pytest** (`backend/tests/`)
- `test_simulations_crud.py` : create + list + get + delete + cascade, RBAC create/delete.
- `test_simulations_patch.py` : auto-transition pending→in_progress, RBAC field-level soc, blocage soc avant review_required (AC-9.2).
- `test_simulations_workflow.py` : transitions valides/invalides, RBAC par transition.
- `test_mitre.py` : load bundle (fixture mini), search ranking, endpoint 503 si pas chargé, sous-techniques incluses.

Tous les tests existants doivent rester verts. Lint ruff + mypy clean.

### Règles
- Pas de touche au frontend.
- Pas d'invention de dépendances (pas besoin d'en ajouter).
- Renvoyer le summary attendu (cf. `.claude/agents/backend-builder.md`).

---

## 3. Brief technique — Frontend Builder

**Scope strict** : `frontend/` UNIQUEMENT. Interdiction de toucher `e2e/`.

### Livrables

**Types** (`frontend/src/api/types.ts`) : ajouter `Simulation`, `SimulationStatus`, `MitreTechnique`, et les payloads PATCH/POST.

**Client API** (`frontend/src/api/simulations.ts`, `frontend/src/api/mitre.ts`)
- `listSimulations(engagementId)`, `createSimulation(engagementId, {name})`, `getSimulation(id)`, `updateSimulation(id, patch)`, `deleteSimulation(id)`, `transitionSimulation(id, to)`.
- `searchMitreTechniques(query)`.

**Hooks TanStack Query** (`frontend/src/hooks/useSimulations.ts`)
- `useEngagementSimulations(engagementId)`, `useSimulation(id)`, mutations `useCreateSimulation`, `useUpdateSimulation`, `useDeleteSimulation`, `useTransitionSimulation`.
- Invalidation : transition + update + delete invalident `["simulations", id]` et `["engagements", eid, "simulations"]`.

**Hook `useMitre`** : `useMitreSearch(query, enabled)` (debounce géré côté composant, hook sans staleTime court — cache 5min).

**Pages**
- `EngagementDetailPage.tsx` : remplacer le placeholder (lignes 74-81) par `<SimulationList engagementId={eng.id} />`. Conserver le reste.
- `SimulationFormPage.tsx` (`/engagements/:eid/simulations/new` et `/engagements/:eid/simulations/:sid/edit`) :
  - Layout en deux cards : "Red Team" et "SOC".
  - Champs redteam : name, MitreTechniquePicker, description, commands (textarea, une commande par ligne, envoyé tel quel — pas de split), prerequisites, executed_at (datetime-local input), execution_result.
  - Champs SOC : log_source, logs, soc_comment, incident_number.
  - Boutons en footer : "Save", "Marquer en revue" (si AC-11.4), "Clôturer" (si AC-11.4), "Supprimer" (modal de confirmation, admin/redteam).
  - Mode création (`new`) : seul `name` requis ; après création, redirige sur `/engagements/:eid/simulations/:sid/edit`.

**Composants** (`frontend/src/components/`)
- `SimulationList.tsx` : table tri par created_at desc, colonnes (Name, MITRE, Status badge, Executed at), bouton "Nouvelle" si admin/redteam, ligne cliquable → navigate edit page.
- `SimulationStatusBadge.tsx` : variant du StatusBadge existant si possible (factoriser), 4 couleurs (pending=fog, in_progress=primary-soft, review_required=bloom-coral, done=storm-deep). Si le StatusBadge existant n'est pas factorisable proprement, créer un nouveau composant — pas d'over-engineering.
- `MitreTechniquePicker.tsx` : input + dropdown, debounce 200ms (`useDebouncedValue` ou util inline), navigation clavier (↑/↓/Enter/Escape), affichage `T1059 — Command and Scripting Interpreter (initial-access)`. Loading state inline.
- `ConfirmDialog.tsx` : modal générique de confirmation (utilisée pour delete).

**Routing** (`App.tsx`)
- Ajouter `/engagements/:eid/simulations/new` (auth, admin|redteam)
- Ajouter `/engagements/:eid/simulations/:sid/edit` (auth, all roles, RBAC champs interne)

**Tests Vitest** (`frontend/tests/`)
- `SimulationList.test.tsx` : loading/error/empty + bouton "Nouvelle" gated par role.
- `MitreTechniquePicker.test.tsx` : autocomplete debounce, sélection met à jour, navigation clavier.
- `SimulationFormPage.test.tsx` : rôle redteam → tous champs éditables ; rôle soc → champs RT disabled, soc-side enabled si status review_required, bandeau si pending.
- `SimulationStatusBadge.test.tsx` : 4 variants.

### Règles
- Lit le summary du backend EN PREMIER (contrat API).
- Pas d'invention d'endpoints. Mismatch → escalade au team-lead.
- Réutiliser `LoadingState`, `ErrorState`, `EmptyState`, `Toast`, `FormField`, `StatusBadge` existants. NE PAS dupliquer.
- Respect DESIGN.md (utiliser tokens Tailwind existants — pas de couleurs hardcodées).
- Pas de CDN remote.

---

## 4. Definition of Done — Sprint 2

- [ ] Tous les critères AC-7 → AC-12 passent.
- [ ] `pytest` (existing 63 + nouveaux ~25) tous verts. `ruff`, `mypy` clean.
- [ ] `npm run typecheck`, `lint`, `test` clean frontend.
- [ ] Playwright suite (existing 36 + nouveaux ~15) verte.
- [ ] `make build` + `make start` + `make update-mitre` + workflow simulation complet manuel OK.
- [ ] Code-reviewer (Opus) sans BLOCKER ouvert.
- [ ] `SPEC.md` (section Simulation enrichie si besoin), `README.md` (mention `make update-mitre` + workflow), `CHANGELOG.md` à jour.
- [ ] PR ouverte sur `sprint/2-simulations`, récap synthétique team-lead, validation utilisateur.

---

## 5. Décisions arrêtées (utilisateur 2026-05-26)

1. **Source MITRE** : `https://raw.githubusercontent.com/mitre/cti/master/enterprise-attack/enterprise-attack.json` (default team-lead).
2. **MITRE bundle dans le repo** : COMMITTÉ (`backend/data/mitre/enterprise-attack.json` versionné, `make build` autosuffisant).
3. **Commands storage** : colonne `text` multiligne, une commande par ligne, transport tel quel.
4. **Workflow auto-transition** pending→in_progress : déclenchée par toute PATCH admin/redteam touchant ≥1 champ redteam à valeur non vide (default team-lead).
5. **Page simulation** : UNE page d'édition role-aware (`/engagements/:eid/simulations/:sid/edit`), pas de page détail séparée.
6. **Suppression cascade** : delete engagement → delete simulations (default team-lead).
7. **SOC restriction status** : soc ne peut PATCH que si status ∈ {review_required, done}.
8. **Sous-techniques MITRE** : incluses dans l'autocomplete (T1059.001 visible) (default team-lead).

---

## 6. Plan d'exécution (séquence)

1. ✅ User a validé les 8 décisions §5 (2026-05-26).
2. ✅ **Spec-reviewer** : APPROVED WITH NOTES (4 items mineurs corrigés avant dispatch).
3. ✅ **Backend-builder** : commit `006c4c2` (67 nouveaux tests, 130 passing).
4. ✅ **Frontend-builder** : commit `765bb5a` (41 nouveaux tests, 61 passing).
5. ✅ **Code-reviewer** : 2 MAJOR + 4 MINOR + 3 NITs → 2 commits de fix (`83bf60f` backend, `c9032a9`+`cf0e8a8` frontend).
6. ✅ **Test-verifier** : 32/32 sprint 2 verts, commits `da905cc` + `54e90f7` (AC-4.9 refresh).
7. 🟡 **Team-lead** : récap + PR en cours.

Branche unique : `sprint/2-simulations`.