Sites et campagnes d’analyse : API de Nexus

GET /sites/:id/memoire

La mémoire des projets qui portent ce site — celui auquel il appartient, et ceux qui déclarent son adresse.

Requêtekind, q, cursor, limit

RéponseMemoireObjetDto

NoteLa mémoire est rangée par PROJET : `projets` nomme ceux d’où viennent les lignes, sans quoi un site rattaché à plusieurs projets afficherait un mélange qu’on croirait sien.

GET /sites

Les sites du parc que je vois (tous pour un administrateur).

Requêtearchives (1 : les archivés aussi), depuis (date ISO 8601 : site créé, archivé, ou dont une panne a commencé ou s’est refermée depuis), etat (UP, DOWN, OFF, UNKNOWN — l’état de surveillance calculé `monitorStatus` ; plusieurs séparés par des virgules)

RéponseSiteDto[]

NotePour interroger en boucle : `depuis` + `etat=DOWN` rend les seuls sites en panne qui ont bougé. Un site n’a pas de date de modification : changer son libellé ne le fait pas remonter dans `depuis`. Une valeur inconnue est un 400 qui nomme le champ.

POST /sites/:id/archive Owner et Admin

Archive un site, ou le rend à la liste courante. Rien d’autre ne bouge : analyses, sauvegardes, demandes et accès restent — c’est la raison d’archiver plutôt que de supprimer.

Corpsarchived (booléen)

Réponse{ ok: true }

NoteGET /sites écarte les archivés ; `archives=1` les rend à la liste.

POST /sites/:id/projet session de l’application seulement

Le projet du site — créé une seule fois s’il n’existe pas (nom = l’hôte de l’adresse, client, premier dépôt et adresse du site repris, auteur affecté, site rattaché), rendu tel quel ensuite. C’est ce qu’« Intervenir sur un site » ouvre.

Réponse{ project: ProjectDto, cree: boolean }

NoteIdempotent : deux appels rendent le même projet (`cree: false`). 403 « non affecté » si le projet existe et que l’appelant n’est pas de son équipe. Le projet ne porte jamais la machine du site : un projet qui porte une machine est le projet DE la machine. Journal : projet.cree-depuis-site.

GET /sites/:id

La fiche d’UN site. Introuvable s’il sort de mon périmètre.

RéponseSiteDto

POST /sites

Déclare un site.

Corpsurl, label, environment (PRODUCTION, STAGING, LOCAL, OTHER), projectId, clientId, serverId, stack, repoUrls, notes, showOnPortal (faux = le site reste rattaché à son client mais n’est plus proposé dans son portail)

RéponseSiteDto

PATCH /sites/:id

Modifie un site (un site dérivé d’un projet se modifie sur le projet).

Corpsmêmes champs que la création, tous facultatifs

RéponseSiteDto

DELETE /sites/:id

Retire un site saisi à la main.

GET /sites/:id/cookies

Le consentement aux cookies du site (Cookie By Nexus) : la solution déclarée (nulle = Cookie By Nexus par défaut), la balise à poser en tête du <head>, la configuration du bandeau, l’adresse de l’aperçu et les statistiques des choix sur trente jours.

RéponseCookiesSiteDto

NoteLa première lecture pose la ligne du site et tire sa clé publique. Introuvable si le site sort de mon périmètre. Compétence « Cookie By Nexus ».

PUT /sites/:id/cookies

Déclare la solution de consentement du site, ou règle le bandeau de Cookie By Nexus (textes, couleurs, police, position, finalités, services de tracking, Consent Mode v2, CSS personnalisé).

Corpssolution? (nexus, cookieyes, axeptio, didomi, cookiebot, tarteaucitron, onetrust, usercentrics, iubenda, complianz, autre, aucune ; null = rien déclaré), identifiant? (l’identifiant PUBLIC d’une solution tierce), config? (FUSIONNÉE à l’existante : textes, liens, apparence, categories, services, consentMode, dureeJours ≤ 183, domaineCookie, preuves, cssPersonnalise), remplacer? (vrai : remplace la configuration entière), redemander? (vrai : redemande leur choix aux visiteurs)

