API machine

L’API machine sert à un SIEM, un SOAR ou un script. Elle ne s’utilise jamais avec une session d’utilisateur : chaque appel porte un identifiant d’accès machine, et chaque appel est limité au client de cet accès.

Créer un accès machine

Dans Paramètres > API & Webhooks, le super administrateur crée un accès machine. Il reçoit :

• un identifiant client (avc_…) ;
• un secret (avs_…), affiché une seule fois et conservé seulement sous forme d’empreinte ;
• l’adresse de l’API ;
• les portées accordées. Rien n’est accordé par défaut.

En option, l’accès peut être limité à des réseaux d’origine, et recevoir une date d’expiration. Le secret se renouvelle à tout moment. La création et le renouvellement demandent une connexion de moins de 10 minutes.

S’authentifier

Deux en-têtes :

curl -sS https://aarview.example.org/api/v1/ext/whoami \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..."

L’authentification HTTP Basic (identifiant:secret) est aussi acceptée. La réponse de whoami donne le client de l’accès, son nom et ses portées.

Un accès inconnu, expiré, désactivé ou utilisé depuis un réseau non autorisé reçoit la même réponse 401, sans distinction.

Portées

Portée	Autorise
ingest:alerts	déposer des alertes
incidents:read	lire les incidents
incidents:comment	ajouter une note à un incident
stats:read	lire les statistiques
archive:read	archiver ses évènements et alertes (outil d’archive sur site)

Points d’accès

Base : https://<votre domaine>/api/v1/ext

Méthode et chemin	Portée	Rôle
GET /whoami	aucune	qui est l’accès, ses portées
POST /alerts	ingest:alerts	déposer des alertes
GET /incidents	incidents:read	lister les incidents
GET /incidents/{id}	incidents:read	lire un incident
POST /incidents/{id}/notes	incidents:comment	ajouter une note
GET /stats	stats:read	statistiques du client
GET /archive	archive:read	une fenêtre d’évènements ou d’alertes, pour l’archive sur site

Lister les incidents

Paramètres : page, per_page (200 au plus), status (open, in_progress, resolved, closed), severity (critical, high, medium, low), kind (case ou alert), since (date ISO 8601), rule_id.

curl -sS "https://aarview.example.org/api/v1/ext/incidents?status=open&severity=critical" \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..."

Ajouter une note

visibility vaut internal (reste à votre équipe, par défaut) ou client (visible du client). Le texte compte 5 000 caractères au plus.

curl -sS https://aarview.example.org/api/v1/ext/incidents/<id>/notes \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..." \
  -H "Content-Type: application/json" \
  -d '{"body": "Poste réimagé par l'\''équipe système.", "visibility": "internal"}'

Statistiques

GET /stats?days=30 : les chiffres de la vue Statistiques pour le client de l’accès, sur 1 à 365 jours.

Déposer des alertes

POST /api/v1/ext/alerts accepte une liste d’alertes, 100 au plus par appel.

Champ	Obligatoire	Contenu
title	oui	512 caractères au plus
source	oui	le nom de votre outil, 64 caractères au plus
source_ref	non	votre identifiant de l’alerte ; il sert à reconnaître un doublon
severity	non	de 1 (faible) à 4 (critique)
source_level	non	niveau de l’outil source, de 0 à 15, converti par AarView à la place de severity
description	non	20 000 caractères au plus
alert_type	non	votre catégorie
tags	non	liste d’étiquettes
observables	non	liste de {"data_type": "ip", "data": "203.0.113.7"}
observed_at	non	date ISO 8601 de l’observation
tlp	non	de 0 à 3, 2 par défaut
raw	non	l’évènement d’origine

curl -sS https://aarview.example.org/api/v1/ext/alerts \
  -H "X-AarView-Client-Id: avc_..." \
  -H "X-AarView-Client-Secret: avs_..." \
  -H "Content-Type: application/json" \
  -d '[{"title": "Connexion SSH depuis une adresse inconnue", "source": "mon-outil",
        "source_ref": "evt-2041", "severity": 3,
        "observables": [{"data_type": "ip", "data": "203.0.113.7"}]}]'

La réponse donne le nombre d’alertes reçues, créées et reconnues comme doublons, et les identifiants créés. Le client n’est jamais lu dans le corps : il vient de l’accès. Un nouvel envoi de la même alerte (même source, même référence) ne crée pas de second incident.

Format générique

Pour un outil qui ne sait envoyer que son propre JSON, créez plutôt une source connectée au format générique. AarView y lit :

Donnée	Champs lus, dans l’ordre
titre	title, name, rule, rule_name, alert
sévérité	severity, level, priority : un mot (low, medium, high, critical…), un nombre de 1 à 4, ou une note sur 10 ou sur 100
référence	id, ref, alert_id, uuid
description	description, message, details
date	timestamp, time, @timestamp
observables	observables (type et value, ou data_type et data), et les valeurs trouvées dans fields ou event
étiquettes	tags

Une alerte sans titre est rejetée ; une sévérité absente ou inconnue devient « moyen ».