Files

Knacky 01434c04a7 docs(plan): sprint 6 — engagement export (md/csv/pdf) plan

3 user stories scoped (US-29 export formats, US-30 SOC zero access,
US-31 format/engagement robustness). Backend extends engagements_bp
with GET /api/engagements/<id>/export?format=md|csv|pdf returning the
rendered file, no DB schema change. Frontend adds an
ExportEngagementButton split-button dropdown on EngagementDetailPage,
gated to admin+redteam.

Binding decisions locked with the user: 3 formats Markdown/CSV/PDF,
RBAC admin+redteam, engagement + all simulations RT+SOC, single
endpoint with format query param. WeasyPrint chosen for PDF (Python
HTML→PDF, ~50MB cairo/pango deps to add to Dockerfile, accepted).

Plan ready for spec-reviewer Pass 1.

2026-06-07 18:29:59 +02:00

18 KiB

Raw Blame History

Sprint 6 — Engagement export (Markdown + CSV + PDF)

Branch : sprint/6-export · Worktree : .claude/worktrees/sprint-6-export · Base : main @ 678ee8f

§0 — Binding decisions (locked with the user 2026-06-07)

Scope du sprint : export d'un engagement (header + toutes ses simulations RT + SOC) vers Markdown, CSV et PDF — clôt la boucle « remplace l'utilisation d'un fichier excel plat partagé entre la redteam et les analystes SOC en fin de mission ».
Formats livrés : Markdown, CSV, PDF (3 formats). JSON exclu (redondant avec l'API existante).
RBAC : admin + redteam peuvent exporter. SOC = pas d'accès (pas de bouton dans l'UI, endpoint /api/engagements/<eid>/export → 403). Cohérent avec le pattern templates sprint 5 (livrable RedTeam).
Contenu de l'export : Engagement header (name, description, dates, status, created_by, created_at) + toutes les simulations de l'engagement, avec leurs champs RT (name, techniques, tactics, description, commands, prerequisites, executed_at, execution_result, status) ET SOC (log_source, logs, soc_comment, incident_number). Ordre des simulations : id ASC (ordre de création).
Déclenchement UI : un bouton split-button dropdown sur EngagementDetailPage libellé [Export ▼], qui ouvre un menu Markdown / CSV / PDF. Click → download direct (Blob + URL.createObjectURL). Pas de modal de configuration. Pattern réutilisé du dropdown sprint 5 (SimulationList).

Décisions techniques arrêtées par le team-lead (à challenger par spec-reviewer)

Endpoint backend : un seul endpoint GET /api/engagements/<eid>/export?format=md|csv|pdf plutôt que 3 endpoints distincts. Une seule route à protéger (RBAC), un seul test d'intégration RBAC, switch sur format en interne. Format inconnu → 400 {error: "format must be one of: md, csv, pdf"}. Format manquant → 400 (pas de défaut implicite — évite l'ambiguïté).
Markdown : généré via string templating Python (pas de lib externe). Simple, déterministe, testable par assertion de sous-chaînes.
CSV : généré via csv.writer (stdlib). Une ligne d'en-tête + N lignes simulations. Colonnes : id, name, status, techniques (joined "|"), tactics (joined "|"), description, commands, prerequisites, executed_at, execution_result, log_source, logs, soc_comment, incident_number, created_at, updated_at. Pas de header engagement dans le CSV (format machine-readable strict) ; l'engagement context sort dans le filename.
PDF : généré via WeasyPrint (Python HTML→PDF, lib mature, qualité de rendu pro, dépendances système cairo/pango/gdk-pixbuf à ajouter au python:3.12-slim du Dockerfile). Pipeline : on génère le même HTML que pour le Markdown (mais wrappé en <html>...<style>...</html>), puis WeasyPrint le rend en PDF. Le styling CSS est inline (≤ 30 lignes : hierarchy h1/h2/h3, code-block monospace, alternance fond pour les simulations). Pas de logo / page de garde — keep it simple.
Filename convention : engagement-<id>-<slugified-name>-YYYYMMDD.{ext}. Slugification = re.sub(r'[^a-z0-9]+', '-', name.lower()).strip('-')[:60]. YYYYMMDD = date.today().strftime('%Y%m%d') côté serveur. Le frontend lit Content-Disposition pour le nom du fichier.
Content-Type : text/markdown; charset=utf-8, text/csv; charset=utf-8, application/pdf.
Génération synchrone : Flask renvoie le fichier dans la même requête (un engagement = quelques dizaines de simulations max, génération < 500 ms même PDF). Pas de job async.
Pas de cache : chaque export régénère depuis la DB (état toujours frais).
Frontend client : pour télécharger, on utilise un fetch avec responseType: 'blob', on lit Content-Disposition pour le filename, puis URL.createObjectURL + <a> invisible + click(). Pas de navigation. Le bouton [Export ▼] partage l'esthétique du [+ New ▼] du sprint 5 (bg-canvas, text-ink, border, rounded, shadow-soft-lift + dark:shadow-soft-lift-dark).