RéponseCookiesSiteDto

NoteStricte : un champ inconnu, un contraste illisible (moins de 4,5:1), un CSS qui charge une ressource ou une durée de plus de six mois sont refusés (400) en nommant le champ. La version monte d’elle-même quand finalités ou services changent. Il n’existe aucun réglage qui cache « Tout refuser » : un CSS qui le rendrait moins visible que « Tout accepter » est retiré par le script lui-même.

GET /sites/:id/cookies/preuves

Les preuves de consentement du site, les plus récentes d’abord : identifiant de choix, version présentée, geste, finalités accordées, date.

Requêtelimite (1 à 1 000, défaut 100), depuis (date ISO)

Réponse{ preuves, limite, note }

NoteNi adresse IP, ni navigateur, ni page : rien n’y désigne une personne. Effacées après treize mois.

PUT /sites/:id/members Owner et Admin

Remplace les membres à qui le site est confié.

CorpsmemberIds

PUT /sites/:id/clients Owner et Admin

ANCIENNE ROUTE, conservée jusqu’à la 0.11 pour REFUSER en l’expliquant (426) : le partage se fait désormais par personne. N’écrit rien. Sans elle, les applications 0.10.2 recevraient un 404 traduit par « elle marchera au prochain déploiement », ce qui est faux.

CorpsclientIds

Réponse426

PUT /sites/:id/contacts Owner et Admin

Ouvre les accès de ce site à des personnes nommées : chacune les retrouve dans son portail. Réservé aux administrateurs.

CorpscontactIds

Réponse{ ok }

GET /sites/:id/monitoring

Disponibilité d’un site : courbe, pannes, taux, incident en cours.

Requêtefrom, to (ISO 8601) — sans dates, les dernières 24 heures

RéponseSiteMonitoringDto

PATCH /sites/:id/monitoring

Règle la surveillance : activation, chemin sondé, texte attendu, silence de maintenance, examen de sécurité, racine web.

Corpsenabled, path, expectText, mutedUntil, securityEnabled, docRoot

RéponseSiteMonitorDto

Note`docRoot` est la racine web sur la machine, et le seul champ de l’API qui entre dans une commande exécutée sur un serveur : chemin absolu, alphabet fermé (ni espace, ni `$`, ni `;`, ni `..`), refusé sinon.

GET /sites/:id/components

Ce qui est installé sur un site, et les mises à jour constatées.

Réponse{ components, changes }

NoteL’inventaire vient de la MACHINE quand Nexus y a un accès SSH et que la racine du site est renseignée, de la page publique sinon — auquel cas il se limite au socle et à PHP, les versions d’extensions lues dans une page n’étant pas fiables.

POST /sites/:id/components/refresh

Relève l’inventaire d’un site tout de suite.

Réponse{ regarde, source, raison, components, changes }

NoteOuvre une session SSH avec l’accès de la machine quand elle en a un, sans jamais le rendre (l’usage du secret est journalisé), comme « Vérifier maintenant » et l’examen de sécurité. Attend qu’aucun autre relevé du même site ne tourne.

POST /sites/:id/monitoring/refresh

Sonde le site immédiatement, sans attendre le planificateur.

GET /site-threats

Les soupçons d’intrusion de TOUT le parc, les avérés d’abord, en un seul appel.

RéponseParcSecurityDto

NoteRend aussi `examined` et `unexamined` : un tableau de constats vide ne se lit « tout va bien » que si l’on sait combien de sites ont été regardés. À préférer à une requête par site — le plafond de débit refuserait un parc entier. Un constat dont `muteId` n’est pas nul a été déclaré normal sur ce site : il reste listé, et l’alerte seule est tue.

GET /sites/:id/security

Soupçons d’intrusion sur un site : constats ouverts, historique, sources consultées.

RéponseSiteSecurityDto

