ServerSupervisor

Système de supervision d'infrastructure : monitoring de VMs, conteneurs Docker, mises à jour APT, services systemd, tâches planifiées, suivi des releases GitHub, supervision Proxmox VE via API et monitoring synthétique (sondes uptime, certificats SSL, intégration Nginx Proxy Manager).

Guides détaillés

Ce README couvre l'installation et donne une vue d'ensemble de chaque fonctionnalité. Pour une intégration qui demande une vraie procédure de configuration côté service tiers, un guide dédié va plus loin (dépannage inclus) — sur le wiki, généré depuis le dossier wiki/ du dépôt :

Guide	Sujet
Proxmox	Connecter un cluster Proxmox VE (token API, permissions, actions en écriture)
NPM	Connecter Nginx Proxy Manager (sync, monitoring auto par proxy host)
Git-Webhooks-and-Releases	Webhooks Git et suivi de releases GitHub/GitLab/Gitea/Docker
Runbooks-and-Scheduled-Tasks	Runbooks multi-étapes vs tâches planifiées par hôte
Restic-Backups	Sauvegardes Restic (installation, resticprofile, déclenchement)
Alerting	Moteur d'alertes (seuils, hystérésis, incidents, ack/escalade, corrélation, maintenance, modèles)
Monitoring	Sondes uptime HTTP/TCP/ICMP et certificats SSL/TLS
Notifications	Centre de notifications in-app et Web Push (VAPID)
Two-Factor-Authentication	TOTP et clés de sécurité/passkeys (WebAuthn)
Host-Discovery	Scan de sous-réseau et ajout en masse
Custom-Tasks-Examples	Exemples de `tasks.yaml` prêts à copier
Internationalization	Langues de l'interface, choix de la langue, ajout d'une traduction

Vision produit & roadmap

AUDIT-PRODUIT-2026.md — audit produit (état des lieux fonctionnel, positionnement vis-à-vis d'un outil type Checkmk, risques/dettes, questions à trancher).
ROADMAP.md — plan d'exécution détaillé (fonctionnalités priorisées, phases, priorités court/moyen/long terme).
AUDIT-2025.md — audit d'architecture technique (juillet 2026), résolu, conservé pour référence historique.

Architecture

┌────────────────────────────────────────────────────────────────┐
│                       Dashboard (Vue.js)                       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐   │
│  │ Hosts    │ │ Docker   │ │ Network  │ │ APT Console    │   │
│  │ Dashboard│ │ Versions │ │Topology  │ │ Commandes      │   │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐   │
│  │ Alertes  │ │ Audit    │ │ Users    │ │ System         │   │
│  │ (rules)  │ │Commandes │ │ (RBAC)   │ │ Systemd/Proc   │   │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘   │
│  ┌──────────────────────────┐ ┌─────────────────────────┐    │
│  │ Tâches planifiées (cron) │ │ Proxmox VE (nœuds/VMs)  │    │
│  └──────────────────────────┘ └─────────────────────────┘    │
│  ┌──────────────────────────┐ ┌─────────────────────────┐    │
│  │ NPM / Uptime / SSL       │ │ Notifications (Push)    │    │
│  └──────────────────────────┘ └─────────────────────────┘    │
├────────────────────────────────────────────────────────────────┤
│               Server Go (API REST + WebSocket + JWT)           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐   │
│  │ Auth+MFA │ │ Rate     │ │ Alert    │ │ Command        │   │
│  │ JWT+Keys │ │ Limiting │ │ Engine   │ │ Stream Hub     │   │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐   │
│  │ Audit    │ │ GitHub   │ │ Settings │ │ Metrics        │   │
│  │ Logs     │ │ Tracker  │ │ (DB)     │ │ Aggregation    │   │
│  └──────────┘ └──────────┘ └──────────┘ └────────────────┘   │
│  ┌──────────────────────────┐ ┌─────────────────────────┐    │
│  │ Task Scheduler (cron)    │ │ Proxmox Poller (HTTP API)│    │
│  └──────────────────────────┘ └─────────────────────────┘    │
├────────────────────────────────────────────────────────────────┤
│                  TimescaleDB (PostgreSQL 16)                   │
└────────────────────────────────────────────────────────────────┘
         ▲              ▲              ▲              ▲
    Push (30s)     Push (30s)     Push (30s)    Poll API PVE
         │              │              │              │
    ┌────┴────┐    ┌────┴────┐    ┌────┴────┐   ┌────┴──────┐
    │ Agent   │    │ Agent   │    │ Agent   │   │ Proxmox   │
    │ (Go)    │    │ (Go)    │    │ (Go)    │   │ VE API    │
    │ VM-1    │    │ VM-2    │    │ VM-N    │   │(pas agent)│
    └─────────┘    └─────────┘    └─────────┘   └───────────┘

Fonctionnalités

Dashboard

Vue d'ensemble : tous les hôtes avec statut temps réel (CPU, RAM, uptime, version agent)
Détail par hôte : graphiques CPU/RAM historiques (24h / 7j / 30j), disques, conteneurs, APT, historique de commandes toutes sources confondues
Docker : vue globale de tous les conteneurs et projets docker-compose sur toute l'infrastructure
Network : topologie réseau avec liens Docker (réseaux, env vars), override manuel des services
APT : gestion centralisée des mises à jour avec actions groupées et console live streamée
Détail hôte : exécution à distance de commandes systemd (start/stop/restart/enable/disable), logs journalctl streamés, snapshot des processus — directement depuis la page hôte
Streaming commandes : affichage en temps réel de la sortie des commandes longues via WebSocket
Versions : suivi des releases GitHub/GitLab/Gitea et des digests d'images Docker, notification ou déclenchement automatique (script ou compose pull && up -d) — voir Git Webhooks & Suivi de releases
Webhooks Git : endpoint public HMAC-authentifié déclenché par un push/tag/release, exécute une tâche tasks.yaml avec le contexte du commit injecté — voir Git Webhooks & Suivi de releases
Runbooks : séquences admin-only de plusieurs étapes de commandes multi-hôtes, whitelist stricte côté serveur — voir Runbooks & Tâches planifiées
Monitoring : sondes HTTP/TCP/ICMP synthétiques (uptime) — le check ICMP couvre les équipements non-agentables (switch, imprimante, caméra IP…) — et suivi d'expiration des certificats SSL/TLS, historique et stats par sonde sur /monitoring — voir Monitoring
Découverte réseau : scan ping ICMP d'un sous-réseau IPv4 (/24 à /30) sur la page « Ajouter un hôte » — liste les adresses qui répondent, marque celles déjà enregistrées, ajout en masse des nouvelles avec récupération des clés API en un clic — voir Host-Discovery
Audit → Commandes : historique paginé de toutes les commandes (apt/docker/systemd/journal/processus), toutes sources
Audit → Connexions : logs de connexion avec statistiques et IPs bloquées (admin)
Audit → Journal : journal d'audit brut (audit_logs), filtrable par catégorie (alertes/authentification/réglages/commandes) et par date, export CSV ; rétention configurable globalement et par catégorie dans Réglages → Rétention
Tâches planifiées : création de tâches cron par hôte (apt, docker, systemd, journal, processus, restic ou custom), déclenchement manuel immédiat, historique des exécutions — voir Runbooks & Tâches planifiées
Alertes : règles d'alertes configurables avec notifications email (SMTP), ntfy ou notifications navigateur (in-app + Web Push) — un canal notify webhook générique existe aussi mais est déprécié, voir Alerting ; acquittement (« En cours de traitement ») et escalade configurable (relance périodique tant qu'un incident critique reste ouvert et non acquitté) ; corrélation automatique — un hôte hors ligne ne déclenche pas une notification séparée par container Docker/VM Proxmox affecté ; onglet « Vue active » (war-room, onglet par défaut de /alerts) — incidents actifs groupés par sévérité, triés du plus ancien au plus récent ; onglet « Modèles » — définir une règle (métrique agent + seuils + notifications) une fois et l'appliquer à plusieurs hôtes en un clic
Fenêtres de maintenance : suspend les notifications d'un hôte (ou de tous les hôtes) pendant une intervention planifiée, onglet Maintenance de /alerts
Notifications : centre de notifications in-app sur /notifications + push navigateur (Web Push/VAPID), en complément des canaux SMTP/ntfy des alertes — voir Notifications
Compte → Sécurité : gestion MFA/2FA du compte utilisateur sur /account/security (TOTP et/ou clés de sécurité/passkeys WebAuthn) — voir Two-Factor-Authentication
Sécurité (admin) : analytics sécurité hôtes sur /security (connexions, IPs bloquées, corrélation CrowdSec si activée côté agent), stats trafic web sur /traffic, menaces web sur /threats
UI cohérente : barres de recherche/filtres/tri harmonisées sur les vues principales (Docker, APT, Audit)
Proxmox VE : supervision de l'infrastructure de virtualisation via API Proxmox (sans agent sur l'hyperviseur) — nœuds, VMs QEMU, conteneurs LXC, stockage ; polling configurable par connexion
NPM (Nginx Proxy Manager) : connexion à une ou plusieurs instances NPM, tous les proxy hosts existants apparaissent après le premier sync, création automatique des sondes uptime/certificats SSL correspondants, activation du monitoring par host

Proxmox VE (supervision sans agent)

Connexion à un ou plusieurs clusters/nœuds Proxmox via l'API REST officielle (token API, sans rien installer sur l'hyperviseur) : collecte périodique des nœuds, VMs QEMU, conteneurs LXC, stockage, disques physiques (S.M.A.R.T.), tâches récentes et résultats de sauvegarde vzdump — avec liaison optionnelle à un hôte déjà supervisé par agent. Vue globale /proxmox + vue détail /proxmox/nodes/:id (onglets VMs / LXC / Stockage / Disques / Tâches / Sauvegardes / Mises à jour / Services / Journaux sécurité). token_secret stocké en base, jamais renvoyé au frontend.

Console interactive LXC : un shell dans un conteneur directement depuis la fiche guest, relayé en WebSocket vers termproxy sur le nœud PVE — aucun ticket PVE n'atteint jamais le navigateur, aucune session n'est persistée. Admin uniquement, tracé dans les logs d'audit, et limité aux LXC (QEMU demanderait du VNC/RFB, un protocole différent). Demande un compte PVE avec VM.Console en plus du token API : l'API Proxmox n'accepte pas le token sur cet endpoint.

Guide complet (création du token PVE, identifiants console, permissions en écriture, posture admin vs authentifié par action, dépannage) : Proxmox.