Points OUVERTS pour le spec-reviewer (à valider Pass 1)

WeasyPrint vs alternatives : retenu pour rendu pro + pipeline HTML mutualisable. Alternatives écartées : reportlab (layout programmatique = beaucoup plus de code), xhtml2pdf (rendu inférieur), pdfkit + wkhtmltopdf (binaire externe en archive partielle). Le coût Dockerfile (≈ 50 MB de libs cairo/pango) est accepté.
CSV sans header engagement : choix de pureté tabulaire (Excel-friendly direct). Le team-lead a tranché. Spec-reviewer doit confirmer ou proposer la variante "1 ligne commentaire # Engagement: <name>".
Pas de JSON export : redondant avec l'API. À confirmer.
Statut done inclus comme tous les autres : pas de filtre par défaut. L'utilisateur exporte toujours TOUT.

§1 — Backend (Sonnet · backend-builder)

Modèle de données

Aucun changement de modèle. Pas de migration. L'export est en lecture seule sur les modèles existants Engagement + Simulation.

Services / serializers

Nouveau module backend/app/services/export.py avec 3 fonctions pures testables unitairement :
- render_engagement_markdown(engagement: Engagement, simulations: list[Simulation]) -> str
- render_engagement_csv(engagement: Engagement, simulations: list[Simulation]) -> str
- render_engagement_pdf(engagement: Engagement, simulations: list[Simulation]) -> bytes
Le rendu Markdown réutilise _enrich_techniques + _enrich_tactics de serializers.py pour avoir [{id, name}] au lieu de juste les IDs.
Le rendu PDF construit l'HTML à partir d'un template Python _render_engagement_html(engagement, simulations) -> str (string templating, pas Jinja — KISS) et le passe à weasyprint.HTML(string=html).write_pdf().

Endpoint

Extension du blueprint engagements_bp existant. Path : GET /api/engagements/<int:eid>/export?format=md|csv|pdf.
Décorateur : @role_required("admin", "redteam").
Logique :
1. Charger l'engagement (404 si absent).
2. Parse format query param. Format manquant ou inconnu → 400 {error: "format must be one of: md, csv, pdf"}.
3. Charger les simulations triées par id ASC.
4. Appeler la fonction render_engagement_<fmt>(engagement, simulations).
5. Construire la Response avec Content-Type, Content-Disposition: attachment; filename="<slug>.<ext>", et le body.
Filename helper : _export_filename(engagement, ext) -> str (slugifier + date).

Tests

Cible : 226 → 245+ pytest passing.

Fichiers nouveaux :

backend/tests/test_export_engagement.py — couvre l'endpoint + RBAC + format inconnu.
- test_export_markdown_admin_returns_md_with_engagement_header_and_all_simulations
- test_export_markdown_redteam_ok
- test_export_markdown_soc_403
- test_export_csv_returns_csv_with_one_row_per_simulation
- test_export_csv_columns_match_contract (assert exact header row)
- test_export_csv_escapes_special_characters (commands avec virgule, guillemet, newline)
- test_export_pdf_returns_pdf_magic_bytes_and_non_empty
- test_export_unknown_format_400
- test_export_missing_format_400
- test_export_unknown_engagement_404
- test_export_engagement_with_zero_simulations_renders_header_only
- test_export_unauthenticated_401
- test_export_filename_slugifies_name_and_carries_date
backend/tests/test_export_render.py — tests unitaires sur les 3 fonctions pures.
- test_render_engagement_markdown_includes_header_fields
- test_render_engagement_markdown_lists_all_simulations_in_order
- test_render_engagement_markdown_includes_techniques_with_id_and_name
- test_render_engagement_markdown_includes_tactics
- test_render_engagement_markdown_includes_soc_fields_even_when_blank (cohérence handoff)
- test_render_engagement_markdown_escapes_backticks_in_commands (fenced code block safety)
- test_render_engagement_csv_has_header_row
- test_render_engagement_csv_joins_multi_techniques_with_pipe
- test_render_engagement_pdf_starts_with_pdf_magic (assert output[:4] == b'%PDF')