NoteUn site jamais examiné rend un tableau vide ET `checkedAt` nul : les deux ne veulent pas dire la même chose. `sources` dit ce qui n’a pas été consulté, faute de clé. `mutes` liste ce qui a été déclaré normal sur ce site, celles qui tiennent d’abord ; un constat tu porte `muteId` et reste dans `threats` — on ne masque pas ce qu’on a jugé normal, on le marque.

POST /sites/:id/security/refresh

Examine le site immédiatement : empreinte, redirections, fichiers exposés, DNS, certificat, listes publiques.

NoteUne dizaine de requêtes vers le site examiné. Le geste est journalisé. L’examen fait aussi partir les alertes en attente sans attendre le tour du jour, et relâche les sourdines dont ce qui était constaté a changé — y compris quand rien de neuf n’est ouvert, puisqu’un constat rafraîchi n’est jamais un constat neuf.

GET /sites/:id/mail

Le chemin de courriel d’un site : SPF, DMARC, DKIM, MX, et la file d’attente de sa machine.

RéponseSiteMailDto

NoteNe dit que ce que la ZONE annonce : un `mail()` désactivé par l’hébergeur ne s’y voit pas, et `queueDepth` nul veut dire « non relevé », jamais « file vide ».

POST /sites/:id/mail/refresh

Relit la zone DNS du domaine immédiatement, après une correction.

NoteAucune requête vers le site : uniquement des résolutions DNS.

GET /sites/:id/page

Ce que la page d’accueil DÉCLARE : indexation, titre, canonique, tiers appelés, poids du document, temps de réponse moyen.

RéponseSitePageDto

NoteLecture du DOCUMENT, sans exécuter de JavaScript : le poids est celui du HTML, jamais de la page rendue. « checkedAt » nul veut dire « jamais examinée », et non « rien à signaler ».

POST /sites/:id/page/refresh

Relit la page d’accueil immédiatement, après une correction.

NoteQuatre requêtes publiques : l’accueil, robots.txt, sitemap.xml, et une adresse improbable pour éprouver le 404. Ouvert à tout environnement, à la différence du tour de nuit qui n’examine que la production.

GET /sites/:id/mise-en-ligne

Ce qui n’est pas encore posé sur ce site : nom, certificat, domaine, HTTPS, indexation, courriel, surveillance, sauvegarde, rapport, accès du client.

RéponseMiseEnLigneDto

NoteUne PROJECTION recalculée à chaque lecture : elle n’écrit rien et ne sonde rien. « INCONNU » n’est jamais « à faire » — c’est « aucune sonde n’est passée ».

PATCH /sites/:id/mail

Allume ou éteint l’examen du chemin de courriel de ce site.

Corpsenabled (booléen)

NoteInterrupteur DISTINCT de la disponibilité et de l’examen de sécurité : une vitrine sans formulaire n’a pas à porter un constat rouge.

GET /sites/:id/stack

Ce qui tourne sur le site, avec la version disponible et les constats ouverts.

RéponseSiteStackDto

Note`sources` dit ce qui n’a pas été consulté : un tableau sans avis peut vouloir dire « à jour » ou « personne n’a demandé au répertoire ».

POST /sites/:id/stack/refresh

Relève l’inventaire du site, puis le reconfronte aux sources publiques, après une mise à jour appliquée.

NoteOuvre une session SSH avec l’accès de la machine quand elle en a un (l’usage du secret est journalisé), comme l’examen de sécurité, puis lit la page publique. Un seul relevé à la fois par site, quel que soit le chemin (ce bouton, l’outil d’agent, le tour de nuit) ; un appel qui arrive pendant un relevé attend le SUIVANT, lancé après lui. Au-delà de 20 s, la réponse le dit et le relevé continue sur le serveur. Un avis se referme tout seul : ce geste ne sert qu’à ne pas attendre le lendemain.

GET /site-advisories

Les constats ouverts de TOUT le parc : failles, retraits du répertoire, fins de vie, retards.

