mimic/SPEC.md

Prompt

Mimic est une application WebUI de type BAS (Breach and Attack Simulation), se basant sur la matrice MITRE ATT&CK. Cette application doit permettre de réaliser des tests en purple Team en fin de mission Read Team. Elle doit être simple et conviviale à utiliser. Elle remplace l'utilisation d'un fichier excel plat que l'on partage entre la redteam et les analystes SOC en fin de mission red team.

Details

Simulation

Une simulation est composée des champs suivants :

• Partie RedTeam :
  • Nom du test
  • Types d'attaque MITRE correspondants (multi-techniques — une simulation peut couvrir plusieurs TTPs) sélectionnables par autocomplete OU via la matrice ATT&CK affichée en modale. Sub-techniques (ex : T1059.001) supportées.
  • Description
  • Commandes exécutés (liste)
  • Pré-requis (champs texte)
  • Date et heure d'exécution
  • Résultat d'exécution
• Partie Analyste SOC :
  • Source des logs
  • Logs obtenues
  • Commentaires
  • Numéro incident correspondant

Fonctionnement

La redteam peut modifier l'ensemble des champs d'une simulation, tandis que l'analyste SOC ne peut remplir que sa partie. Un workflow de simulation doit être mis en place : Pending, In progress, Review required, Done. Le workflow se mettra à jour de la manière suivante :

• Création de la simulation : pending
• La redteam saisit des informations dans la simulation : in progress
• La redteam décide par une action manuelle de passer la simulation en status "review required" ce qui offre à la possibilité au SOC de remplir les informations nécessaire.
• Le SOC (ou la redteam) décide par une action manuelle de passe la simulation en status "Done".

Un engagement correspond à une mission redteam. Il est possible d'ajouter plusieurs test dans un engagement.

Prévoir un module d'authentification : dans un premier temps local à la bdd.

Dans un premier temps, il s'agit juste de notifier manuellement de l'exécution et les résultats des tests. Dans un second temps, après que la V1 soit terminée, nous ajouterons une couche permettant de se connecter à un C2 (mythic ou maison) afin d'exécuter des simulation au travers du C2.

Stacks techniques

• FrontEnd : WebUI
  • Stacks standard : ReactJS, Vite, TailWind etc...
  • Evite l'utilisation de remote librairie un maximum, télécharge toujours les ressources en local si possible.
  • Design récent et UI respectant le fichier DESIGN.md
• Backend : Flask Python, Base de données SQLLite
• Livrable : Container compatible Docker/Podman et Makefile pour gérer les différents états des containers - start, stop, restart, update, build, etc.

Points importants

• Ne prend pas d'initiative. Si tu doutes d'une fonctionnalité, pose les questions afin de pouvoir coder la fonctionnalité.
• Focus sur la méthode KISS : Keep It Simple and Stupid. Limite toi à des fonctionnalités simples sans entreprendre du coding couteux avec des fonctionnalités non demandées.

Workflows

• Découpage en sprint
• Chaque sprint doit apporter une nouvelle fonctionnalité à tester sur l'UI
• A chaque sprint : Code + Test (Test unitaire python + Test pywright front) + Reviews (spec + code). Une fois le review OK, PR que je valide après test.
• A chaque fin de sprint, avant mes tests, le team lead doit me faire un récapitulatif synthétique de ce qui a été fait et ce qui doit être testé (et comment le tester).

Team

Pour ce projet, j'ai besoin d'une équipe d'agent réparti de la manière suivante :

1. Team leader : modèle Opus

• Lit les spec et réparti les tâches entre les différents agents
• En charge de la livraison de son sprint et de la création des PR
• Met à jour le README.md quand nécessaire
• Met à jour le fichier SPEC.md quand de nouvelles fonctionnalités ou des précisions sont apportées à certains points
• Réfléchit à l'aspect architecturale de l'application
• Rédige et dispatch les technical briefs

2. Backend builder : modèle Sonnet

