Référence de l'API

Version de l'API : 1.7.0. Adresse de base : https://<votre-console>/api/v1. Toutes les routes exigent un jeton (Authorization: Bearer …, voir cette page). Les réponses ont la forme { data, meta } ; les dates sont en UTC (ISO 8601).

Cette référence est générée à partir de la spécification OpenAPI du produit. La même spécification est servie par votre console à l'adresse /api/v1/openapi.json.

#Jeton

#GET /me

Identité et portées du jeton

Réponses : 200 OK · 401 Jeton absent, invalide, expiré ou révoqué

#Parc

#GET /machines

Postes équipés de l'agent FirstSI — portée read:machines

Pagination par curseur.

Réponses : 200 Liste paginée · 403 Portée manquante · 429 Trop d'appels

#GET /machines/{hostname}

Un poste

Réponses : 200 OK · 404 Poste inconnu

#Flux réseau

#GET /flows

Flux réseau détaillés — portée read:flows

Un flux = une connexion observée par l'agent : date, processus, utilisateur, pair distant, protocole, sens, octets. Fenêtre limitée à 7 jours (au-delà, la réponse est ramenée aux 7 derniers jours et meta.window_capped vaut true) : au-delà, utilisez /flows/destinations ou /flows/summary, qui lisent des agrégats horaires. Pagination par curseur, du plus récent au plus ancien.

Réponses : 200 Liste paginée · 403 Portée manquante · 429 Trop d'appels

#GET /flows/destinations

Destinations les plus vues — portée read:flows

Avec qui les postes parlent-ils ? Calculé sur les agrégats horaires, donc rapide jusqu'à 31 jours. Trié par volume décroissant. source=gateway : flux vus par les passerelles (IPFIX), appareils sans agent compris ; source=all : les deux, le trafic des postes équipés n'étant compté qu'une fois (champ seen_by).

Réponses : 200 OK · 403 Portée manquante

#GET /flows/summary

Volumes réseau sur la période — portée read:flows

Totaux, répartition par protocole et par sens, et courbe heure par heure (744 points au plus). Agrégats horaires, jusqu'à 31 jours.

Réponses : 200 OK · 403 Portée manquante

#GET /flows/talkers

Postes qui échangent le plus — portée read:flows

Classement des postes par volume total sur la période. Agrégats horaires, jusqu'à 31 jours.

Réponses : 200 OK · 403 Portée manquante

#GET /flows/blocked

Connexions refusées, expirées ou bloquées — portée read:flows

Connexions sortantes en échec vues par les agents (capteur ETW Microsoft-Windows-TCPIP) : refused, timeout, blocked (pare-feu local), host_unreachable, network_unreachable, reset, aborted. Collecte active depuis le 27/09/2026 ; une tentative abandonnée par l'application avant le délai TCP de Windows (~21 s) n'est pas enregistrée.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /flows/explore

Explorateur de flux (volumes par dimensions) — portée read:flows

Croise 1 à 3 dimensions (interne, externe, pays, operateur, port, service, proto, sens, source, passerelle, site, interface, processus, utilisateur) sur les flux des agents et des passerelles, avec filtre textuel (ex. « pays != FR et service = https »). Renvoie la série temporelle empilée par la première dimension, les liens entre dimensions (diagramme de Sankey) et le top N. Pays et opérateur : IP Geolocation by DB-IP (CC BY 4.0).

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#NetDiag

#GET /netdiag/machines

Postes en diagnostic réseau, verdict courant et état d'alerte — portée read:netdiag

Réponses : 200 OK

#GET /netdiag/machines/{hostname}/summary

Résumé d'un poste sur une période

Répartition des verdicts, causes, dernière mesure (lien, Wi-Fi, latences, sondes).

Réponses : 200 OK · 404 Aucune mesure

#GET /netdiag/machines/{hostname}/events

Événements d'un poste

Sources : verdict, appv, alert, app, teams, ap, vpn, wlan, driver, trace, speed, capture, netprofile, switch, dhcp, power, wan, tcpfail, proc, install. Les sources file et fg (données sensibles) ne sont pas exposées.