Requêteseverity (une gravité), severites (CRITIQUE, HAUTE, MOYENNE, FAIBLE, INFO — plusieurs séparées par des virgules), etat (OUVERT par défaut, RESOLU, ou les deux), depuis (date ISO 8601 : constat détecté ou résolu depuis)

NoteÀ préférer à une requête par site — le plafond de débit refuserait un parc entier. `depuis` ne lit pas `seenAt`, que chaque relevé repose sur tous les constats encore vrais. 300 constats au plus.

GET /deadlines

Ce qui va expirer : certificats, noms de domaine, fins de vie, licences.

Requêtedays (horizon, 1 à 365, défaut 120), includeDismissed, etat (EN_RETARD, A_VENIR, ECARTEE — plusieurs séparés par des virgules ; remplace includeDismissed), depuis (date ISO 8601 : échéance créée, écartée, annoncée — une marche franchie — ou, saisie à la main, modifiée depuis)

RéponseDeadlineDto[]

NoteFiltré par la portée de l’appelant. `source` distingue ce qui est MESURÉ de ce qui est DÉCLARÉ : les deux ne méritent pas la même confiance. `depuis` ne lit pas la date de modification d’une échéance MESURÉE, que chaque relevé réécrit : un renouvellement qui repousse `dueAt` se voit en comparant `dueAt`.

POST /deadlines

Ajoute une échéance déclarée : licence, contrat d’hébergement, renouvellement.

Corpskind, label, dueAt, detail, siteId, serverId

NoteLes certificats, les domaines et les fins de vie sont relevés tout seuls : cette route sert à ce qu’aucune sonde ne peut lire.

GET /deadlines/par-tache/:taskId

Les échéances regroupées dans une tâche — l’onglet « Échéances » de sa fiche.

RéponseDeadlineDto[]

PATCH /deadlines/ecarter

Écarte (ou rétablit) plusieurs échéances d’un geste. Écarter n’efface rien : la ligne reste, la sonde continue de la relire.

CorpsdeadlineIds, dismissed

Réponse{ ecartees }

POST /deadlines/tache

Convertit des échéances en tâche, neuve ou existante. Les échéances restent des échéances : la sonde dira si le renouvellement a eu lieu.

CorpsdeadlineIds, title | taskId, description, assigneeIds, priority, dueAt, projectId

RéponseTaskDto

NoteAffecter quelqu’un l’affecte au projet de la tâche — et au site, ou à la machine, de la demande dont elle vient (jamais les deux : un membre d’une machine voit déjà tous ses sites). Ajout seulement, jamais un retrait ; un affecté déjà en place n’est pas touché. Seul un membre ACTIF de cette entreprise est accepté (400 sinon, et rien n’est écrit). Ce qui a été posé va au journal (« affectation posée par une tâche »).

PATCH /deadlines/:id

Modifie ou écarte une échéance.

Corpslabel, dueAt, detail, dismissed (booléen)

NoteRefuse de réécrire la date d’une échéance MESURÉE : elle serait rétablie au prochain relevé. On peut l’écarter.

DELETE /deadlines/:id

Supprime une échéance déclarée.

NoteUne échéance mesurée ne s’efface pas — elle reviendrait au prochain relevé.

GET /outage-alerts

Les alertes de panne envoyées, avec qui les a prises en charge.

Requêtelimit (1 à 100, défaut 50), sorte (DOWN, UP, FLAPPING — le `kind` de l’alerte), etat (A_PRENDRE, PRISE, ESCALADEE — la prise en charge ; une alerte escaladée et non prise est aussi A_PRENDRE), depuis (date ISO 8601 : alerte envoyée, prise ou escaladée depuis) ; plusieurs valeurs séparées par des virgules

RéponseOutageAlertDto[]

Note`emailSent` et `webhookSent` répondent à « pourquoi je n’ai rien reçu ». Une alerte est un MESSAGE, pas un incident : l’état de la panne se lit sur le site (`GET /sites?etat=DOWN`).