NPM (Nginx Proxy Manager)

Connexion à une ou plusieurs instances Nginx Proxy Manager via son API (identité + mot de passe, pas de jeton à portée restreinte) : tous les proxy hosts existants apparaissent automatiquement après le premier sync (pas d'import sélectif), avec création à la demande d'une sonde uptime HTTP et d'un certificat SSL suivi par host, et désactivation en cascade de leur supervision si le host est supprimé/désactivé côté NPM ou si la connexion elle-même est supprimée. Vue /npm : gestion des connexions (admin) + liste des proxy hosts importés.

Guide complet (authentification, cadence de sync réelle, sémantique des interrupteurs de monitoring, dépannage) : NPM.

Git Webhooks & Suivi de releases

Deux façons de réagir à un événement Git : le suivi de releases interroge périodiquement GitHub/GitLab/Gitea ou un registre Docker (modèle pull, notification seule ou déclenchement d'une tâche/compose pull && up -d, avec réconciliation de dérive optionnelle en mode Compose) ; un webhook Git est appelé directement par votre plateforme à chaque push/tag/release (modèle push, endpoint public authentifié par HMAC/token selon le provider). Les deux peuvent déclencher la même tâche custom sur un hôte, avec le contexte du commit injecté en variables d'environnement.

Guide complet (création d'un tracker, configuration du webhook côté plateforme, vérification de signature par provider, dépannage) : Git-Webhooks-and-Releases.

Runbooks & Tâches planifiées

Deux mécanismes de dispatch de commandes agent, à ne pas confondre : un runbook (admin uniquement) enchaîne plusieurs étapes sur plusieurs hôtes en un seul déclenchement manuel, avec une whitelist d'actions strictement revalidée côté serveur ; une tâche planifiée cible un seul hôte sur un cron, avec une liste d'actions seulement indicative (non validée côté serveur au-delà du module) — le déclenchement manuel (run) et la création/modification/suppression sont tous vérifiés Operator+ par hôte (voir le guide).

Guide complet (whitelist par module, tableau comparatif runbook vs tâche planifiée, fuseau horaire d'exécution du cron, dépannage) : Runbooks-and-Scheduled-Tasks.

Agent

Collecte automatique : CPU, RAM, disques, réseau, uptime
Monitoring Docker via CLI (conteneurs, réseaux, projets compose, variables d'environnement)
Détection des mises à jour APT disponibles, extraction des CVEs
Collecte S.M.A.R.T. et métriques disques (via smartctl)
Collecte web logs unifiée (Nginx/Apache/httpd/NPM) : trafic + menaces en un seul parsing
Ingestion incrémentale des logs web via cursor persistant (évite de relire les mêmes lignes à chaque cycle)
Corrélation CrowdSec (optionnelle, désactivée par défaut) : rapproche le trafic web collecté des décisions actives de l'API locale CrowdSec (bans/captcha) — nécessite collect_web_logs: true et une clé bouncer CrowdSec
Exécution de commandes distantes : APT, Docker/Compose, systemd, journalctl, snapshot processus
Tâches custom : exécution de scripts/binaires locaux pré-déclarés dans tasks.yaml (allowlist, sans shell, sans exécution de code arbitraire distant)
Sauvegardes Restic (optionnelle) : supervision passive de l'état Restic local + déclenchement de backup à la demande ou planifié, sans jamais faire remonter les credentials au serveur (voir Sauvegardes Restic)
Streaming temps réel de la sortie des commandes longues (chunk par chunk)
Rapport de résultat des commandes autonomes au démarrage (ex: apt update)
Binaire unique sans dépendances, multi-architecture (amd64/arm64/armv7/armv6)

Interface multilingue

Français et anglais, sélecteur disponible sur la page de connexion et dans le menu utilisateur — voir Internationalisation
Choix mémorisé par navigateur (localStorage), avec repli sur la langue du navigateur puis sur le français
Dates, heures, nombres et tri alphabétique suivent la locale, pas seulement les textes
Erreurs de l'API traduites côté interface via un code d'erreur stable, pour qu'elles suivent la langue choisie et non celle du navigateur

Sécurité

Authentification JWT avec refresh tokens
MFA/2FA optionnel par compte : TOTP et/ou clés de sécurité/passkeys (WebAuthn)
API Keys uniques par agent avec rotation
Vérification stricte de l'appartenance des commandes à chaque hôte
Rate limiting par IP avec cleanup automatique et support reverse proxy
CORS multi-origines configurable
Audit logs de toutes les actions utilisateurs et agent
RBAC 3 niveaux : admin / operator / viewer
Blocage automatique des IPs sur échecs répétés

Captures d'écran



Dashboard — vue d'ensemble de la flotte	Détail hôte — métriques, disques, historique

Docker — conteneurs et projets compose	APT — mises à jour et CVE par hôte

Proxmox VE — nœuds, VMs et LXC	Monitoring — sondes uptime et certificats SSL

Audit — journal des actions, filtrable par catégorie

Ces captures sont générées automatiquement à chaque release contre un jeu de données de démonstration fixe (voir CONTRIBUTING.md pour lancer ce même mode démo en local).

Démarrage rapide

1. Déployer le serveur

git clone https://github.com/Rem7474/ServerSupervisor.git && cd ServerSupervisor
cp .env.example .env
docker compose up -d

Le dashboard est accessible sur http://localhost:8080.
Premier démarrage : Si ADMIN_PASSWORD n'est pas renseigné dans votre fichier .env, un mot de passe aléatoire sécurisé est généré automatiquement au premier lancement. Affichez-le via :
```
docker compose logs server
```
Connectez-vous avec le login admin et le mot de passe généré (ou celui défini dans .env). Une modification du mot de passe vous sera demandée dès la première connexion.

2. Enregistrer un hôte

Dashboard → Ajouter un hôte
Renseigner le nom, hostname/IP, OS — ou onglet Scanner un sous-réseau pour ping-sweeper un CIDR (/24 à /30) et ajouter en masse les adresses qui répondent et ne sont pas encore enregistrées
Copier la clé API affichée (elle ne sera plus visible ensuite)

3. Installer l'agent sur une VM

Installation en une commande (recommandé)

Après avoir enregistré un hôte dans le dashboard, copiez la commande affichée (URL serveur et clé API déjà injectées) :

curl -sSL https://raw.githubusercontent.com/Rem7474/ServerSupervisor/main/agent/install.sh | sudo bash -s -- --server-url http://your-server:8080 --api-key your-api-key

Le script détecte l'architecture (amd64 / arm64 / arm), télécharge le binaire depuis les releases GitHub, génère /etc/serversupervisor/agent.yaml (permissions 0600) et active le service systemd immédiatement.

Options supplémentaires :

--interval <sec>   Intervalle de rapport (défaut: 30)
--no-docker        Désactiver le monitoring Docker
--no-apt           Désactiver le monitoring APT

Prérequis agent (packages système)

L'agent est un binaire Go statique, mais certaines fonctionnalités s'appuient sur des outils système présents sur la VM/LXC.

Fonctionnalité agent	Binaire / package requis	Obligatoire
Exécution de l'agent	`ca-certificates`	Oui
Monitoring Docker (`collect_docker`) + commandes Docker	`docker` / `docker-cli`	Oui si Docker activé
Monitoring APT (`collect_apt`) + actions APT	`apt`, `apt-get`	Oui sur Debian/Ubuntu
SMART disques (`collect_smart`)	`smartctl` (`smartmontools`)	Oui si SMART activé
Température CPU (`collect_cpu_temperature`)	`/sys/class/thermal` ou `/sys/class/hwmon`, fallback `sensors` (`lm-sensors`)	Oui si température CPU activée
Commandes système (services/logs)	`systemctl`, `journalctl` (systemd)	Recommandé
Snapshot processus	`ps` (`procps`)	Recommandé
Sauvegardes Restic (`collect_restic`)	`restic`, éventuellement `resticprofile` — toolkit installé/configuré séparément (non fourni par ServerSupervisor)	Oui si Restic activé

Exemple Debian/Ubuntu:

sudo apt update
sudo apt install -y ca-certificates curl procps

# Optionnels selon les features activées
sudo apt install -y docker.io        # si collect_docker: true
sudo apt install -y smartmontools    # si collect_smart: true
sudo apt install -y lm-sensors       # si collect_cpu_temperature: true

Exemple RHEL/Alma/Rocky:

sudo dnf install -y ca-certificates curl procps-ng

# Optionnels selon les features activées
sudo dnf install -y docker-cli       # si collect_docker: true
sudo dnf install -y smartmontools    # si collect_smart: true
sudo dnf install -y lm_sensors       # si collect_cpu_temperature: true

Notes:

Pour Docker, l'utilisateur du service agent doit avoir accès au socket Docker (groupe docker ou équivalent).
Sur certains environnements virtualisés, la température CPU peut être absente même avec lm-sensors.

Via les releases GitHub (manuel)

# Remplacer ARCH par : amd64, arm64, arm
curl -fsSL https://github.com/Rem7474/ServerSupervisor/releases/latest/download/serversupervisor-agent-linux-ARCH \
  -o /usr/local/bin/serversupervisor-agent
chmod +x /usr/local/bin/serversupervisor-agent

sudo /usr/local/bin/serversupervisor-agent --init \
  --config /etc/serversupervisor/agent.yaml \
  --server-url http://your-server:8080 \
  --api-key your-key

Manuellement

# Compiler l'agent (depuis la machine de dev)
cd agent
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o serversupervisor-agent ./cmd/agent
scp serversupervisor-agent user@vm:/usr/local/bin/

# Sur la VM : générer la config (écrit le fichier en 0600)
sudo /usr/local/bin/serversupervisor-agent --init \
  --config /etc/serversupervisor/agent.yaml \
  --server-url http://your-server:8080 \
  --api-key la-cle-api-copiee

# Si le fichier existe déjà et doit être écrasé
# sudo /usr/local/bin/serversupervisor-agent --init --init-force \
#   --config /etc/serversupervisor/agent.yaml --server-url ... --api-key ...

# Installer le service systemd
sudo tee /etc/systemd/system/serversupervisor-agent.service <<EOF
[Unit]
Description=ServerSupervisor Agent
After=network-online.target docker.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/serversupervisor-agent --config /etc/serversupervisor/agent.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable --now serversupervisor-agent
sudo journalctl -u serversupervisor-agent -f

4. Suivre des repos GitHub

Dashboard → Git / Automatisation → onglet Suivi de releases
Ajouter un repo (ex: home-assistant / core)
Optionnel : associer un nom d'image Docker pour la comparaison automatique
Le serveur vérifie les nouvelles releases toutes les 15 minutes

Pour un webhook déclenché en temps réel par un push (plutôt que ce polling 15 min), ou pour un tracker Docker en mode Compose avec réconciliation de dérive : voir le guide complet Git-Webhooks-and-Releases.

Configuration

Variables d'environnement serveur

Serveur

Variable	Description	Défaut
`SERVER_PORT`	Port d'écoute	`8080`
`BASE_URL`	URL publique (CORS + WebSocket)	`http://localhost:8080`
`TZ`	Fuseau horaire d'interprétation des expressions cron des Tâches planifiées globales et de calcul de leur prochaine exécution — nom IANA/tzdata (ex: `Europe/Paris`). Laissé à `UTC`, une tâche créée pour "23h00" s'exécute réellement à 23h00 UTC, soit 01h00 le lendemain en UTC+2	`UTC`
`TRUSTED_PROXIES`	CIDRs des reverse proxies (ex: `172.18.0.0/16`)	``
`ALLOWED_ORIGINS`	Origins CORS supplémentaires autorisées (virgule)	``
`APP_ENV`	`dev`/`development` assouplit la validation stricte des secrets (JWT auto-généré) ; toute autre valeur = production stricte	`production`
`LOG_LEVEL`	Niveau de log (`debug`/`info`/`warn`/`error`)	`info`
`LOG_FORMAT`	Format de log (`json`/`text`)	`text` en dev, `json` sinon

Base de données

Variable	Description	Défaut
`DB_HOST`	Hôte PostgreSQL	`localhost`
`DB_PORT`	Port PostgreSQL	`5432`
`DB_USER`	Utilisateur	`supervisor`
`DB_PASSWORD`	Mot de passe (à changer !)	`supervisor`
`DB_NAME`	Nom de la base	`serversupervisor`
`DB_SSLMODE`	Mode SSL	`disable`

Authentification

Variable	Description	Défaut
`JWT_SECRET`	Secret JWT (généré automatiquement et persisté en base si omis)	Auto-généré
`JWT_EXPIRATION`	Durée de vie du token JWT	`24h`
`REFRESH_TOKEN_EXPIRATION`	Durée de vie du refresh token	`168h`
`ADMIN_USER`	Nom du compte admin initial	`admin`
`ADMIN_PASSWORD`	Mot de passe admin initial (généré et affiché dans les logs au 1er boot si omis)	Auto-généré

Rate limiting

Variable	Description	Défaut
`RATE_LIMIT_RPS`	Requêtes par seconde max par IP	`100`
`RATE_LIMIT_BURST`	Burst max par IP	`200`
`AGENT_RATE_LIMIT_RPS`	Idem, pour les routes `/api/agent/*` (un agent qui rapporte souvent ne doit pas être limité comme un navigateur)	`20`
`AGENT_RATE_LIMIT_BURST`	Burst max par IP sur `/api/agent/*`	`40`

Le limiteur est en mémoire, par instance — comme le bus d'événements et les hubs WebSocket. C'est cohérent avec le modèle de déploiement actuel (un seul conteneur server), pas un oubli.

GitHub

Variable	Description	Défaut
`GITHUB_TOKEN`	Token GitHub (augmente rate limit 60→5000/h)	``
`GITHUB_POLL_INTERVAL`	Intervalle de vérification	`15m`
`DOCKER_IMAGE_POLL_INTERVAL`	Rafraîchissement du cache de versions d'images Docker (balaye toute la flotte, les registres limitent par IP source)	`6h`

Divers

Variable	Description	Défaut
`DEMO_MODE`	Mode démonstration (jeu de données figé, actions désactivées) — voir CONTRIBUTING.md	`false`
`TLS_ENABLED`	Ne fait pas servir le HTTPS. Force uniquement le flag `Secure` sur les cookies de session — à activer quand l'app est exposée en HTTPS derrière un reverse proxy. Le serveur lui-même n'écoute qu'en HTTP	`false`
`ALLOWED_ORIGINS`	Origines WebSocket/CORS additionnelles (séparées par des virgules)	``
`TRUSTED_PROXIES`	Proxies de confiance pour la résolution d'IP cliente	``
`WEBAUTHN_RP_ID`	Relying Party ID WebAuthn (déduit de `BASE_URL` si absent)	dérivé
`WEBAUTHN_RP_ORIGINS`	Origines WebAuthn autorisées (déduites de `ALLOWED_ORIGINS` si absent)	dérivé

Détection de menaces (scoring)

Le score de menace d'une IP dans les vues Trafic/Menaces est une somme pondérée de signaux, entièrement réglable. Tout est optionnel — les défauts sont calibrés pour un usage courant, ne les touchez que si le scoring est trop bruyant ou trop laxiste sur votre trafic.

Variable	Description	Défaut
`THREAT_THRESHOLD_MEDIUM`	Score à partir duquel une IP est classée « moyenne »	`15`
`THREAT_THRESHOLD_HIGH`	Score « élevée »	`50`
`THREAT_THRESHOLD_CRITICAL`	Score « critique »	`150`
`THREAT_WEIGHT_HITS`	Poids du volume de requêtes	`2`
`THREAT_WEIGHT_BREADTH`	Poids du nombre de chemins distincts sondés	`3`
`THREAT_WEIGHT_STATUS_404`	Poids des 404 (signature d'un balayage)	`2`
`THREAT_WEIGHT_STATUS_4XX`	Poids des autres 4xx	`1.5`
`THREAT_WEIGHT_STATUS_5XX`	Poids des 5xx	`3`
`THREAT_WEIGHT_STATUS_3XX`	Poids des 3xx	`1`
`THREAT_WEIGHT_STATUS_2XX`	Poids des 2xx — volontairement quasi nul : du trafic qui réussit est du trafic normal	`0.1`
`THREAT_WEIGHT_ADMIN_PANEL`	Bonus si des chemins d'administration sont visés	`3`
`THREAT_WEIGHT_WORDPRESS`	Bonus sur les chemins WordPress classiques	`2`
`THREAT_WEIGHT_PATH_TRAVERSAL`	Bonus sur les tentatives de traversée de chemin	`5`
`THREAT_WEIGHT_SUSPICIOUS_METHOD`	Bonus sur les méthodes HTTP inhabituelles	`2`
`THREAT_WEIGHT_KNOWN_SCANNER`	Bonus si le User-Agent est un scanner connu	`4`

Alertes & notifications

Variable	Description	Défaut
`NOTIFY_URL`	URL ntfy/webhook par défaut	``
`SMTP_HOST`	Serveur SMTP	``
`SMTP_PORT`	Port SMTP	`587`
`SMTP_USER`	Utilisateur SMTP	``
`SMTP_PASS`	Mot de passe SMTP	``
`SMTP_FROM`	Email expéditeur	``
`SMTP_TO`	Destinataire par défaut des alertes email	``
`SMTP_TLS`	Activer TLS	`true`
`NTFY_AUTH_TOKEN`	Token d'authentification ntfy (topics protégés)	``

Rétention

Variable	Description	Défaut
`METRICS_RETENTION_DAYS`	Rétention des métriques en jours	`30`
`AUDIT_RETENTION_DAYS`	Rétention des logs d'audit en jours	`90`
`WEB_LOGS_RETENTION_DAYS`	Rétention des requêtes de logs web	`30`
`NETWORK_FLOWS_RETENTION_DAYS`	Rétention des flux réseau	`14`

AUDIT_RETENTION_DAYS peut être affiné par catégorie d'événement, mais uniquement depuis Settings (clé audit_retention_days_by_category) : une map par catégorie n'entre pas dans le format plat CLÉ=valeur d'une variable d'environnement.

Les paramètres de notifications et de rétention sont également éditables depuis le dashboard (Settings) et persistés en base de données.

Sauvegarde & restauration

Le stack Docker Compose inclut un service postgres-backup (image prodrigestivill/postgres-backup-local) qui exécute des pg_dump planifiés, compressés et rotés, de la base ServerSupervisor. C'est une sauvegarde au sens disaster recovery — elle protège contre la perte du volume Docker, une corruption, ou une erreur de manipulation. Ce n'est pas la même chose que METRICS_RETENTION_DAYS / les politiques de rétention TimescaleDB, qui ne font qu'expirer les anciennes métriques dans une base par ailleurs saine.

Variable	Description	Défaut
`BACKUP_SCHEDULE`	Planification (`@daily`, `@weekly`, ou cron 5 champs)	`@daily`
`BACKUP_KEEP_DAYS`	Sauvegardes quotidiennes conservées	`7`
`BACKUP_KEEP_WEEKS`	Sauvegardes hebdomadaires conservées	`4`
`BACKUP_KEEP_MONTHS`	Sauvegardes mensuelles conservées	`6`

Les fichiers .sql.gz sont écrits dans le volume nommé postgres_backups (/backups dans le conteneur postgres-backup).

Restaurer une sauvegarde (arrête l'API pendant la restauration ; adapter le nom de fichier) :

# 1. Arrêter le serveur pour éviter des écritures pendant la restauration
docker compose stop server

# 2. Copier la sauvegarde choisie hors du volume
docker compose cp postgres-backup:/backups/daily/serversupervisor-<horodatage>.sql.gz ./restore.sql.gz
gunzip restore.sql.gz

# 3. Recréer une base vide (la restauration part d'un schéma propre)
docker compose exec postgres psql -U supervisor -d postgres -c "DROP DATABASE serversupervisor;"
docker compose exec postgres psql -U supervisor -d postgres -c "CREATE DATABASE serversupervisor OWNER supervisor;"

# 4. Importer le dump
cat restore.sql | docker compose exec -T postgres psql -U supervisor -d serversupervisor

# 5. Redémarrer le serveur
docker compose start server

Testez cette procédure au moins une fois avant d'en avoir besoin en production — une sauvegarde qui n'a jamais été restaurée n'est pas vérifiée. Les noms de fichiers exacts (sous-dossier daily/weekly/monthly) sont listés par docker compose exec postgres-backup ls -la /backups.

Revenir en arrière après une mise à jour ratée (rollback manuel de migration)

Les migrations SQL (server/internal/database/migrations/) s'appliquent automatiquement au démarrage et sont forward-only — il n'existe pas de mécanisme de "migration down" intégré. Avant de mettre à jour vers une version qui embarque de nouvelles migrations, prenez un instantané ad-hoc et gardez cette procédure à portée de main.

Avant la mise à jour :

docker compose exec postgres pg_dump -Fc -U supervisor serversupervisor -f /tmp/pre-upgrade.dump
docker compose cp postgres:/tmp/pre-upgrade.dump ./pre-upgrade.dump

Si la nouvelle version pose problème :

# 1. Revenir à l'image/tag précédent dans docker-compose.yml, puis arrêter le serveur
docker compose stop server

# 2. Recréer une base vide
docker compose cp ./pre-upgrade.dump postgres:/tmp/pre-upgrade.dump
docker compose exec postgres psql -U supervisor -d postgres -c \
  "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='serversupervisor' AND pid <> pg_backend_pid();"
docker compose exec postgres psql -U supervisor -d postgres -c "DROP DATABASE serversupervisor;"
docker compose exec postgres psql -U supervisor -d postgres -c "CREATE DATABASE serversupervisor OWNER supervisor;"

# 3. Restaurer l'instantané pré-mise à jour
docker compose exec postgres pg_restore -U supervisor -d serversupervisor /tmp/pre-upgrade.dump

# 4. Redémarrer sur l'ancienne image
docker compose up -d server

Cette procédure a été testée de bout en bout (pas seulement rédigée en théorie) : schéma complet migré (baseline + les 71 migrations), une migration destructrice simulée (colonne supprimée, lignes effacées), puis DROP DATABASE / CREATE DATABASE / pg_restore depuis l'instantané — l'état obtenu (schéma, schema_migrations, données) est identique bit à bit à celui du moment de l'instantané. Cette validation a été faite sur un PostgreSQL 16 nu (hors conteneur, sans l'extension TimescaleDB disponible dans cet environnement de test) : le mécanisme pg_dump/ pg_restore lui-même est donc vérifié, mais les commandes docker compose exec ci-dessus n'ont pas pu être rejouées telles quelles faute de démon Docker disponible pendant cette validation. Testez-la une fois sur votre propre stack avant d'en dépendre en production.

Configuration agent (`agent.yaml`)

Cette configuration est identique quel que soit le mode d'installation de l'agent (release GitHub, build manuel, ou script d'installation).

Initialiser une config (écriture fichier) :

serversupervisor-agent --init \
  --config /etc/serversupervisor/agent.yaml \
  --server-url http://your-server:8080 \
  --api-key your-key

Comportement de --init :

Écrit la config sur le chemin passé via --config (défaut: /etc/serversupervisor/agent.yaml)
Refuse d'écraser un fichier existant sauf avec --init-force
Crée automatiquement le dossier parent si nécessaire
Écrit le fichier avec permissions 0600
Mode compatibilité stdout: --config -

Champ	Description	Défaut	Variable d'env
`server_url`	URL du serveur	`http://localhost:8080`	`SUPERVISOR_SERVER_URL`
`api_key`	Clé API de l'hôte (requis)	—	`SUPERVISOR_API_KEY`
`report_interval`	Intervalle d'envoi en secondes	`30`	`SUPERVISOR_REPORT_INTERVAL`
`max_report_body_bytes`	Taille max du payload JSON envoyé (bytes)	`3145728`	`SUPERVISOR_MAX_REPORT_BODY_BYTES`
`collect_docker`	Activer le monitoring Docker	`true`	`SUPERVISOR_COLLECT_DOCKER`
`collect_apt`	Activer le monitoring APT	`true`	`SUPERVISOR_COLLECT_APT`
`collect_smart`	Activer la collecte S.M.A.R.T.	`false`	`SUPERVISOR_COLLECT_SMART`
`collect_cpu_temperature`	Activer la collecte de température CPU	`false`	`SUPERVISOR_COLLECT_CPU_TEMPERATURE`
`collect_web_logs`	Activer l'analyse unifiée des logs web	`false`	`SUPERVISOR_COLLECT_WEB_LOGS`
`web_logs_log_paths`	Liste de paths/globs de logs access à parser	voir exemple	`SUPERVISOR_WEB_LOGS_LOG_PATHS`
`web_logs_tail_lines`	Nombre de lignes lues (par fichier)	`5000`	`SUPERVISOR_WEB_LOGS_TAIL_LINES`
`web_logs_top_n`	Nombre max d'IP/domaines/paths retournés	`10`	`SUPERVISOR_WEB_LOGS_TOP_N`
`web_logs_requests_limit`	Nombre max de requêtes brutes envoyées	`200`	`SUPERVISOR_WEB_LOGS_REQUESTS_LIMIT`
`web_logs_cursor_file`	Fichier de cursor incrémental web logs	`/var/lib/serversupervisor/web_logs_cursor.json`	`SUPERVISOR_WEB_LOGS_CURSOR_FILE`
`apt_auto_update_on_start`	Lancer `apt update` au démarrage de l'agent	`false`	`SUPERVISOR_APT_AUTO_UPDATE_ON_START`
`insecure_skip_verify`	Ignorer les erreurs TLS (certificats auto-signés)	`false`	`SUPERVISOR_INSECURE_SKIP_VERIFY`

Toutes les options sont également configurables via variables d'environnement (préfixe SUPERVISOR_), utile pour les déploiements Docker/Kubernetes.

Compatibilité: les anciennes variables SUPERVISOR_COLLECT_BOT_DETECTION, SUPERVISOR_COLLECT_NPM_ANALYTICS et leurs variantes *_LOG_PATHS, *_TAIL_LINES, *_TOP_N restent supportées comme alias hérités.

Bot detection (logs web)

L'agent peut analyser les access logs web pour identifier des comportements de scan automatisé.

Détection actuelle :

chemins sensibles fréquemment scannés (/.env, wp-admin, phpmyadmin, etc.)
user-agents typiques d'outils de scan (masscan, sqlmap, nikto, etc.)
méthodes HTTP atypiques (TRACE, PROPFIND, ...)

Agrégations remontées :

top_suspicious_ips
top_suspicious_paths
suspicious_requests

Affichage :

onglet Sécurité → Menaces (agrégation globale multi-hôtes)

API :

GET /api/v1/auth/security inclut un champ bot_detection pour les admins.

NPM analytics (logs web)

L'agent peut également agréger les access logs pour remonter des statistiques de trafic web façon "GoAccess".

Payload remonté par hôte :

total_requests
total_bytes
top_domains (avec domain, hits, bytes, errors_4xx, errors_5xx)

Affichage :

page Sécurité (/security) côté admin, section analytics hôtes

API :

GET /api/v1/auth/security inclut aussi un champ npm_analytics (agrégation multi-hôtes pour les admins)

Tâches custom (`tasks.yaml`)

Les tâches custom permettent de définir localement sur l'agent des scripts ou binaires déclenchables depuis le serveur. Le serveur ne peut qu'appeler une tâche par son ID — il n'envoie jamais de code arbitraire.

Chemin par défaut : /etc/serversupervisor/tasks.yaml (override : variable TASKS_CONFIG_PATH)

tasks:
  - id: cleanup_logs
    name: "Nettoyer les vieux logs"
    command: ["find", "/var/log", "-name", "*.log", "-mtime", "+30", "-delete"]
    timeout: 120          # secondes (défaut 60, max 3600)

  - id: backup_db
    name: "Backup PostgreSQL"
    command: ["pg_dump", "-U", "postgres", "mydb", "-f", "/backups/db.sql"]
    timeout: 300

  # Déclenchable via Git Webhook — reçoit les variables SS_BRANCH, SS_COMMIT_SHA, etc.
  - id: git-pull-test
    name: "Git pull /home/root/test"
    command: ["bash", "-c", "cd /home/root/test && git pull origin ${SS_BRANCH:-main}"]
    timeout: 60

  # Alternative : déléguer à un script shell pour plus de contrôle
  - id: deploy-test
    name: "Deploy /home/root/test"
    command: ["/opt/scripts/deploy-test.sh"]
    timeout: 120

Pour l'option script shell, /opt/scripts/deploy-test.sh :

#!/bin/bash
set -e
cd /home/root/test
git pull origin ${SS_BRANCH:-main}
echo "Déploiement terminé (commit: $SS_COMMIT_SHA)"

Variables d'environnement injectées automatiquement par un Git Webhook :

Variable	Contenu
`SS_REPO_NAME`	Nom du dépôt (`owner/repo`)
`SS_BRANCH`	Branche poussée
`SS_COMMIT_SHA`	SHA du dernier commit
`SS_COMMIT_MESSAGE`	Message du commit
`SS_PUSHER`	Auteur du push
`SS_WEBHOOK_NAME`	Nom du webhook ServerSupervisor
`SS_EVENT_TYPE`	Type d'événement (`push`, `tag`, `release`)

Champ	Description
`id`	Identifiant unique (alphanumérique + `-` + `_`, max 64 chars)
`name`	Nom affiché dans le dashboard
`command`	Argv (tableau) — exécuté directement par l'agent, sans passer par un shell
`timeout`	Timeout en secondes (défaut 60, max 3600)

Sur l'argv et le shell. ServerSupervisor n'assemble jamais de ligne de commande : le serveur ne peut désigner qu'un id déjà présent dans le tasks.yaml de l'hôte, et l'agent exécute le tableau tel quel via exec.CommandContext. Il n'y a donc pas d'injection possible depuis le serveur. En revanche, écrire vous-même ["bash", "-c", "…"] (comme dans l'exemple git-pull-test ci-dessus) insère volontairement un shell dans votre propre commande — c'est légitime et parfois nécessaire, mais les variables que vous y interpolez, SS_BRANCH en tête, viennent d'un webhook. Préférez un script dédié dès que la commande devient non triviale.

Déclencher une tâche custom

Trois chemins, tous limités à un id déjà déclaré côté agent :

Depuis	Comment
L'interface	Fiche hôte → onglet Tâches personnalisées → Exécuter. Exécution unique, sans créer de tâche planifiée (`POST /api/v1/hosts/:id/custom-tasks/:taskId/run`, Operator+ sur l'hôte)
Une planification	Créer une tâche planifiée `module=custom`, `target=<id de la tâche>`. Le champ Action est masqué pour ce module : l'agent l'ignore, seul l'identifiant compte
Un webhook Git	Voir Git-Webhooks-and-Releases — les variables `SS_*` ci-dessus sont injectées dans l'environnement du processus

L'onglet Tâches personnalisées affiche ce que l'agent voit réellement : la liste vient de son tasks.yaml, pas de la base. Un fichier absent ou mal formé s'y remarque immédiatement.

Sauvegardes Restic

Supervision optionnelle des sauvegardes Restic/resticprofile sur les hôtes supervisés. Le toolkit Restic (binaire, resticconf, run_backup.sh, resticprofile.yaml) doit déjà être installé et configuré sur la machine — ServerSupervisor ne l'installe pas et ne stocke jamais ses credentials (mot de passe du dépôt, clés Swift/S3/B2, identifiants SMTP) : ils restent dans resticconf sur l'hôte, lu localement par l'agent et jamais transmis au serveur.

Guide complet (installation, resticprofile.yaml, exemples Nextcloud AIO/Immich, dépannage) : Restic-Backups.

Activer la collecte (`agent.yaml`)

collect_restic: true
restic_bin: "/usr/local/bin/restic"
restic_conf_path: "/home/user/restic-backups/resticconf"
restic_run_script_path: "/home/user/restic-backups/run_backup.sh"
restic_status_file_path: "/home/user/restic-backups/backup-status.json"
restic_enable_progress: true
restic_progress_fps: 0.1
restic_backup_idle_timeout_minutes: 20

Seuls des chemins et des indicateurs de fonctionnalité vivent ici — jamais un secret. restic_status_file_path pointe vers le status-file JSON de resticprofile (status-file: ... dans resticprofile.yaml, idéalement avec extended-status: true) : c'est la source privilégiée pour le monitoring passif ; sans ce fichier, l'agent retombe sur restic snapshots --json / restic stats --json.

Monitoring passif vs déclenchement actif

Passif : à chaque rapport périodique, l'agent lit l'état Restic local (status-file ou fallback commandes) et le remonte au serveur — visible dans l'onglet Sauvegardes de la fiche hôte, sans qu'aucun backup n'ait été déclenché par ServerSupervisor.
Actif : le bouton Lancer un backup de cet onglet dispatche une commande agent (module=restic action=run_backup) qui exécute directement run_backup.sh, avec suivi de progression en direct (pourcentage, fichiers/octets traités, ETA) tant que le navigateur reste sur la page.
Planifié : un backup récurrent se programme comme n'importe quelle autre tâche planifiée — page Tâches planifiées, module restic, action run_backup, cible = nom du profil resticprofile (files, db, …, laisser vide pour le profil par défaut du script). Il n'y a pas de webhook ni de cron externe à configurer côté ServerSupervisor.

Limites du suivi en direct

La progression en direct dépend de RESTIC_PROGRESS_FPS et de la sortie --json de restic (forcés automatiquement par l'agent) — un backup lancé en dehors de ServerSupervisor (cron système, ligne de commande) n'est jamais suivi en direct, seul son résultat final apparaît via le monitoring passif au prochain rapport.
Un backup manuel n'a pas de limite de durée fixe : il est coupé uniquement s'il reste silencieux plus de restic_backup_idle_timeout_minutes (pas de plafond absolu, contrairement aux autres commandes agent).
Fermer l'onglet interrompt seulement l'affichage, pas le backup lui-même — revenir sur la page plus tard affiche le résultat final une fois le rapport de statut à jour.

API REST

Authentification

# Login
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# Avec TOTP (si MFA activé)
curl -X POST http://localhost:8080/api/auth/login \
  -d '{"username":"admin","password":"admin","totp_code":"123456"}'

# Utiliser le token
curl http://localhost:8080/api/v1/hosts \
  -H "Authorization: Bearer <token>"

Endpoints (JWT requis sauf indication)

Authentification

Méthode	Endpoint	Description	Rôle
`POST`	`/api/auth/login`	Connexion (JWT + refresh token)	Public
`POST`	`/api/auth/refresh`	Renouveler le token	Public
`POST`	`/api/auth/logout`	Déconnexion	Authentifié
`GET`	`/api/v1/auth/profile`	Profil utilisateur	Authentifié
`POST`	`/api/v1/auth/change-password`	Changer le mot de passe	Authentifié
`GET`	`/api/v1/auth/login-events`	Ses propres connexions	Authentifié
`GET`	`/api/v1/auth/login-events/admin`	Toutes les connexions	Admin
`POST`	`/api/v1/auth/revoke-all-sessions`	Révoquer toutes les sessions	Authentifié
`GET`	`/api/v1/auth/security`	Résumé sécurité + IPs bloquées + agrégats `bot_detection` et `npm_analytics`	Admin
`DELETE`	`/api/v1/auth/blocked-ips/:ip`	Débloquer une IP	Admin
`GET/POST`	`/api/v1/auth/mfa/*`	Gestion MFA/2FA TOTP (setup/verify/disable)	Authentifié
`GET`	`/api/v1/auth/webauthn/credentials`	Liste des clés de sécurité/passkeys	Authentifié
`POST`	`/api/v1/auth/webauthn/register/begin\|finish`	Enregistrer une clé de sécurité/passkey	Authentifié
`DELETE`	`/api/v1/auth/webauthn/credentials/:id`	Supprimer une clé de sécurité/passkey	Authentifié
`POST`	`/api/auth/webauthn/login/begin\|finish`	Connexion via clé de sécurité/passkey (étape MFA)	Public

Hôtes & Métriques

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts`	Liste des hôtes	Authentifié
`POST`	`/api/v1/hosts`	Enregistrer un hôte	Admin
`POST`	`/api/v1/hosts/bulk`	Enregistrer plusieurs hôtes en un appel (ex: après un scan réseau)	Admin
`POST`	`/api/v1/hosts/discover`	Scanner un sous-réseau IPv4 par ping ICMP (`/24` à `/30`)	Admin
`GET`	`/api/v1/hosts/:id`	Détails d'un hôte	Viewer+ (par hôte)
`PATCH`	`/api/v1/hosts/:id`	Modifier un hôte	Operator+ (par hôte)
`DELETE`	`/api/v1/hosts/:id`	Supprimer un hôte	Operator+ (par hôte)
`POST`	`/api/v1/hosts/:id/rotate-key`	Rotation de clé API	Operator+ (par hôte)
`POST`	`/api/v1/hosts/:id/agent/update`	Déclencher la mise à jour de l'agent	Operator+ (par hôte)
`GET`	`/api/v1/hosts/:id/dashboard`	Dashboard rapide d'un hôte	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/complete`	Vue complète agrégée d'un hôte	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/metrics/history`	Métriques brutes (≤24h)	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/metrics/aggregated`	Métriques agrégées (heure/jour)	Viewer+ (par hôte)
`GET`	`/api/v1/metrics/summary`	Résumé global (toutes VMs)	Authentifié
`GET`	`/api/v1/hosts/:id/disk/metrics`	Métriques disques	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/disk/health`	Santé S.M.A.R.T.	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/disk/metrics/history`	Historique brut des métriques disque	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/disk/metrics/aggregated`	Historique agrégé des métriques disque	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/capabilities`	Ce que l'agent de cet hôte sait faire (collecteurs actifs)	Authentifié
`GET`	`/api/v1/hosts/:id/timeline`	Chronologie des événements de l'hôte (onglet Timeline)	Authentifié
`GET`	`/api/v1/hosts/:id/exposure`	Domaines publics NPM routés vers cet hôte + trafic/menaces associés	Viewer+ (par hôte)
`GET`	`/api/v1/dashboard/attention`	Centre d'attention : ce qui nécessite une action, tous domaines confondus	Authentifié

Permissions par hôte (voir RBAC) :

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts/:id/permissions`	Permissions accordées sur cet hôte	Admin
`PUT`	`/api/v1/hosts/:id/permissions/:username`	Accorder/modifier une permission	Admin
`DELETE`	`/api/v1/hosts/:id/permissions/:username`	Retirer une permission	Admin
`GET`	`/api/v1/auth/host-permissions`	Ses propres permissions par hôte	Authentifié

Docker & Network

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts/:id/containers`	Conteneurs d'un hôte	Authentifié
`GET`	`/api/v1/docker/containers`	Tous les conteneurs	Authentifié
`GET`	`/api/v1/docker/compose`	Tous les projets Compose	Authentifié
`POST`	`/api/v1/docker/command`	Envoyer une commande Docker/Compose	Operator+
`GET`	`/api/v1/network`	Snapshot réseau	Authentifié
`GET`	`/api/v1/network/topology`	Topologie réseau	Authentifié
`GET/PUT`	`/api/v1/network/config`	Config topologie (overrides)	Authentifié
`GET`	`/api/v1/hosts/:id/compose-projects`	Projets Compose d'un hôte	Authentifié
`GET`	`/api/v1/network/ip-inventory`	Inventaire IP consolidé (hôtes, guests, conteneurs)	Authentifié
`GET`	`/api/v1/hosts/:id/network/flows`	Flux réseau live d'un hôte	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/network/flows/history`	Historique des flux réseau	Viewer+ (par hôte)
`GET`	`/api/v1/hosts/:id/network/flows/summary`	Top talkers / résumé des flux	Viewer+ (par hôte)

APT

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts/:id/apt`	Statut APT d'un hôte	Authentifié
`GET`	`/api/v1/apt/summary`	Résumé CVE consolidé toute la flotte	Authentifié
`POST`	`/api/v1/apt/command`	Envoyer une commande APT	Operator+
`GET`	`/api/v1/hosts/:id/apt/unattended-upgrades`	État de `unattended-upgrades` sur l'hôte	Authentifié
`PUT`	`/api/v1/hosts/:id/apt/unattended-upgrades`	Configurer `unattended-upgrades`	Operator+
`POST`	`/api/v1/hosts/:id/apt/unattended-upgrades/install`	Installer `unattended-upgrades`	Operator+
`POST`	`/api/v1/hosts/:id/apt/unattended-upgrades/run-now`	Lancer une passe immédiate	Operator+
`GET`	`/api/v1/hosts/:id/apt/unattended-upgrades/runs`	Historique des passes automatiques	Authentifié

Sauvegardes Restic

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts/:id/backup`	Statut agrégé (dernier run + état passif)	Authentifié
`GET`	`/api/v1/hosts/:id/backup/runs`	Historique des backups d'un hôte	Authentifié
`GET`	`/api/v1/hosts/:id/backup/profiles`	Profils resticprofile détectés sur l'hôte	Authentifié
`GET`	`/api/v1/hosts/:id/backup/groups`	Groupes resticprofile détectés sur l'hôte	Authentifié
`GET`	`/api/v1/backup/runs/:runId`	Détail d'un run	Authentifié
`POST`	`/api/v1/hosts/:id/backup/run`	Déclencher un backup manuel	Operator+

Système (systemd / journal / processus)

Méthode	Endpoint	Description	Rôle
`POST`	`/api/v1/system/service`	Commande systemd (start/stop/restart…)	Operator+
`POST`	`/api/v1/system/journalctl`	Logs journalctl d'un service	Operator+
`POST`	`/api/v1/system/processes`	Snapshot des processus	Operator+

Tâches custom (`tasks.yaml`)

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts/:id/custom-tasks`	Tâches déclarées dans le `tasks.yaml` de l'hôte	Authentifié
`POST`	`/api/v1/hosts/:id/custom-tasks/:taskId/run`	Exécuter une tâche une fois, sans créer de tâche planifiée	Operator+
`GET`	`/api/v1/hosts/:id/tasks-yaml`	Contenu brut du `tasks.yaml` tel que vu par l'agent	Authentifié

Commandes & Audit

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts/:id/commands/history`	Historique toutes commandes (hôte)	Authentifié
`GET`	`/api/v1/commands/:id`	Statut d'une commande par UUID	Authentifié
`POST`	`/api/v1/commands/:id/cancel`	Annuler une commande en attente/en cours	Operator+
`GET`	`/api/v1/audit/logs`	Logs d'audit paginés (filtres `category`/`from`/`to`)	Admin
`GET`	`/api/v1/audit/logs/export`	Export CSV des logs d'audit (mêmes filtres, jusqu'à 20 000 lignes)	Admin
`GET`	`/api/v1/audit/logs/me`	Ses propres logs d'audit	Authentifié
`GET`	`/api/v1/audit/logs/host/:host_id`	Logs d'audit par hôte	Admin
`GET`	`/api/v1/audit/logs/user/:username`	Logs d'audit par utilisateur	Admin
`GET`	`/api/v1/audit/commands`	Historique paginé toutes commandes	Operator+

Sécurité & logs web (Trafic / Menaces)

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/security/web-logs`	Résumé agrégé (trafic, top domaines/endpoints/hôtes, menaces, CrowdSec)	Authentifié
`GET`	`/api/v1/security/web-logs/timeseries`	Séries temporelles de trafic	Authentifié
`GET`	`/api/v1/security/web-logs/live`	Tail live des requêtes (rafraîchissement rapide)	Authentifié
`GET`	`/api/v1/security/web-logs/ip/:ip`	Chronologie complète d'une IP	Authentifié
`POST`	`/api/v1/security/web-logs/ip/:ip/decisions`	Bannir une IP via CrowdSec (`host_id` requis)	Admin
`DELETE`	`/api/v1/security/web-logs/ip/:ip/decisions`	Lever un bannissement CrowdSec	Admin
`GET`	`/api/v1/security/web-logs/domain/:domain`	Détail des requêtes pour un domaine	Authentifié

Le scoring de menace est réglable par variables d'environnement (THREAT_WEIGHT_* / THREAT_THRESHOLD_*) — voir Détection de menaces.

Alertes

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/alerts/incidents`	Incidents déclenchés	Authentifié
`POST`	`/api/v1/alerts/incidents/:id/resolve`	Clôturer manuellement un incident	Admin
`POST`	`/api/v1/alerts/incidents/:id/ack`	Accuser réception d'un incident (« En cours de traitement », stoppe l'escalade)	Admin
`GET`	`/api/v1/alert-rules`	Règles d'alertes	Authentifié
`POST`	`/api/v1/alert-rules`	Créer une règle	Admin
`PATCH`	`/api/v1/alert-rules/:id`	Modifier une règle	Admin
`DELETE`	`/api/v1/alert-rules/:id`	Supprimer une règle	Admin
`POST`	`/api/v1/alert-rules/test`	Tester une règle	Admin
`POST`	`/api/v1/alert-rules/test/logs`	Tester une règle de type logs sur un échantillon	Admin
`GET`	`/api/v1/alert-rules/capabilities/agent`	Métriques agent disponibles pour une règle	Admin
`GET`	`/api/v1/alert-rules/capabilities/proxmox`	Métriques Proxmox disponibles	Admin
`GET`	`/api/v1/alert-rules/capabilities/synthetic`	Métriques synthétiques (uptime/SSL) disponibles	Admin
`GET`	`/api/v1/alert-rules/capabilities/docker`	Métriques Docker disponibles	Admin
`GET`	`/api/v1/alert-rule-templates`	Modèles de règles réutilisables	Authentifié
`POST`	`/api/v1/alert-rule-templates`	Créer un modèle	Admin
`PATCH`	`/api/v1/alert-rule-templates/:id`	Modifier un modèle	Admin
`DELETE`	`/api/v1/alert-rule-templates/:id`	Supprimer un modèle	Admin
`POST`	`/api/v1/alert-rule-templates/:id/apply`	Appliquer un modèle à N hôtes (`host_ids`)	Admin

Métriques additionnelles disponibles pour les règles d'alertes :

npm_requests
npm_traffic_bytes
npm_5xx_errors

Guide complet du moteur d'alertes (hystérésis, cooldown, incidents, ack, escalade, corrélation, fenêtres de maintenance, modèles) : Alerting.

Fenêtres de maintenance

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/maintenance-windows`	Liste globale	Authentifié
`GET`	`/api/v1/hosts/:id/maintenance-windows`	Fenêtres applicables à un hôte (les siennes + les globales)	Authentifié
`POST`	`/api/v1/hosts/:id/maintenance-windows`	Créer une fenêtre sur un hôte	Operator+ (vérifié par hôte)
`POST`	`/api/v1/maintenance-windows/global`	Créer une fenêtre sur tous les hôtes	Admin
`DELETE`	`/api/v1/maintenance-windows/:id`	Supprimer une fenêtre	Operator+ sur l'hôte (Admin si globale)

Notifications & Push

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/notifications`	Centre de notifications in-app	Authentifié
`POST`	`/api/v1/notifications/mark-read`	Marquer comme lues	Authentifié
`GET`	`/api/v1/push/vapid-public-key`	Clé publique VAPID	Authentifié
`POST`	`/api/v1/push/subscribe`	Enregistrer un abonnement Web Push	Authentifié
`DELETE`	`/api/v1/push/subscribe`	Supprimer l'abonnement	Authentifié

Monitoring (sondes uptime & certificats SSL)

Une sonde uptime a un type : http, tcp ou icmp (ping). Le check ICMP a besoin d'un socket raw, ce qui nécessite la capacité Linux CAP_NET_RAW — l'image officielle l'accorde au binaire non-root via setcap dans le Dockerfile (CAP_NET_RAW fait déjà partie de l'ensemble de capacités par défaut de Docker, aucun cap_add requis en temps normal). Un déploiement durci avec cap_drop: [ALL] doit ajouter explicitement cap_add: [NET_RAW] ; sans cette capacité, un check ICMP échoue avec un message explicite plutôt que de rapporter un faux « hors ligne ». Le scan de sous-réseau (POST /api/v1/hosts/discover, voir plus haut) réutilise le même mécanisme ICMP et nécessite donc la même capacité.

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/uptime/probes`	Liste des sondes uptime	Authentifié
`GET`	`/api/v1/uptime/probes/:id`	Détail d'une sonde	Authentifié
`GET`	`/api/v1/uptime/probes/:id/history`	Historique des checks	Authentifié
`GET`	`/api/v1/uptime/probes/:id/stats`	Statistiques agrégées	Authentifié
`GET`	`/api/v1/uptime/probes/:id/history/buckets`	Historique agrégé en tranches (barres de disponibilité)	Authentifié
`POST`	`/api/v1/uptime/probes`	Créer une sonde	Admin
`PUT`	`/api/v1/uptime/probes/:id`	Modifier une sonde	Admin
`DELETE`	`/api/v1/uptime/probes/:id`	Supprimer une sonde	Admin
`POST`	`/api/v1/uptime/probes/:id/check-now`	Vérification immédiate	Admin
`GET`	`/api/v1/ssl/certificates`	Liste des certificats suivis	Authentifié
`GET`	`/api/v1/ssl/certificates/:id`	Détail d'un certificat	Authentifié
`GET`	`/api/v1/ssl/certificates/:id/history`	Historique des checks	Authentifié
`POST`	`/api/v1/ssl/certificates`	Ajouter un certificat à suivre	Admin
`PUT`	`/api/v1/ssl/certificates/:id`	Modifier	Admin
`DELETE`	`/api/v1/ssl/certificates/:id`	Supprimer	Admin
`POST`	`/api/v1/ssl/certificates/:id/check-now`	Vérification immédiate	Admin

NPM (Nginx Proxy Manager)

Guide complet : NPM

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/npm/connections`	Liste des connexions NPM (sans secrets)	Authentifié
`GET`	`/api/v1/npm/connections/:id/proxy-hosts`	Proxy hosts importés d'une connexion	Authentifié
`GET`	`/api/v1/npm/proxy-hosts`	Tous les proxy hosts importés	Authentifié
`POST`	`/api/v1/npm/connections`	Créer une connexion	Admin
`PUT`	`/api/v1/npm/connections/:id`	Modifier une connexion	Admin
`DELETE`	`/api/v1/npm/connections/:id`	Supprimer une connexion	Admin
`POST`	`/api/v1/npm/connections/test`	Tester sans sauvegarder	Admin
`POST`	`/api/v1/npm/connections/:id/refresh-now`	Rafraîchir immédiatement	Admin
`PATCH`	`/api/v1/npm/proxy-hosts/:id`	Modifier le monitoring d'un proxy host	Admin
`PATCH`	`/api/v1/npm/proxy-hosts/:id/npm-enabled`	Activer/désactiver le suivi	Admin

Utilisateurs (admin)

Méthode	Endpoint	Description
`GET`	`/api/v1/users`	Liste des utilisateurs
`POST`	`/api/v1/users`	Créer un utilisateur
`PATCH`	`/api/v1/users/:id/role`	Changer le rôle (`admin`/`operator`/`viewer`)
`DELETE`	`/api/v1/users/:id`	Supprimer un utilisateur

Git Webhooks & Suivi de releases

Guide complet : Git-Webhooks-and-Releases

Méthode	Endpoint	Description	Rôle
`GET/POST`	`/api/v1/webhooks/git`	Webhooks Git	Admin
`GET/PUT/DELETE`	`/api/v1/webhooks/git/:id`	Détail / modification / suppression	Admin
`POST`	`/api/v1/webhooks/git/:id/regenerate-secret`	Regénérer le secret HMAC	Admin
`GET`	`/api/v1/webhooks/git/:id/executions`	Historique exécutions	Admin
`POST`	`/api/v1/webhooks/git/:id/receive`	Réception webhook (public, HMAC)	Public
`GET/POST`	`/api/v1/release-trackers`	Suivi releases GitHub/GitLab	Admin
`GET/PUT/DELETE`	`/api/v1/release-trackers/:id`	Détail / modification / suppression	Admin
`POST`	`/api/v1/release-trackers/:id/check-now`	Vérification immédiate	Admin
`POST`	`/api/v1/release-trackers/:id/run`	Déclencher manuellement	Admin
`GET`	`/api/v1/release-trackers/:id/executions`	Historique exécutions	Admin
`GET`	`/api/v1/release-trackers/:id/version-history`	Historique des versions/digests vus, enrichi des notes de release	Admin
`POST`	`/api/v1/release-trackers/bulk`	Créer plusieurs trackers en un appel (validation indépendante par entrée)	Admin
`GET`	`/api/v1/release-trackers/trackable-containers`	Conteneurs Compose éligibles à la mise à jour auto (flux en masse)	Admin
`GET`	`/api/v1/release-trackers/pickable-containers`	Conteneurs sélectionnables pour un tracker docker unitaire	Admin
`GET/POST`	`/api/v1/registry-credentials`	Identifiants de registre privé (GHCR, Docker Hub, registre v2)	Admin
`PUT/DELETE`	`/api/v1/registry-credentials/:id`	Modifier / supprimer des identifiants de registre	Admin

Runbooks

Guide complet : Runbooks-and-Scheduled-Tasks

Méthode	Endpoint	Description	Rôle
`GET/POST`	`/api/v1/runbooks`	Lister / créer un runbook	Admin
`GET/PATCH/DELETE`	`/api/v1/runbooks/:id`	Détail / modification / suppression	Admin
`POST`	`/api/v1/runbooks/:id/run`	Dispatcher la première étape	Admin
`GET`	`/api/v1/runbooks/:id/executions`	Historique des exécutions	Admin
`GET`	`/api/v1/runbooks/:id/executions/:execution_id`	Détail d'une exécution	Admin

Tâches planifiées

Guide complet : Runbooks-and-Scheduled-Tasks

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/hosts/:id/scheduled-tasks`	Lister les tâches d'un hôte	Authentifié
`POST`	`/api/v1/hosts/:id/scheduled-tasks`	Créer une tâche planifiée	Operator+ (vérifié par hôte)
`PUT`	`/api/v1/scheduled-tasks/:id`	Modifier une tâche	Operator+ (vérifié par hôte)
`DELETE`	`/api/v1/scheduled-tasks/:id`	Supprimer une tâche	Operator+ (vérifié par hôte)
`POST`	`/api/v1/scheduled-tasks/:id/run`	Déclencher manuellement	Operator+ (vérifié par hôte)
`GET`	`/api/v1/scheduled-tasks/:id/executions`	Historique d'exécution d'une tâche	Authentifié

Création/modification/suppression sont vérifiées au même niveau que run (requireHostAccess(..., "operator")) — voir Runbooks-and-Scheduled-Tasks pour le détail.

Proxmox VE

Guide complet : Proxmox

Méthode	Endpoint	Description	Rôle
`GET`	`/api/v1/proxmox/summary`	Compteurs globaux (nœuds, VMs, LXC, stockage)	Authentifié
`GET`	`/api/v1/proxmox/nodes`	Tous les nœuds (`?connection_id=` optionnel)	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id`	Détail nœud avec guests + stockages	Authentifié
`GET`	`/api/v1/proxmox/guests`	Tous les guests (`?type=vm\|lxc`, `?status=running`)	Authentifié
`POST`	`/api/v1/proxmox/guests/:id/action`	Démarrer / arrêter / redémarrer une VM ou CT (`{"action":"start\|shutdown\|reboot"}`)	Admin
`GET`	`/api/v1/proxmox/instances`	Liste des connexions (sans secrets)	Authentifié
`POST`	`/api/v1/proxmox/instances`	Créer une connexion	Admin
`GET`	`/api/v1/proxmox/instances/:id`	Détail d'une connexion	Admin
`PUT`	`/api/v1/proxmox/instances/:id`	Modifier une connexion	Admin
`DELETE`	`/api/v1/proxmox/instances/:id`	Supprimer une connexion	Admin
`POST`	`/api/v1/proxmox/instances/test`	Tester sans sauvegarder	Admin
`POST`	`/api/v1/proxmox/instances/:id/test`	Tester une connexion existante	Admin
`POST`	`/api/v1/proxmox/instances/:id/poll-now`	Déclencher un poll immédiat	Admin
`POST`	`/api/v1/proxmox/nodes/:id/apt-refresh`	Déclencher `apt update` sur le nœud (Sys.Modify requis)	Authentifié
`POST`	`/api/v1/proxmox/nodes/:id/guests/:vmid/migrate`	Migrer un guest vers un autre nœud (Sys.Modify requis)	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/services`	Services systemd du nœud	Authentifié
`POST`	`/api/v1/proxmox/nodes/:id/services/:service/:action`	start / stop / restart / reload d'un service de nœud (Sys.Modify requis)	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/status`	Statut temps réel d'un nœud	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/syslog`	Journaux du nœud (onglet Journaux sécurité)	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/rrd`	Séries RRD natives du nœud	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/tasks/:upid/log`	Sortie d'une tâche PVE par UPID	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/guest-networks`	Réseaux des guests du nœud	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/guest-exposure`	Exposition publique des guests du nœud	Authentifié
`GET`	`/api/v1/proxmox/nodes/metrics`	Résumé métriques tous nœuds	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/cpu-temp/history`	Historique température CPU (via source capteurs)	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/fan-rpm/history`	Historique RPM ventilateurs (via source capteurs)	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/sensor-source/candidates`	Hôtes agent éligibles comme source capteurs	Authentifié
`PUT`	`/api/v1/proxmox/nodes/:id/sensor-source`	Désigner la source capteurs d'un nœud	Admin
`GET`	`/api/v1/proxmox/guests/:id/metrics`	Résumé métriques d'un guest	Authentifié
`GET`	`/api/v1/proxmox/guests/:id/link`	Lien guest↔hôte d'un guest	Authentifié
`GET`	`/api/v1/proxmox/guests/:id/exposure`	Domaines publics routés vers ce guest	Authentifié
`GET`	`/api/v1/proxmox/tasks`	Toutes les tâches récentes (`?connection_id=`)	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/tasks`	Tâches d'un nœud	Authentifié
`GET`	`/api/v1/proxmox/nodes/:id/disks`	Disques physiques d'un nœud	Authentifié
`GET`	`/api/v1/proxmox/backup-jobs`	Configurations des jobs de sauvegarde	Authentifié
`GET`	`/api/v1/proxmox/backup-runs`	Derniers résultats de sauvegarde par VM	Authentifié
`GET`	`/api/v1/proxmox/links`	Liens guest↔hôte (`?status=`)	Authentifié
`POST`	`/api/v1/proxmox/links`	Créer/remplacer un lien	Admin
`GET/PUT/DELETE`	`/api/v1/proxmox/links/:id`	Détail / modification / suppression d'un lien	Admin
`GET`	`/api/v1/hosts/:id/proxmox-link`	Lien Proxmox d'un hôte agent	Authentifié
`GET`	`/api/v1/hosts/:id/proxmox-candidates`	Guests candidats à la liaison	Authentifié
`GET`	`/api/v1/hosts/:id/proxmox-disks`	Disques Proxmox du nœud hébergeant cet hôte	Authentifié

La console LXC est un WebSocket, pas une route REST — voir la section WebSocket.

Settings

Méthode	Endpoint	Description	Rôle
`GET/PUT`	`/api/v1/settings`	Paramètres globaux	Admin
`POST`	`/api/v1/settings/test-smtp`	Tester la config SMTP	Admin
`POST`	`/api/v1/settings/test-ntfy`	Tester ntfy	Admin
`POST`	`/api/v1/settings/cleanup-metrics`	Purger les métriques	Admin
`POST`	`/api/v1/settings/cleanup-audit`	Purger les audit logs	Admin

WebSocket (streaming temps réel)

Endpoint	Description
`/api/v1/ws/dashboard`	Flux dashboard global
`/api/v1/ws/hosts/:id`	Flux détail hôte (métriques, conteneurs, APT…)
`/api/v1/ws/docker`	Flux conteneurs Docker
`/api/v1/ws/network`	Flux réseau
`/api/v1/ws/apt`	Flux statut APT
`/api/v1/ws/commands/stream/:id`	Sortie live d'une commande par UUID
`/api/v1/ws/proxmox/console/:guest_id`	Console interactive d'un conteneur LXC (relais bidirectionnel vers `termproxy`) — Admin
`/api/v1/ws/notifications`	Flux notifications (in-app + déclenche le push)

Authentification WebSocket : cookie de session envoyé automatiquement à la connexion, avec repli sur l'envoi de {"type":"auth","token":"<jwt>"} en message une fois la connexion établie (pour les clients qui ne peuvent pas compter sur le cookie). Il n'y a pas de fallback ?token= en query string — retiré volontairement (fuite potentielle dans les logs de proxy/l'historique navigateur).

Agent (API Key requise)

Méthode	Endpoint	Description
`POST`	`/api/agent/report`	Rapport agent (métriques + docker + apt + disques)
`POST`	`/api/agent/command/result`	Résultat d'une commande
`POST`	`/api/agent/command/stream`	Chunk de sortie en streaming
`POST`	`/api/agent/apt-status`	Push du statut APT hors bande (après enrichissement CVE)
`POST`	`/api/agent/restic-status`	Push du statut Restic hors bande (après un `run_backup`)
`POST`	`/api/agent/audit`	Log d'action autonome (ex: apt update au démarrage)
`GET`	`/api/agent/ws`	Optionnel — canal WebSocket ouvert par l'agent pour être réveillé dès qu'une commande est dispatchée, au lieu d'attendre le prochain `report_interval`. Ne transporte aucune commande (juste `{"type":"poll_now"}`) ; un agent sans cette connexion continue de fonctionner par polling normal. Désactivable via `disable_ws_push` dans `agent.yaml`

RBAC

Deux couches se superposent : un rôle global par utilisateur, et des permissions par hôte qui peuvent l'élever localement.

Rôle global

Rôle	Description
`admin`	Accès complet — gestion des utilisateurs, hôtes, alertes, settings, connexions Proxmox/NPM, console LXC
`operator`	Peut exécuter des commandes (apt, docker, systemd) et consulter l'historique
`viewer`	Lecture seule — dashboards, métriques, statuts

Permissions par hôte

Le rôle global ne suffit pas à décrire qui peut agir sur quel hôte. Une table de permissions par hôte (host_permissions, gérée via /api/v1/hosts/:id/permissions, admin uniquement) accorde à un utilisateur un niveau viewer ou operator sur un hôte donné. Le serveur l'applique via HostPermissionMiddleware / requireHostAccess, indépendamment du rôle global :

Les routes de lecture par hôte (GET /hosts/:id/... : métriques, disques, flux réseau, exposition…) exigent viewer sur cet hôte.
Les routes d'écriture par hôte (PATCH/DELETE /hosts/:id, rotation de clé, mise à jour d'agent, tâches planifiées, fenêtres de maintenance, exécution d'une tâche custom) exigent operator sur cet hôte.

C'est pour cette raison que la colonne « Rôle » des tableaux d'endpoints distingue Operator+ (rôle global) de Operator+ (par hôte) : les deux ne se vérifient pas au même endroit, et un operator global n'a pas automatiquement la main sur tous les hôtes.

Deux domaines restent hors de portée de ce découpage, par construction : une cible qui n'est pas un hôte agent (guest Proxmox, conteneur Docker, sonde synthétique) ne peut pas être ramenée à une ligne de hosts, donc seules les fenêtres de maintenance globales la couvrent, et les actions Proxmox suivent leur propre posture (voir Proxmox).

Développement

Prérequis

Go 1.25+ (version exacte dans server/go.mod / agent/go.mod)
Node.js 22+ (utilisé en CI ; le Dockerfile build sur Node 26)
TimescaleDB 2.27.2 (PostgreSQL 16) — prérequis obligatoire (hypertables, time_bucket, retention policies)

Développement local

# Terminal 1 : PostgreSQL
docker compose up postgres

# Terminal 2 : Serveur Go
cd server && go run ./cmd/server

# Terminal 3 : Frontend Vue.js (proxy → serveur Go)
cd frontend && npm install && npm run dev

Build

# Build complet via Docker
docker compose build

# Build agent multi-arch
cd agent && bash build.sh v1.0.0

# Build server + frontend séparément
cd server && go build ./...
cd frontend && npm run build

Structure du projet

ServerSupervisor/
├── server/                          # API Go (Gin) + WebSocket + scheduler + pollers
│   ├── cmd/server/main.go           # Bootstrap : config, migrations, background jobs, HTTP server
│   └── internal/
│       ├── api/                     # router.go (routes/middleware wiring) + middleware.go (JWT/CSRF/rate limit)
│       ├── handlers/                # Traduction HTTP : bind → service → respondError (fichiers par domaine)
│       ├── services/<domaine>/      # Logique métier + port Repository, un package par domaine :
│       │                            #   agent, alertrule, apt, audit, authn, backup, dashboard, discovery,
│       │                            #   docker, dockerversions, gitwebhook, host, hostperm, maintenance,
│       │                            #   network, notifications, notifychannels, npm, proxmox, push,
│       │                            #   releasetracker, runbook, scheduledtask, settings, ssl, uptime,
│       │                            #   user, weblogs
│       ├── database/                # Implémentation des ports Repository (db_*.go) + migrations/*.sql
│       ├── models/                  # Structs partagés, un fichier par domaine (pas de models.go unique)
│       ├── apperr/                  # Erreurs typées → enveloppe HTTP uniforme {"error","code"}
│       ├── events/                  # Bus pub/sub in-process (déclenche les push WebSocket sur écriture)
│       ├── ws/                      # WSHandler, CommandStreamHub, NotificationHub (snapshots event-driven)
│       ├── alerts/                  # Moteur d'évaluation des règles (engine/metrics/authfailures/severity/notify)
│       ├── background/              # Jobs supervisés : audit cleanup, host status, alert eval, rétentions, uptime, SSL
│       ├── safego/                  # Helper recover()+log partagé, utilisé par toute goroutine détachée
│       ├── poller/                  # Boucle générique Every(ctx, interval, ...)
│       ├── scheduler/               # Scheduler cron (tâches planifiées)
│       ├── dispatch/                # Persistance des remote_commands (file de commandes agent)
│       ├── proxmoxclient/           # Client HTTP Proxmox VE
│       ├── npmclient/               # Client HTTP Nginx Proxy Manager
│       ├── gitprovider/             # Client releases GitHub/GitLab/Gitea
│       ├── releasetracker/          # Helpers purs de comparaison de version (pas le tracker lui-même)
│       ├── synthetic/               # Sondes uptime HTTP/TCP + vérification de certificats SSL
│       ├── config/                  # Config env vars + override runtime depuis la table settings
│       ├── notify/                  # Envoi SMTP + ntfy + template HTML d'alerte
│       ├── auth/                    # Génération/vérification TOTP (second facteur)
│       ├── cookies/                 # Fabrication des cookies de session (flag Secure, SameSite)
│       ├── networkview/             # Construction du snapshot réseau / inventaire IP
│       ├── threatdetect/            # Scoring de menace des logs web (pondérations THREAT_*)
│       ├── logging/                 # Setup slog (JSON en prod, texte en dev)
│       ├── errors/                  # Codes d'erreur nommés partagés (ADMIN_REQUIRED, ...)
│       └── testutil/                # Postgres éphémère via testcontainers pour les tests d'intégration
├── agent/                           # Collecteur Go déployé sur chaque VM/hôte supervisé (pas sur Proxmox)
│   ├── cmd/agent/main.go            # Flags, --init, --internal-update, --internal-healthcheck
│   └── internal/
│       ├── reporter/                # Collecte parallèle → POST /api/agent/report
│       ├── dispatcher/              # Exécution des commandes (mutex apt + sémaphore + registry par module)
│       ├── collector/               # Un fichier par domaine : system, docker, apt, disk, web_logs, systemd,
│       │                            #   journal, processes, crowdsec, restic, network_flows (+ L7),
│       │                            #   compose_update, container_ips, diagnostics
│       ├── sender/                  # Structs Report/PendingCommand/CommandResult + client HTTP
│       ├── agentws/                 # Canal WebSocket optionnel vers /api/agent/ws (push "poll_now")
│       ├── security/                # Liste unique des motifs "valeur sensible" (filtrage env + redaction YAML)
│       ├── logging/                 # Setup slog (texte pour journald par défaut)
│       └── config/                  # Config YAML + env vars ; tasks.go charge tasks.yaml
├── frontend/                        # SPA Vue 3 + TypeScript (Tabler CSS)
│   └── src/
│       ├── api/                     # client.ts (axios + intercepteurs CSRF/401) + modules par domaine
│       ├── router/                  # Routes lazy-loaded + retry sur ChunkLoadError
│       ├── stores/                  # Pinia : auth, hosts, dashboard, alertRules
│       ├── composables/             # useWebSocket, useDashboard, useHostDetail, use<Domaine> par vue
│       ├── components/              # Organisés par domaine (proxmox/, npm/, security/, settings/, ...)
│       ├── views/                   # Une vue par route
│       └── types/                   # generated.ts (généré par tygo depuis les modèles Go) + types par domaine
├── protocol/                        # Fixture golden du contrat agent↔serveur + README
├── .github/workflows/               # ci-{server,agent,frontend}.yml, release.yml, security.yml, pr-checks.yml, stale.yml
├── docker-compose.yml                # postgres (TimescaleDB) + server + postgres-backup
├── .env.example
└── README.md

Licence

GNU AGPLv3

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
agent		agent
docs		docs
frontend		frontend
protocol		protocol
screenshot		screenshot
server		server
wiki		wiki
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.nancy-ignore		.nancy-ignore
.trivyignore		.trivyignore
AUDIT-2025.md		AUDIT-2025.md
AUDIT-PRODUIT-2026.md		AUDIT-PRODUIT-2026.md
AUDIT-SONARQUBE-2026.md		AUDIT-SONARQUBE-2026.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
docker-compose.demo.yml		docker-compose.demo.yml
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
sonar-project.properties		sonar-project.properties

Latest commit

History

Folders and files

Repository files navigation

ServerSupervisor

Guides détaillés

Vision produit & roadmap

Architecture

Fonctionnalités

Dashboard

Proxmox VE (supervision sans agent)

NPM (Nginx Proxy Manager)

Git Webhooks & Suivi de releases

Runbooks & Tâches planifiées

Agent

Interface multilingue

Sécurité

Captures d'écran

Démarrage rapide

1. Déployer le serveur

2. Enregistrer un hôte

3. Installer l'agent sur une VM

Installation en une commande (recommandé)

Prérequis agent (packages système)

Via les releases GitHub (manuel)

Manuellement

4. Suivre des repos GitHub

Configuration

Variables d'environnement serveur

Serveur

Base de données

Authentification

Rate limiting

GitHub

Divers

Détection de menaces (scoring)

Alertes & notifications

Rétention

Sauvegarde & restauration

Revenir en arrière après une mise à jour ratée (rollback manuel de migration)

Configuration agent (agent.yaml)

Bot detection (logs web)

NPM analytics (logs web)

Tâches custom (tasks.yaml)

Déclencher une tâche custom

Sauvegardes Restic

Activer la collecte (agent.yaml)

Monitoring passif vs déclenchement actif

Limites du suivi en direct

API REST

Authentification

Endpoints (JWT requis sauf indication)

Authentification

Hôtes & Métriques

Docker & Network

APT

Sauvegardes Restic

Système (systemd / journal / processus)

Tâches custom (tasks.yaml)

Commandes & Audit

Sécurité & logs web (Trafic / Menaces)

Alertes

Fenêtres de maintenance

Notifications & Push

Monitoring (sondes uptime & certificats SSL)

NPM (Nginx Proxy Manager)

Utilisateurs (admin)

Git Webhooks & Suivi de releases

Runbooks

Tâches planifiées

Proxmox VE

Settings

WebSocket (streaming temps réel)

Agent (API Key requise)

RBAC

Rôle global

Permissions par hôte

Développement

Prérequis

Développement local

Configuration agent (`agent.yaml`)

Tâches custom (`tasks.yaml`)

Activer la collecte (`agent.yaml`)

Tâches custom (`tasks.yaml`)