• Développement backend uniquement
• What it builds: → API routes → Services and business logic → Database access and migrations → Background jobs → Unit tests for everything it writes
• What it cannot do: → Touch React components, pages, or client-side hooks (that's Agent 5) → Invent new dependencies without instruction → Modify files outside agreed scope → Stop without running typecheck, lint, and the test suite
• After finishing, it returns a summary: → Every file added or edited → Every existing helper or pattern reused → Any CLAUDE.md rule that would have helped
  • Tools: Read, Edit, Write, Bash — scoped to backend folders only.
• Livre un code simple à comprendre sans essayer de prévoir l'avenir (se limiter au scope)
• Ne prend pas de décision ou d'hypothèse. Si des questions subsitent, il les remonte au team lead qui décidera de la position à prendre en fonction des contraintes énnoncés par le développeur.
• Livre un code propre, avec les tests appropriés (success, failure, edge cases)

3. Front builder : modèle Sonnet
   • Développement frontend uniquement
   • It reads the Backend Builder's summary first.
   • It consumes the API exactly as the backend produced it.
   • It does not invent new endpoints.
   • If the API shape is wrong for the UI, it surfaces the mismatch as feedback — not as a patch.
   • Input it receives: → Approved technical brief → Researcher's findings → Backend Builder's summary (the API contract)
   • What it builds: → React components and pages → Client-side hooks and state → Loading and error states → Component and unit tests for everything it writes
   • What it cannot do: → Touch services, API routes, workers, or migrations (that's Agent 4) → Invent endpoints or response shapes → Add dependencies without instruction → Stop without running typecheck, lint, and the test suite
   • Tools: Read, Edit, Write, Bash — scoped to frontend folders only

• Livre un code simple à comprendre sans essayer de prévoir l'avenir (se limiter au scope)
• Ne prend pas de décision ou d'hypothèse. Si des questions subsitent, il les remonte au team lead qui décidera de la position à prendre en fonction des contraintes énnoncés par le développeur.
• Livre un code propre, avec les tests appropriés (success, failure, edge cases)

4. Spec reviewer : modèle Sonnet
   • Avant chaque début de sprint, lit les plans du team leader et valide les tâches à donner au développeur
   • Si le plan s'éloigne des spec énoncés, le dire au team leader afin qu'il mette à jour son plan pour répondre aux besoins énoncés
5. Code reviewer : modèle Opus

• A la fin de chaque sprint, avant de réaliser la PR, cet agent relit le code généré par le développeur sur le sprint courant (pas tout le code, juste celui du scope).
• Utilise un maximum les LSP quand c'est possible
• Vérifie si des optimisations ou des factorisations de code sont possibles suite aux nouvelles implémentations du développeur.
• Dans le cas ou des erreurs ou des optimisations ou des factorisations sont possible, les remontés directement au développeur afin qu'il traite les erreurs et en informer le team lead.
• Quand le code review est OK, en informer le test verifier pour qu'il réalise ses tests à son tour.

6. Test verifier : modèle Sonnet
   • The Test Verifier does one thing only: prove that the feature actually does what the user story said it should.
   • It writes acceptance tests. Not unit tests.
   • These test the feature from the outside — the way a real user would experience it.
   • Input it receives: → Approved user story (with all acceptance criteria) → Approved technical brief → Both builders' summaries
   • What it produces: → One acceptance test file covering every acceptance criterion → A report: which criteria passed, which failed, which can't be covered cleanly
   • What it cannot do: → Modify any backend or frontend code → Invent workarounds for untestable criteria → Mark a criterion as covered if it genuinely isn't
   • If a test fails: the feature doesn't satisfy the story.
   • It reports exactly which criterion failed.
   • It does not patch the code.
   • That goes back to the right builder.
   • Tools: Read, Edit, Write (test files only), Bash.
   • The rule: you don't have a feature until the acceptance tests pass.
   • Quand tout est ok pour le test verifier en informer le team lead afin qu'il prépare la PR.
7. Devil advocate : modèle Opus

• Dans le cas de questions structurantes sur le projet, faire intervenir cet agent en tant que tierce personne n'ayant pas connaissance de tout le projet mais permettant d'avoir un regarde neuf sur ces questions.

Décisions techniques

Décisions arrêtées avec l'utilisateur au démarrage du projet. Ces choix doivent guider les sprints et peuvent évoluer — toute évolution est tracée dans le CHANGELOG.md.

Authentification & rôles

• Trois rôles : admin, redteam, soc.
  • admin : super-user. Gestion des comptes (CRUD users) et CRUD complet sur engagements/simulations (cumule les droits de redteam). Décision élargie le 2026-05-26 pour éviter qu'un admin doive se créer un second compte redteam pour gérer les engagements opérationnellement.
  • redteam : CRUD complet sur engagements et simulations (tous champs).
  • soc : lecture des simulations, écriture restreinte à la partie SOC (logs, sources, commentaires, n° incident).
• Méthode : JWT Bearer token (login /api/auth/login → access token). Refresh token à décider plus tard si besoin.
• Mot de passe : hash argon2 (ou bcrypt si argon2 indisponible).
• Création de comptes : par admin uniquement via UI. Pas de self-registration.
• Bootstrap du 1er admin : commande Flask flask create-admin <user> <pass> exposée via une target Makefile (make create-admin USER=… PASS=…) qui wrap docker exec mimic flask create-admin …. Aucun credential par défaut, aucun secret persisté en .env.

Modèle de données — V1

User

Champ	Type	Notes
id	int (PK)
username	str unique
password_hash	str	argon2/bcrypt
role	enum(admin/redteam/soc)
created_at	datetime

Engagement

Modèle minimal Sprint 1 (extensible plus tard) :

Champ	Type	Notes
id	int (PK)
name	str	requis
description	text	optionnel
start_date	date	requis
end_date	date	optionnel, ≥ start_date
status	enum(planned/active/closed)	défaut planned
created_at	datetime
created_by	FK User

Simulation (Sprint 2+)

Conforme à la spec (partie RedTeam + partie SOC). Workflow Pending → In progress → Review required → Done. Détaillé dans le sprint correspondant.

Référentiel MITRE ATT&CK

• Bundle local : JSON officiel STIX 2.1 MITRE Enterprise embarqué dans l'image (backend/data/mitre/enterprise-attack.json).
• Pas d'appel réseau au runtime. Seed/refresh manuel via make update-mitre.
• Utilisé au Sprint 2+ pour l'autocomplete des TTPs (T-id + nom + tactique).

Stack technique précisée

• Backend : Python 3.12, Flask, SQLAlchemy, Alembic, pytest, ruff, mypy. Auth via PyJWT + middleware decorator.
• Frontend : React 18, Vite, TailwindCSS, TanStack Query, React Router, Vitest pour les unit tests composants.
• Tests acceptance : Playwright (TS), exécutés dans le container ou via runner CI.
• Conteneurisation : Container unique — Flask sert l'API sous /api/* et le build statique de Vite (frontend/dist) sous /. Un seul Dockerfile multistage (stage Node pour build front, stage Python pour run).
• Makefile : targets build, start, stop, restart, update, logs, create-admin USER=… PASS=…, update-mitre, test-backend, test-frontend, test-e2e.

Arborescence cible

mimic/
├── backend/
│   ├── app/
│   │   ├── __init__.py        # create_app() factory
│   │   ├── config.py
│   │   ├── extensions.py      # db, migrate
│   │   ├── models/
│   │   ├── api/               # blueprints
│   │   ├── services/
│   │   ├── auth/              # jwt, decorators
│   │   └── cli.py             # flask create-admin
│   ├── migrations/            # alembic
│   ├── tests/
│   ├── data/mitre/
│   ├── pyproject.toml
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── api/               # client + types
│   │   └── styles/
│   ├── tests/
│   ├── package.json
│   ├── vite.config.ts
│   └── tailwind.config.ts
├── e2e/                       # Playwright tests
├── docker/
│   └── Dockerfile
├── tasks/                     # plans sprint, lessons
├── DESIGN.md
├── SPEC.md
├── README.md
├── CHANGELOG.md
└── Makefile

Workflow git

• Branche par sprint : sprint/<num>-<short-name> (ex : sprint/1-auth-engagements).
• Sous-branches par builder si besoin : sprint/1-auth-engagements/backend, …/frontend.
• PR à la fin du sprint, validée par l'utilisateur après récap synthétique du team-lead.