POST /outage-alerts/:id/ack

« Je m’en occupe » : inscrit un nom et une heure sur une alerte, et empêche l’escalade.

NoteLe premier arrivé garde la main : réacquitter n’écrase rien et rend `deja: true`.

GET /sites/:id/restore-checks

Les épreuves d’archive de ce site : ce que Nexus a réussi à RELIRE, et non ce qu’il a cru écrire.

RéponseRestoreCheckDto[]

POST /sites/:id/restore-check

Relit la dernière archive du site chez le destinataire, et la confronte à ce qui avait été noté.

NoteRéservé aux administrateurs : relit des gigaoctets. Une archive chiffrée est éprouvée comme un flux d’octets — la clé privée n’est pas sur le serveur.

POST /site-threats/:id/resolve

Referme un constat d’intrusion, et reprend l’empreinte de référence si le changement était normal.

Corpsnormal (booléen), note

RéponseSiteThreatDto

Note`normal: true` efface l’empreinte : le prochain examen la réécrit à partir de ce que le site sert vraiment.

POST /site-threats/:id/mute session de l’application seulement

Déclare ce constat normal sur ce site : Nexus ne prévient plus tant qu’il ne change pas.

Corpsreason (motif court, facultatif)

RéponseSiteThreatMuteDto

NoteSession seulement : le briefing d’un agent correcteur contient des fragments de la page constatée, donc du texte écrit par l’attaquant — une consigne glissée là ne doit pas pouvoir faire taire le détecteur. La sourdine porte sur la SIGNATURE du constat, jamais sur son identifiant, et elle ne tient que tant que ce qui est constaté ne change pas : Nexus condense les faits du jour et relâche dès qu’ils diffèrent. Elle tait l’ALERTE, pas le constat, qui reste ouvert et visible. Reposer une sourdine relâchée réécrit la même ligne.

POST /site-threat-mutes/:id/release session de l’application seulement

Lève une sourdine : les alertes de ce constat repartent.

RéponseSiteThreatMuteDto

NoteLa ligne reste, datée de sa levée — « la sourdine a sauté » et « rien n’a jamais été tu » ne doivent pas se lire pareil. Les constats ouverts de cette signature sont remis en attente d’alerte.

GET /scan-runs

Les campagnes d’analyse, les plus récentes d’abord.

Requêtelimit (≤ 50, défaut 20)

RéponseScanRunDto[]

GET /scan-runs/:id

Une campagne, site par site : verdicts, constats, résumés.

RéponseScanRunDto

POST /scan-runs

Crée une campagne d’analyse sur des sites ; les agents sont lancés par l’application.

CorpssiteIds, label, threatId, moduleId, scopes, message (facultatifs)

RéponseScanRunDto

Note`threatId` fait partir la campagne d’un constat d’intrusion : le serveur compose lui-même la consigne de l’agent (`brief`) à partir du constat, jamais depuis le corps de la requête. `message` (précisions d’une personne, ≤ 2 000 caractères) est REFUSÉ (403) à une clé d’API et à un agent : ce texte finit dans la consigne d’une session autonome, seule une personne en session l’écrit.

POST /scan-runs/:id/stop

Arrête une campagne : ce qui n’a pas commencé est marqué échoué.

DELETE /scan-runs/:id

Supprime une campagne close, et son rapport avec elle.

Réponse{ ok, supprimees }

NoteRefusé (409) tant que la campagne tourne : ses agents écriraient dans des lignes disparues. Un développeur ne peut supprimer que les siennes. Les constats d’intrusion survivent, leur lien vidé.

POST /site-scans/:id/start application de bureau seulement

L’agent annonce qu’il commence un site.

POST /site-scans/:id/report application de bureau seulement

L’agent rend son compte rendu sur un site.

Corpsseverity (OK, MINOR, MAJOR), summary, filesChanged, detectedStack, findings

POST /site-scans/:id/fail application de bureau seulement

L’agent n’a pas pu conclure sur un site.

Corpserror