Merge pull request #920 from Mathide-Team/feat/902-api-live-captures

feat(#902): API de capture en direct sur interfaces, un filtre BPF par point

Author: MathildeDec

docs/api-rest.md

@@ -81,6 +81,9 @@ La spécification OpenAPI est disponible sur :
 | `POST` | `/tools/export` | Sous-ensemble filtré (`file`, `bpf`, `time_start`, `time_end`, `endpoints`, `format`) : `--export-pcap` (issue #886) |
 | `POST` | `/tools/adjust-time` | Recalage (`file`, puis `time_offset`, `normalize` ou `align_to`, `format`) : `--adjust-time-output` (issue #887) |
 | `POST` | `/tools/replay` | Rejeu (`file`, `interface`, `speed`, `loop`) : `--replay`. ÉMET du trafic réel ; refusé (403) sauf si `interface` figure dans `NETCROSS_REPLAY_INTERFACES` (liste séparée par des virgules, vide par défaut) ; 503 si tcpreplay absent (issue #871) |
+| `POST` | `/live-captures` | Capture en direct (JSON `points` : `name`, `interface`, `bpf` ; `duration` ; `points_order` ; `options` de `/captures/multi`) puis analyse ; 202. 403 si `NETCROSS_API_LIVE` n'est pas à 1, interface hors de `NETCROSS_API_LIVE_INTERFACES` ou `NETCROSS_API_TOKEN` absent ; 409 si une capture est déjà en cours (issue #902) |
+| `GET` | `/live-captures/{id}` | État (`capturing`, `analysing`, `completed`, `failed`), `bytes_captured` par point, `elapsed_seconds`, `packet_count`, `analysis_id` |
+| `POST` | `/live-captures/{id}/stop` | Arrêt anticipé ; l'analyse porte sur ce qui a été capturé |
 | `GET` | `/analyses/{id}/annotations` | Annotations par point (`point`, `tag`) : même format que le sidecar `<capture>.annotations.json` de la GUI (issue #910) |
 | `POST` | `/analyses/{id}/annotations` | Ajoute une annotation (JSON `point`, `frame_number`, `tag`, `comment`, `color`) ; même trame et étiquette = mise à jour ; 404 point inconnu, 422 saisie invalide |
 | `DELETE` | `/analyses/{id}/annotations?point=&frame_number=&tag=` | Supprime une annotation ; 404 si absente |

docs/class-diagram.md

@@ -11,7 +11,7 @@
 > Il remplace l'ancienne section 3 de `docs/features-backlog.md`, tenue à la main, qui avait dérivé
 > (voir `docs/sessions/session-36.md`, issue #140).
 
-198 modules · 285 classes · 690 fonctions publiques de module.
+199 modules · 288 classes · 694 fonctions publiques de module.
 
 Conventions : `+` public, `-` privé (préfixe `_`) ; `int?` = `int | None` ; `list~str~` = `list[str]` ;
 `<<module>>` regroupe les fonctions publiques d'un module ; `A --> B : champ` = `A` a un champ annoté
@@ -42,8 +42,8 @@ flowchart TD
     netcross_gtk4 -->|"6 imports"| pcap_parser
     netcross_api -->|"19 imports"| netcross_report
     netcross_api -->|"5 imports"| netcross_ai
-    netcross_api -->|"48 imports"| netcross_core
-    netcross_api -->|"3 imports"| pcap_parser
+    netcross_api -->|"49 imports"| netcross_core
+    netcross_api -->|"4 imports"| pcap_parser
     netcross_report -->|"40 imports"| netcross_core
     netcross_ai -->|"10 imports"| netcross_core
     netcross_core -->|"19 imports"| pcap_parser
@@ -3893,6 +3893,7 @@ classDiagram
 | `netcross_api.batches` | lots de captures de l'API (issue #872). |
 | `netcross_api.bpf_routes` | bibliothèque de filtres BPF enregistrés (issue #906), équivalent API de ``--bpf-library NOM`` et des boutons « Filtres… » / « Enregistrer » de la GUI. |
 | `netcross_api.history_routes` | historique SQLite des runs (issue #874). |
+| `netcross_api.live_routes` | capture en direct sur des interfaces du serveur, puis analyse (issue #902), équivalent API de ``--live`` et de la case « Capture en direct » de la GUI. |
 | `netcross_api.lua_doc_routes` | documentation hors ligne de l'API Lua Wireshark (issue #873), équivalent de ``netcross-lua-doc --json``. |
 | `netcross_api.models` | modèles Pydantic pour les requêtes/réponses API (issue #209). |
 | `netcross_api.store` | analyses de l'API : statut, document JSON, persistance. |
@@ -4043,6 +4044,34 @@ classDiagram
         +register(app, verify) None
     }
 
+    %% ===== netcross_api.live_routes =====
+    class LivePoint {
+        <<BaseModel>>
+        +str name
+        +str interface
+        +str? bpf
+    }
+    class LiveCaptureRequest {
+        <<BaseModel>>
+        +list~LivePoint~ points
+        +float duration
+        +list~str~? points_order
+        +dict~str, Any~ options
+    }
+    class _LiveCaptures {
+        +start(req) dict~str, Any~
+        +get(capture_id) dict~str, Any~
+        +stop(capture_id) dict~str, Any~
+        +public(entry) dict~str, Any~
+    }
+    class mod_netcross_api_live_routes["netcross_api.live_routes"] {
+        <<module>>
+        +live_enabled(environ) bool
+        +allowed_interfaces(environ) frozenset~str~
+        +max_duration(environ) float
+        +register(app, verify, deps) _LiveCaptures
+    }
+
     %% ===== netcross_api.lua_doc_routes =====
     class mod_netcross_api_lua_doc_routes["netcross_api.lua_doc_routes"] {
         <<module>>
@@ -4152,6 +4181,7 @@ classDiagram
     }
 
     %% ===== relations =====
+    LiveCaptureRequest --> LivePoint : points
     netcross_api_models_SecurityReport --> SecurityFinding : findings
     MultiAnalysisSummary --> SegmentLoss : segments
 ```

docs/guide/api.md

@@ -89,6 +89,37 @@ encore disponibles par l'API. Utilisez pour cela la ligne de commande
 (voir [Comparer deux situations](comparer.md)). Le tableau complet des
 écarts entre surfaces est dans [Parité GUI / CLI / API](../parite-surfaces.md).
 
+## Capturer en direct sur le serveur
+
+L'API peut capturer elle-même sur les interfaces du serveur, un filtre BPF
+par point, comme `netcross --live`. C'est désactivé par défaut :
+l'administrateur l'active et choisit les interfaces autorisées.
+
+```bash
+export NETCROSS_API_TOKEN=un-secret          # obligatoire pour la capture
+export NETCROSS_API_LIVE=1
+export NETCROSS_API_LIVE_INTERFACES=eth0,eth1
+export NETCROSS_API_LIVE_MAX_DURATION=300    # secondes, 300 par défaut
+```
+
+Le compte du service doit avoir le droit de capturer (par exemple
+`sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap`, ou le groupe
+`wireshark`).
+
+```bash
+curl -X POST -H "X-API-Key: $NETCROSS_API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"points": [{"name": "LAN", "interface": "eth0", "bpf": "tcp port 443"},
+                  {"name": "WAN", "interface": "eth1"}],
+       "duration": 60, "options": {"nat_tolerant": true}}' \
+  http://localhost:8000/live-captures
+curl -H "X-API-Key: $NETCROSS_API_TOKEN" http://localhost:8000/live-captures/$CAPTURE_ID
+curl -X POST -H "X-API-Key: $NETCROSS_API_TOKEN" http://localhost:8000/live-captures/$CAPTURE_ID/stop
+```
+
+L'état passe de `capturing` à `analysing` puis `completed` ; il donne alors
+`analysis_id`, et le résultat se lit sous `/analyses/{analysis_id}` comme
+pour des fichiers envoyés. Une seule capture à la fois par serveur.
+
 ## Annoter une analyse
 
 ```bash

docs/openapi.yaml

@@ -2131,6 +2131,120 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/HTTPValidationError'
+  /live-captures:
+    post:
+      tags:
+      - live
+      summary: Start Live Capture
+      description: Démarre une capture en direct puis son analyse (équiv. ``--live``
+        + ``--live-duration``).
+      operationId: start_live_capture_live_captures_post
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/LiveCaptureRequest'
+        required: true
+      responses:
+        '202':
+          description: Successful Response
+          content:
+            application/json:
+              schema: {}
+        '403':
+          description: Capture en direct désactivée (NETCROSS_API_LIVE), interface
+            hors de NETCROSS_API_LIVE_INTERFACES, ou NETCROSS_API_TOKEN non défini
+        '404':
+          description: Capture inconnue
+        '409':
+          description: Une capture est déjà en cours
+        '422':
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
+      security:
+      - APIKeyHeader: []
+  /live-captures/{capture_id}:
+    get:
+      tags:
+      - live
+      summary: Get Live Capture
+      description: 'État : capturing, analysing, completed ou failed ; octets par
+        point ; analysis_id.'
+      operationId: get_live_capture_live_captures__capture_id__get
+      security:
+      - APIKeyHeader: []
+      parameters:
+      - name: capture_id
+        in: path
+        required: true
+        schema:
+          type: string
+          title: Capture Id
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                title: Response Get Live Capture Live Captures  Capture Id  Get
+        '403':
+          description: Capture en direct désactivée (NETCROSS_API_LIVE), interface
+            hors de NETCROSS_API_LIVE_INTERFACES, ou NETCROSS_API_TOKEN non défini
+        '404':
+          description: Capture inconnue
+        '409':
+          description: Une capture est déjà en cours
+        '422':
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
+  /live-captures/{capture_id}/stop:
+    post:
+      tags:
+      - live
+      summary: Stop Live Capture
+      description: Arrête la capture avant la fin de ``duration`` ; l'analyse porte
+        sur ce qui a été capturé.
+      operationId: stop_live_capture_live_captures__capture_id__stop_post
+      security:
+      - APIKeyHeader: []
+      parameters:
+      - name: capture_id
+        in: path
+        required: true
+        schema:
+          type: string
+          title: Capture Id
+      responses:
+        '200':
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+                title: Response Stop Live Capture Live Captures  Capture Id  Stop
+                  Post
+        '403':
+          description: Capture en direct désactivée (NETCROSS_API_LIVE), interface
+            hors de NETCROSS_API_LIVE_INTERFACES, ou NETCROSS_API_TOKEN non défini
+        '404':
+          description: Capture inconnue
+        '409':
+          description: Une capture est déjà en cours
+        '422':
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
   /analyses/{analysis_id}/annotations:
     get:
       tags:
@@ -3408,6 +3522,61 @@ components:
       type: object
       title: HealthResponse
       description: Réponse du health check.
+    LiveCaptureRequest:
+      properties:
+        points:
+          items:
+            $ref: '#/components/schemas/LivePoint'
+          type: array
+          title: Points
+          description: Points à capturer simultanément (au moins 1)
+        duration:
+          type: number
+          exclusiveMinimum: 0.0
+          title: Duration
+          description: Durée de capture en secondes (bornée par NETCROSS_API_LIVE_MAX_DURATION)
+        points_order:
+          anyOf:
+          - items:
+              type: string
+            type: array
+          - type: 'null'
+          title: Points Order
+          description: Ordre amont -> aval (sinon déduit du trafic)
+        options:
+          additionalProperties: true
+          type: object
+          title: Options
+          description: 'Options d''analyse de POST /captures/multi (mêmes noms : tls,
+            nat_tolerant, max_packets...)'
+      type: object
+      required:
+      - points
+      - duration
+      title: LiveCaptureRequest
+      description: Corps de ``POST /live-captures``.
+    LivePoint:
+      properties:
+        name:
+          type: string
+          title: Name
+          description: Nom du point (devient le point de capture de l'analyse)
+        interface:
+          type: string
+          title: Interface
+          description: Interface du serveur (autorisée par NETCROSS_API_LIVE_INTERFACES)
+        bpf:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Bpf
+          description: Filtre BPF de capture de ce point (ex. 'tcp port 443')
+      type: object
+      required:
+      - name
+      - interface
+      title: LivePoint
+      description: 'Un point de capture : nom, interface du serveur, filtre BPF propre.'
     MultiAnalysisSummary:
       properties:
         analysis_id:

docs/parite-surfaces.md

@@ -16,7 +16,7 @@ ici fait donc échouer la CI.
 |---|---|---|
 | CLI | `cross_capture_analyzer_cli.py` (110 options), `cross_capture_diff_cli.py` (27), `cross_capture_batch_cli.py` (11), `cross_history_cli.py`, `netcross_lua_doc_cli.py`, `netcross_ai_models_cli.py` | Surface de référence : tout y est |
 | GUI | `netcross_gtk4` : 3 pages, 43 cases à cocher, 31 réglages numériques | Analyse interactive et exploration visuelle |
-| API | 47 routes FastAPI | Analyse avec sécurité ; options NAT, TLS, QUIC, anonymisation ; exports texte, PDF, CSV (issue #670) ; options avancées (#672) ; comparaison baseline/courant (#669) ; recherche forensic, extraction, comparaison de postes, NetFlow (#675) |
+| API | 50 routes FastAPI | Analyse avec sécurité ; options NAT, TLS, QUIC, anonymisation ; exports texte, PDF, CSV (issue #670) ; options avancées (#672) ; comparaison baseline/courant (#669) ; recherche forensic, extraction, comparaison de postes, NetFlow (#675) |
 
 
 Légende : **oui** = disponible ; **non** = absent ; **auto** = toujours
@@ -118,9 +118,9 @@ est conservée telle quelle pour les clients existants.
 
 | Fonction | GUI | CLI | API |
 |---|---|---|---|
-| Capture sur interfaces, un filtre BPF par point | oui (case « Capture en direct ») | `--live` | non |
-| Durée maximale | oui | `--live-duration` | non |
-| Arrêt manuel puis analyse | oui (« Arreter et analyser ») | Ctrl+C | non |
+| Capture sur interfaces, un filtre BPF par point | oui (case « Capture en direct ») | `--live` | `POST /live-captures` : `points` (`name`, `interface`, `bpf`), `points_order`, `options` (mêmes options d'analyse que `POST /captures/multi`) ; état par `GET /live-captures/{capture_id}`, puis résultat sous `/analyses/{analysis_id}`. Désactivé par défaut (`NETCROSS_API_LIVE=1`), interfaces de `NETCROSS_API_LIVE_INTERFACES` seulement, `NETCROSS_API_TOKEN` exigé (issue #902) |
+| Durée maximale | oui | `--live-duration` | `duration`, bornée par `NETCROSS_API_LIVE_MAX_DURATION` (300 s par défaut ; issue #902) |
+| Arrêt manuel puis analyse | oui (« Arreter et analyser ») | Ctrl+C | `POST /live-captures/{capture_id}/stop` (issue #902) |
 | Rotation de capture (ring buffer) | oui (« Rotation de capture », nombre de fichiers, durée par fichier) : même enregistreur que la CLI, répertoires et fichiers conservés indiqués dans le journal | `--ring-buffer N:SECONDES` : enregistre la capture brute de chaque point en pcapng tournants (ring buffer natif de tshark), incompatible avec `pipe://` (issue #676) | non |
 | Bibliothèque de filtres BPF enregistrés | oui (enregistrer, choisir) | `--bpf-library NOM` (lit `~/.netcross/bpf_filters.json`, issue #676) | `GET /bpf-filters`, `PUT /bpf-filters/{nom}`, `DELETE /bpf-filters/{nom}` (même fichier, `$NETCROSS_API_BPF_FILTERS` côté serveur, issue #906) ; champ `bpf_library` par point avec #902 |
 | Rapport HTML rafraîchi en continu | oui (« Rapport HTML en continu », répertoire, intervalle, « Servir la page » et port ; issue #676) | `--live-report`, `--live-report-interval`, `--live-report-serve` | non |
@@ -301,6 +301,9 @@ l'option CLI de même nom) : `nat_tolerant`, `nat_window_ms`, `tls`,
 | `GET /lua-doc/search` | Recherche dans la documentation Lua, `q`, `limit`, `full` (issue #873) |
 | `GET /comparisons/{comparison_id}/redact-map` | Table d'anonymisation commune baseline/courant (issue #876) |
 | `POST /tools/replay` | Rejeu sur une interface autorisée (issue #871) |
+| `POST /live-captures` | Capture en direct sur des interfaces autorisées puis analyse (issue #902) |
+| `GET /live-captures/{capture_id}` | État d'une capture en direct : octets par point, durée, `analysis_id` (issue #902) |
+| `POST /live-captures/{capture_id}/stop` | Arrêt anticipé d'une capture en direct (issue #902) |
 | `GET /analyses/{analysis_id}/annotations` | Annotations de l'analyse par point, filtres `point`, `tag` (issue #910) |
 | `POST /analyses/{analysis_id}/annotations` | Ajoute ou met à jour une annotation (issue #910) |
 | `DELETE /analyses/{analysis_id}/annotations` | Supprime une annotation, `point`, `frame_number`, `tag` (issue #910) |
@@ -335,7 +338,7 @@ Classés par impact pour un utilisateur :
    batch) relève de l'automatisation et reste en CLI **par choix**.
    Révisé le 11/10/2026 (#330) : plus aucune exemption, toute fonction
    doit exister en CLI, GTK4 et API. Restent : l'API de la capture en
-   direct (#902 à #908) et la CLI et l'API des vues propres à la GUI
+   direct (#903 à #908 ; #902 livrée) et la CLI et l'API des vues propres à la GUI
    (#909 cartographie, #911 dashboard, #912
    exploration statistique).
 

src/netcross_api/app.py

@@ -2829,6 +2829,38 @@ async def get_batch_report(batch_id: str, name: str, _auth: None = Depends(_veri
 
 _lua_doc_routes.register(app, _verify_api_key)
 
+# Issue #902 : capture en direct sur des interfaces du serveur, puis analyse
+import inspect as _inspect  # noqa: E402
+
+from netcross_api import live_routes as _live_routes  # noqa: E402
+
+_LIVE_OPTION_DEFAULTS = {"nat_tolerant": False, "nat_window_ms": 200.0, "tls": False, "quic": False, "redact": False}
+
+
+def _live_make_options(**kwargs: Any) -> ApiAnalysisOptions:
+    """Options d'analyse d'une capture en direct : celles de POST /captures/multi."""
+    return _options(**{**_LIVE_OPTION_DEFAULTS, **kwargs})
+
+
+live_captures = _live_routes.register(
+    app,
+    _verify_api_key,
+    {
+        "token": lambda: _API_TOKEN,
+        "max_files": lambda: _MAX_FILES,
+        "parse_points_order": lambda order, labels: _parse_points_order(order, labels),
+        "option_names": lambda: frozenset(_inspect.signature(_options).parameters) - _live_routes._EXCLUDED_OPTIONS,
+        "make_options": _live_make_options,
+        "create_pending": lambda metadata, options: store.create_pending(
+            {**metadata, "options": _options_metadata(options)}
+        ),
+        "run_job": lambda analysis_id, captures, order, multi, options: _run_job(
+            analysis_id, captures, order, multi, options
+        ),
+        "get_analysis": lambda analysis_id: store.get(analysis_id),
+    },
+)
+
 # Issue #910 : annotations d'une analyse (rangées dans ses métadonnées, par point)
 from netcross_api import annotations_routes as _annotations_routes  # noqa: E402