Réponses : 200 Liste paginée

#GET /netdiag/machines/{hostname}/apps

Applications suivies : verdicts, charge, dépendances réseau, sondes, tendance mémoire

Réponses : 200 OK

#GET /netdiag/machines/{hostname}/report.pdf

Rapport de diagnostic PDF — portée report:pdf

Même rapport que le bouton « Télécharger » du tableau de bord.

Réponses : 200 PDF · 403 Portée report:pdf manquante

#PUT /netdiag/machines/{hostname}/settings

Modifier les réglages NetDiag d'un poste (mise à jour partielle) — portée write:netdiag

Seules les clés envoyées changent. apps : exécutables à suivre (10 max, liste vide = défaut du tenant) ; extraProbes : sondes "hote.domaine[:port]" ou "*.domaine[:port]" (3 max) ; interrupteurs booléens : traceOnIncident, captureOnIncident, autoWatchApps, flowsEnabled, foregroundEnabled, foregroundTitles, fileEventsEnabled, fileIncludeAppData, installEventsEnabled, processEventsEnabled, windowsEventsEnabled. L'agent applique dans la minute.

{
  "apps": [
    "sage.exe",
    "outlook.exe"
  ],
  "autoWatchApps": true
}

Réponses : 200 Réglages enregistrés · 400 Clé inconnue ou valeur invalide (la réponse liste les clés admises) · 404 Poste inconnu

#POST /netdiag/machines/{hostname}/actions

Demander un traceroute, un test de débit ou une capture réseau au poste — portée write:netdiag

action=trace (target facultatif : hôte ou IP, sinon la passerelle), speed (20 Mo descendant / 8 Mo montant vers le serveur FirstSI), capture (seconds 5 à 120, défaut 30 ; fichier pcapng consultable dans FirstSI). Réponse 202 : le résultat arrive dans les événements du poste (source trace | speed | capture) une à trois minutes plus tard si l'agent est en ligne.

{
  "action": "trace",
  "target": "srv-sage.exemple.lan"
}

Réponses : 202 Demande transmise · 400 action invalide · 404 Poste inconnu

#Alertes

#GET /alerts

Flux unifié des alertes : NetDiag, HostMonitor, SIEM — portée read:alerts

status=open renvoie ce qui est en cours maintenant (états NetDiag, incidents HostMonitor non résolus, incidents SIEM ouverts) ; status=all ajoute l'historique de la période (alertes NetDiag envoyées, incidents ouverts dans la fenêtre). Chaque élément porte kind, severity (critical|high|medium|low|info), status (open|resolved), title, target et details propres à la source.

Réponses : 200 OK · 403 Portée manquante

#POST /alerts/{id}/ack

Acquitter un incident HostMonitor ou SIEM — portée write:alerts