Dépendances

weasyprint>=60.0 ajouté à backend/requirements.txt.
docker/Dockerfile stage Python : ajouter apt-get install -y libcairo2 libpango-1.0-0 libpangoft2-1.0-0 libgdk-pixbuf-2.0-0 libffi-dev shared-mime-info (liste minimale WeasyPrint pour Debian slim). Documenter dans le PR.

Livrable backend-builder (summary attendu)

Tous les fichiers créés/modifiés
Contrat API précis (statuts, query params, headers de réponse) en table
Liste des helpers réutilisés (_enrich_techniques, _enrich_tactics, serialize_user_brief)
Section "Déviations vs plan" explicite (cf. lesson sprint 5 — URL drift silencieuse à interdire)
Résultats pytest + ruff + mypy

§2 — Frontend (Sonnet · frontend-builder)

Composants

ExportEngagementButton.tsx (nouveau) : split-button dropdown style sprint 5.
- Bouton principal Export (icône Download lucide-react) + chevron à droite (icône ChevronDown).
- Click sur principal : ouvre le dropdown (pas d'action par défaut).
- Dropdown : 3 items "Markdown" / "CSV" / "PDF". Click → mutation download.
- Fermeture : click outside + Escape (réutiliser le hook/effet du dropdown sprint 5 dans SimulationList).
- Loading state : pendant la mutation, le composant affiche un spinner inline sur l'item cliqué, le dropdown reste ouvert. Désactive les 3 items pendant l'in-flight.
- Toast erreur sur 4xx/5xx.
EngagementDetailPage.tsx : intégrer <ExportEngagementButton engagementId={engagement.id} /> dans le header de la page, à côté des autres CTAs existants (edit/close). Visible uniquement si currentUser.role in ['admin', 'redteam'] (gate côté UI + RBAC backend de toute façon en force).

API client

frontend/src/api/exports.ts (nouveau) :
- downloadEngagementExport(engagementId: number, format: 'md' | 'csv' | 'pdf'): Promise<void> — fait un GET /api/engagements/<id>/export?format=<fmt> avec responseType: 'blob', lit Content-Disposition pour le filename, crée un Blob + URL.createObjectURL + <a>.click(), puis URL.revokeObjectURL.
- Helper parseContentDispositionFilename(header: string | undefined): string | null (regex filename="...", fallback null).

Types

Aucun nouveau type API (l'export retourne un Blob).

Tests

Cible : 121 → 130+ vitest passing.

Fichiers nouveaux :

frontend/tests/ExportEngagementButton.test.tsx
- renders Export button with chevron
- clicking primary opens dropdown with three formats
- clicking outside closes dropdown
- Escape closes dropdown
- clicking Markdown triggers download with format=md
- clicking CSV triggers download with format=csv
- clicking PDF triggers download with format=pdf
- loading state disables items during in-flight
- error response shows toast
frontend/tests/EngagementDetailPage.test.tsx (existant — adapter) :
- admin sees Export button
- redteam sees Export button
- soc does NOT see Export button

Screenshots OBLIGATOIRES (lesson sprint 4)

EngagementDetailPage light + dark, dropdown fermé.
EngagementDetailPage light + dark, dropdown ouvert (3 items visibles).
EngagementDetailPage SOC view — bouton Export ABSENT.
Le builder doit fournir un script Playwright authenti (réutiliser le pattern sprint 5 — page.goto('/login') → fill → wait nav).

Livrable frontend-builder (summary attendu)

Tous les fichiers créés/modifiés
API contracts consommés exactement comme livrés par backend (cf. lesson sprint 5 — path drift à éviter, grep Content-Disposition dans la PR)
Helpers réutilisés (useToast, etc.)
Résultats vitest + typecheck + lint
Liste des écrans capturés (light + dark, role-by-role)

§3 — Acceptance tests (Sonnet · test-verifier)

Cible : 201 → 215+ Playwright passing.

3 user stories à couvrir :

US-29 — Admin/redteam exporte l'engagement en Markdown/CSV/PDF

AC-29.1 : login admin → engagement avec ≥ 2 simulations → click "Export" → dropdown s'ouvre.
AC-29.2 : click "Markdown" → download d'un .md avec Content-Type: text/markdown. Le fichier contient le nom de l'engagement, la date de début, et le nom de chaque simulation.
AC-29.3 : click "CSV" → download d'un .csv avec exactement N+1 lignes (1 header + N simulations). La colonne name contient les noms des simulations.
AC-29.4 : click "PDF" → download avec Content-Type: application/pdf, taille > 1 KB, magic bytes %PDF.
AC-29.5 : login redteam → mêmes 3 formats fonctionnent.
AC-29.6 : filename respecte engagement-<id>-<slug>-YYYYMMDD.{ext} (assert via Content-Disposition).

US-30 — SOC pas d'accès à l'export

AC-30.1 : login SOC → engagement page → bouton "Export" ABSENT du DOM (pas seulement display: none).
AC-30.2 : appel direct API GET /api/engagements/<id>/export?format=md (Bearer SOC) → 403.
AC-30.3 : (sanity) appel API sans token → 401.

US-31 — Robustesse format / engagement

AC-31.1 : GET /api/engagements/<id>/export sans format → 400 message friendly.
AC-31.2 : GET /api/engagements/<id>/export?format=xml → 400 friendly.
AC-31.3 : GET /api/engagements/99999/export?format=md → 404.
AC-31.4 : engagement avec 0 simulations → export OK (header seul, le CSV n'a qu'une ligne d'en-tête, le MD n'a pas de section simulation).

Bouncing

Si un AC échoue → bounce au builder responsable (backend ou frontend), pas de patch test-side.

§4 — Reviews

Spec-reviewer Pass 1 (avant dispatch)

Lit ce tasks/todo.md § 0 + § 1 + § 2 + § 3.
Verdict attendu : APPROVED / NEEDS-CHANGES par section.
Points particuliers à challenger : WeasyPrint vs reportlab, CSV sans header engagement, URL drift (un seul endpoint avec query param vs 3 endpoints distincts).

Spec-reviewer Pass 2 (après mes éventuels édits du plan)

Re-validation des changements apportés.
TEAM-LEAD : ne PAS dispatcher backend tant que Pass 2 n'a pas répondu APPROVED. Lesson sprint 5 — la patience sur le 2-pass a éliminé les addenda mid-implementation.

Code-reviewer (après backend + frontend)

LSP first (goToDefinition, findReferences).
Focalise sur : pureté des render functions (testables), gestion des deps WeasyPrint dans Dockerfile, échappement CSV, filename slug, dropdown close-on-outside réutilisation.

Design-reviewer (après screenshots frontend)

Light + dark cohérence du dropdown Export.
Vérifie que le bouton respecte la convention "icône + label court ≤ 8 chars" (Export).
Audit alignement vs le header existant de la page.

Test-verifier (après code-reviewer APPROVED)

Écrit 1 spec file par US (us29-export-formats, us30-export-rbac, us31-export-robustness).
Rapport pass/fail par AC.

§5 — SPEC.md update (au tout début du sprint — lesson sprint 3/4/5)

Ajouter une section § Export d'engagement entre § Templates de simulations et § Authentification & rôles :

Export d'engagement

Un engagement peut être exporté à tout moment dans 3 formats au choix : Markdown (handoff narratif), CSV (machine-readable, intégration tableurs), PDF (livrable client). L'export contient l'en-tête de l'engagement et toutes ses simulations avec les champs Red Team et SOC. Endpoint unique : GET /api/engagements/<id>/export?format=md|csv|pdf. Réservé aux rôles admin et redteam (livrable RedTeam, cohérent avec le RBAC Templates). Filename normalisé : engagement-<id>-<slug>-YYYYMMDD.<ext>.

Le commit qui crée cette section doit être le PREMIER commit du sprint (pas le dernier — sinon on rate le bug récurrent identifié dans les lessons). Le commit suivant peut être le plan lui-même (tasks/todo.md + tasks/lessons.md).

§6 — Workflow git du sprint

Branch : sprint/6-export (créée @ 678ee8f).
Commit séquence :
1. docs(spec): add § Export d'engagement section (le M SPEC.md ne doit JAMAIS rester unstaged)
2. docs(plan): sprint 6 plan + sprint-5 lessons folded (tasks/)
3. Commits backend (un ou deux, signés par backend-builder)
4. Commits frontend (un ou deux, signés par frontend-builder)
5. Commit post-code-review fixes (si nécessaire)
6. Commit screenshots design + e2e tests
7. Wrap-up commit team-lead : CHANGELOG + README + lessons.md sprint-6 + plan final
PR via make open-pr SPRINT=6 TITLE="feat: sprint 6 — engagement export (md/csv/pdf)" BODY=tasks/pr-body-sprint-6.md (3e dogfood du wrapper sprint 4).

§7 — Risk / hazard list

#	Risk	Mitigation
1	WeasyPrint deps gonflent l'image Docker	Liste minimale documentée + WeasyPrint déjà packagé sur Debian slim ; mesurer Δ MB image build après vs avant
2	CSV mal-échappé avec commands multilines / quotes	Utiliser `csv.writer` stdlib (handles tout automatiquement), pas de string concat manuel
3	Markdown casse sur backticks dans commands	Fenced code blocks `~~~bash` (tildes au lieu de backticks pour les blocks contenant des backticks), OU escape via `markdown.escape`
4	Test PDF fragile sur le contenu	Asserter UNIQUEMENT : Content-Type, magic bytes `%PDF`, taille > 1 KB. Pas de regex sur le texte rendu (binary).
5	URL drift backend (`/export` vs `/engagements/<id>/export`)	Lesson sprint 5 — la 1re ligne du backend summary doit confirmer le path exact
6	Frontend oublie `URL.revokeObjectURL` → fuite mémoire	Test unitaire explicite : assert `revokeObjectURL` appelé après le click téléchargement
7	SPEC.md uncommitted à la fin du sprint (3 sprints en série !)	Commit SPEC.md en commit #1 du sprint, pas en wrap-up. Étape « cendrillon » du plan ci-dessus.

§8 — Definition of Done (sprint-level)

§5 SPEC.md committed AS THE FIRST COMMIT of the sprint.
Backend : 245+ pytest, ruff clean, mypy clean.
Frontend : 130+ vitest, typecheck clean, lint clean.
E2e : 215+ Playwright, 0 régression vs main.
Screenshots fournies : EngagementDetailPage light + dark, dropdown fermé + ouvert, vue SOC sans bouton.
Dockerfile mis à jour avec deps WeasyPrint + make build réussit.
CHANGELOG.md [Unreleased] → Sprint 6 rédigée.
README.md « Status » bumped + section dans le tableau des features si pertinent.
PR ouverte via make open-pr (pas via UI manuelle).
git status au sprint-close affiche uniquement des fichiers ignorés (lesson récurrente).

18 KiB Raw Blame History

Sprint 6 — Engagement export (Markdown + CSV + PDF)

§0 — Binding decisions (locked with the user 2026-06-07)

Décisions techniques arrêtées par le team-lead (à challenger par spec-reviewer)

Points OUVERTS pour le spec-reviewer (à valider Pass 1)

§1 — Backend (Sonnet · backend-builder)

Modèle de données

Services / serializers

Endpoint

Tests

Dépendances

Livrable backend-builder (summary attendu)

§2 — Frontend (Sonnet · frontend-builder)

Composants

API client

Types

Tests

Screenshots OBLIGATOIRES (lesson sprint 4)

Livrable frontend-builder (summary attendu)

§3 — Acceptance tests (Sonnet · test-verifier)

US-29 — Admin/redteam exporte l'engagement en Markdown/CSV/PDF

US-30 — SOC pas d'accès à l'export

US-31 — Robustesse format / engagement

Bouncing

§4 — Reviews

Spec-reviewer Pass 1 (avant dispatch)

Spec-reviewer Pass 2 (après mes éventuels édits du plan)

Code-reviewer (après backend + frontend)

Design-reviewer (après screenshots frontend)

Test-verifier (après code-reviewer APPROVED)

§5 — SPEC.md update (au tout début du sprint — lesson sprint 3/4/5)

Export d'engagement

§6 — Workflow git du sprint

§7 — Risk / hazard list

§8 — Definition of Done (sprint-level)

18 KiB

Raw Blame History