Hôtes

À quoi ça sert

Un hôte représente une cible à surveiller : un serveur, un site web, une API, un équipement réseau. C'est le point d'ancrage auquel vous rattachez des vérifications. Un hôte regroupe ainsi toutes les sondes d'une même machine ou d'un même service, et centralise leurs résultats (uptime, dernier état, logs, métriques).

Le modèle d'un hôte

Utilisation via le portail

La section Hosts liste tous vos hôtes avec leur état. Vous pouvez :

• Ajouter un hôte : renseigner nom, hostname/IP, type et tags.
• Ouvrir le détail d'un hôte pour consulter :
  • ses graphes et son uptime ping sur 24 h, 7 j ou 30 j ;
  • son dernier résultat par vérification ;
  • ses logs (si la corrélation de logs est disponible pour votre organisation) ;
  • ses métriques SNMP si l'hôte est supervisé par SNMP.
• Éditer ou supprimer un hôte.

Lister et consulter : tous les rôles. Créer, éditer, supprimer : owner et admin.

Utilisation via l'API

Lister les hôtes

GET /api/v2/hosts — paramètre optionnel active=true pour ne renvoyer que les hôtes actifs.

curl -s "https://api.secumon.secuaas.ovh/api/v2/hosts?active=true" \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{
  "count": 1,
  "hosts": [
    {
      "id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f",
      "name": "web-prod-01",
      "hostname": "10.0.0.12",
      "host_type": "server",
      "tags": { "env": "prod", "role": "web" },
      "is_active": true,
      "created_at": "2026-06-23T12:00:00Z",
      "updated_at": "2026-06-23T12:00:00Z"
    }
  ]
}

Créer un hôte

POST /api/v2/hosts — rôle owner ou admin. name et hostname sont requis.

curl -s -X POST https://api.secumon.secuaas.ovh/api/v2/hosts \
  -H "Authorization: Bearer $SECUMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-prod-01",
    "hostname": "10.0.0.12",
    "host_type": "server",
    "tags": { "env": "prod", "role": "web" }
  }'

Réponse : 201 Created avec l'hôte complet (voir Prise en main).

Consulter, modifier, supprimer

# Détail
curl -s https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f \
  -H "Authorization: Bearer $SECUMON_TOKEN"

# Modifier (seuls les champs fournis sont mis à jour)
curl -s -X PUT https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f \
  -H "Authorization: Bearer $SECUMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tags": { "env": "prod", "role": "web", "owner": "team-web" } }'

# Supprimer
curl -s -X DELETE https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f \
  -H "Authorization: Bearer $SECUMON_TOKEN"

La modification est partielle : un champ absent du corps conserve sa valeur actuelle. La suppression renvoie 204 No Content.

Uptime ping

GET /api/v2/hosts/:id/uptime?window=24h|7d|30d renvoie le pourcentage de disponibilité calculé sur les résultats de ping.

curl -s "https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/uptime?window=7d" \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{ "uptime_pct": 99.87, "samples": 10080, "window": "7d" }

Seules les valeurs 24h, 7d et 30d sont acceptées pour window.

Dernier résultat par vérification

GET /api/v2/hosts/:id/latest renvoie, pour chaque vérification de l'hôte, son résultat le plus récent.

curl -s https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/latest \
  -H "Authorization: Bearer $SECUMON_TOKEN"

[
  {
    "check_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "time": "2026-06-23T12:01:30Z",
    "status": 0,
    "latency_ms": 1.5,
    "output": "pong 1.5ms",
    "error_msg": ""
  }
]

Métriques SNMP de l'hôte

GET /api/v2/hosts/:id/snmp-metrics?from=&to= renvoie les séries temporelles des vérifications SNMP de l'hôte (par défaut, les 6 dernières heures). Voir la page SNMP.

Logs de l'hôte

GET /api/v2/hosts/:id/logs?from=&to=&limit= renvoie les entrées de log associées au hostname, lorsque la corrélation de logs est activée pour votre organisation.

curl -s "https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/logs?limit=50" \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{ "enabled": true, "count": 2, "entries": [ /* ... */ ] }

Si la fonctionnalité n'est pas activée, la réponse est {"enabled": false, "entries": []}. La plage de temps maximale est de 24 heures ; limit est plafonné à 5000 (100 par défaut).

Étiquetage assisté par IA

SecuMon peut proposer des tags pour un hôte en analysant son nom, son hostname, son IP, le type de ses vérifications et sa dernière sortie SNMP. Les tags suggérés sont ajoutés sous un préfixe ai: et n'écrasent pas vos tags manuels.

• POST /api/v2/hosts/:id/ai-tag — étiquette un hôte.
• POST /api/v2/hosts/ai-tag — étiquette tous les hôtes (corps optionnel {"active_only": true}, traitement séquentiel, plafonné à 200 hôtes).

Réservé aux rôles owner et admin.

curl -s -X POST https://api.secumon.secuaas.ovh/api/v2/hosts/8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f/ai-tag \
  -H "Authorization: Bearer $SECUMON_TOKEN"

{
  "host": { "id": "8f3b1c2a-2d44-4e1a-9b77-0a1b2c3d4e5f", "name": "web-prod-01", "...": "..." },
  "ai_tags": { "role": "web-server", "os": "linux" },
  "confidence": 0.82,
  "model_used": "souverain",
  "cost_usd": 0.0004,
  "tags": { "env": "prod", "role": "web", "ai:role": "web-server", "ai:os": "linux" }
}

Si l'étiquetage IA n'est pas configuré pour votre instance, l'endpoint répond 503 avec {"error": "ai_unavailable"}.

Cas d'usage

• Inventaire structuré : utilisez tags (env, role, owner, region) pour filtrer et regrouper vos hôtes de façon cohérente.
• Reporting de disponibilité : GET /hosts/:id/uptime?window=30d fournit la donnée d'un rapport SLA mensuel par hôte.
• Mise hors-service temporaire : passez is_active à false pour cesser de planifier les vérifications d'un hôte sans le supprimer.

Astuces

• Préférez is_active: false à la suppression pour conserver l'historique d'un hôte que vous comptez réutiliser.
• Lancez POST /hosts/ai-tag après un import massif pour obtenir une première taxonomie automatique, puis affinez à la main.
• Le host_type est libre : adoptez une convention d'équipe (server, website, router, switch…) pour faciliter le filtrage.