id tel que renvoyé par GET /alerts : hm-<n> (HostMonitor : acknowledged, la note va dans les notes de l'incident si elles sont vides) ou siem-<id> (SIEM : statut OPEN → ACKNOWLEDGED, note ajoutée aux actions). Les alertes NetDiag (nd-…) ne s'acquittent pas : elles se résolvent au retour à OK.

{
  "note": "Pris en charge par l'astreinte, ticket #1234"
}

Réponses : 200 Acquitté · 400 Identifiant invalide ou alerte NetDiag · 404 Incident inconnu · 409 Déjà acquitté / plus ouvert

#Disponibilité

#GET /monitors

Moniteurs HostMonitor : état, dernier contrôle, disponibilité 24 h / 7 j / 30 j — portée read:monitors

Réponses : 200 OK

#GET /monitors/{id}

Un moniteur

Réponses : 200 OK · 404 Moniteur inconnu

#GET /monitors/{id}/incidents

Incidents d'un moniteur (période par défaut : 30 jours, incidents en cours toujours inclus)

Réponses : 200 OK · 404 Moniteur inconnu

#Inventaire

#GET /inventory/assets

Actifs inventoriés : matériel, OS, rôles, risque CVE, logiciels en fin de vie — portée read:inventory

Pagination par curseur.

Réponses : 200 Liste paginée

#GET /inventory/assets/{id}

Un actif et ses logiciels installés (500 max)

Réponses : 200 OK · 404 Actif inconnu

#GET /inventory/software

Logiciels installés, tous actifs confondus

Filtres has_cve=1 (au moins une CVE), eol=1 (statut eol : fin de vie atteinte, ou warning : fin de support proche ; unknown exclu).

Réponses : 200 Liste paginée

#GET /inventory/cves

Vulnérabilités détectées (logiciel × CVE) avec description, CVSS, EPSS, exploitation connue

Réponses : 200 Liste paginée

#Assistants IA

#POST /mcp

Serveur MCP (Model Context Protocol) en lecture seule

Transport Streamable HTTP sans état : envoyez les messages JSON-RPC 2.0 (initialize, tools/list, tools/call, ping) en POST avec le même jeton. 58 outils en lecture seule couvrant tous les modules, chacun appelant la route v1 correspondante : portées, quota et journal s'appliquent. tools/list ne montre que les outils couverts par les portées du jeton. Voir la section « Assistants IA » de la documentation pour la configuration de Claude Code et Claude Desktop.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "netdiag_summary",
    "arguments": {
      "hostname": "POSTE-01",
      "period": "24h"
    }
  }
}

Réponses : 200 Réponse JSON-RPC · 202 Notification reçue (sans corps) · 401 Jeton absent ou invalide

#Exploitation

#GET /maintenance

Fenêtres de maintenance — portée read:monitors

Fenêtres ponctuelles et récurrentes, sondes couvertes (covers = all | some | none), active_now. Une liste de sondes vide couvre tout le tenant.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /heartbeats

Heartbeats — portée read:monitors

Traitements planifiés qui doivent se signaler : dernier signal, code de sortie, état.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /profiles

Profils applicatifs — portée read:monitors

Profils (sondes, requêtes de contrôle, fenêtres, paramètres) et leurs déploiements.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /profiles/{id}

Définition d'un profil — portée read:monitors

Document complet firstsi-profile/1, avec la trace de vérification.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /profiles/deployments/{id}/compare

Écarts d'un déploiement de profil — portée read:monitors

Pour chaque élément : conforme, modifie (champ, attendu, réel), absent, non_deploye, indetermine.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#Sécurité

#GET /security/logons

Ouvertures de session Active Directory — portée read:security

Événements 4624 (réussite) et 4625 (échec) : compte, postes source et cible, adresse, type d'ouverture, raison de l'échec. Fenêtre bornée à 7 jours (meta.window_capped). Pagination par curseur.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /security/lockouts

Verrouillages et déverrouillages de comptes — portée read:security

Événements 4740 et 4767 ; fenêtre par défaut 7 jours, 90 au plus.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /security/account-changes

Changements de l'annuaire — portée read:security

Comptes, groupes, ordinateurs, stratégie d'audit, objets d'annuaire (47xx, 5136-5141) : auteur, cible, attribut. Fenêtre par défaut 7 jours, 90 au plus.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /security/risky-accounts

Comptes les plus à risque — portée read:security

Classement issu du graphe des connexions (administrateur, postes atteints, échecs, centralité).

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /security/anomalies

Anomalies de comportement — portée read:security

Écarts au comportement habituel détectés par SI-Tracer.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /security/incidents

Incidents SIEM — portée read:security

status=open pour ceux en cours (OPEN, ACKNOWLEDGED, INVESTIGATING) ; sinon incidents actifs sur la période.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /security/incidents/{id}

Détail d'un incident SIEM — portée read:security

Incident et ses 200 derniers événements corrélés.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /security/rules

Règles de corrélation SIEM — portée read:security

Règles globales du produit et règles propres au tenant.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#Bases de données

#GET /databases/instances

Instances surveillées — portée read:databases

Version, édition, état ; jamais le compte ni le mot de passe enregistrés.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/instances/{id}/metrics

Indicateurs d'une instance — portée read:databases

CPU, mémoire, connexions, latences d'E/S, attentes ; 500 points au plus, fenêtre de 31 jours au plus.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/instances/{id}/slow-queries

Requêtes lentes — portée read:databases

Triées par durée ; sans le plan d'exécution.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/instances/{id}/top-queries

Requêtes les plus coûteuses — portée read:databases

Cumul des instantanés sur la période (7 jours au plus), par CPU, durée ou lectures.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/instances/{id}/sessions

Sessions : qui exécute quoi — portée read:databases

Échantillons de sessions actives (compte, poste, programme, attente, bloqué par, requête).

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/instances/{id}/blocking

Blocages — portée read:databases

Session bloquante, durée, requêtes.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/alerts

Alertes DB Monitor — portée read:databases

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/checks

Requêtes de contrôle — portée read:databases

Requêtes métier en lecture seule et leur dernier résultat.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /databases/checks/{id}/results

Historique d'une requête de contrôle — portée read:databases

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#Pare-feu

#GET /firewall/devices

Pare-feu et passerelles déclarés — portée read:firewall

Équipements dont les journaux syslog et les flux IPFIX sont relayés par un agent du site.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /firewall/events

Journaux des pare-feu — portée read:firewall

Journaux analysés (WatchGuard, UniFi, CEF, LEEF, clé=valeur) : category (auth, vpn, tunnel, ids, deny, allow, admin, system, other), action (success, failure, blocked, allowed, detected, changed, up, down, info), compte, adresses, service. ad_events : événements du contrôleur de domaine rapprochés (même compte, ±15 s), qui ne voient que l'adresse du pare-feu. Fenêtre de 7 jours au plus.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /firewall/traffic

Trafic des passerelles — portée read:firewall

Flux IPFIX / NetFlow v9 agrégés par heure complète : plus gros émetteurs et principales destinations. Fenêtre de 31 jours au plus.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /firewall/threats

Adresses malveillantes contactées — portée read:firewall

Une ligne par appareil interne, adresse externe et jour : source de l'observation (gateway, firewall, agent), indicateur, identification de l'appareil, statut, incident SIEM. Période par défaut : 30 jours.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /firewall/report

Rapport de la période — portée read:firewall

Synthèse, comptes visés (dont comptes réels de l'annuaire), adresses attaquantes, connexions réussies, menaces, trafic bloqué, tunnels, état de la collecte, incidents. Le PDF est disponible dans l'interface.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#DNS

#GET /dns/resolutions

Résolutions DNS des postes — portée read:dns

Fenêtre de 7 jours au plus.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /dns/top-domains

Domaines les plus demandés — portée read:dns

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /dns/threats

Requêtes vers des domaines malveillants — portée read:dns

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /dns/server-queries

Journaux des serveurs DNS — portée read:dns

Si la collecte des serveurs DNS est active.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#Fichiers

#GET /files/events

Accès aux fichiers partagés — portée read:files

Qui a lu, créé, modifié, supprimé ou renommé quoi ; fenêtre de 31 jours au plus ; pagination par curseur.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /files/summary

Synthèse des accès aux fichiers — portée read:files

Volumes par action, utilisateurs et dossiers les plus actifs.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#Infrastructure réseau

#GET /network/sites

Sites — portée read:network

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /network/devices

Équipements réseau — portée read:network

Pagination par curseur.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /network/devices/{id}

Un équipement, ses liens WAN et interfaces — portée read:network

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /network/devices/{id}/metrics

Indicateurs d'un équipement — portée read:network

500 points au plus.

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /network/tunnels

Tunnels VPN inter-sites — portée read:network

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /network/alerts

Alertes réseau — portée read:network

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

#GET /network/ports

Ports ouverts découverts — portée read:network

Réponses : 200 OK · 403 Portée absente du jeton · 404 Élément inconnu dans ce tenant

Source : · Docs FirstSI · mis à jour le 10/10/2026