API isMalicious : réussir son premier lookup d'IOC fiable

Une commande curl réussie prouve qu'un serveur a répondu une fois. Une intégration IOC fiable démontre davantage : elle appelle le bon hôte, protège l'identifiant, refuse une entrée mal formée, distingue un verdict d'une panne et conserve assez de preuves pour enquêter ensuite.

Le lookup canonique actuel est GET https://api.ismalicious.com/check?query=<indicateur>. Le paramètre query accepte une adresse IP, un domaine, une URL ou un hash de fichier hexadécimal, avec un enrichissement basic, standard ou full. Ce guide part de standard, puis ajoute les contrôles nécessaires pour passer d'un test en terminal à un service, une règle SIEM ou un playbook SOAR.

Gardez la documentation interactive de l'API ouverte pendant l'implémentation. Elle constitue la référence pour l'hôte actuel, les paramètres, les exemples de réponse et les endpoints voisins.

Partir du contrat canonique

Utilisez https://api.ismalicious.com pour les clients serveur à serveur. L'application web principale expose aussi des routes de tableau de bord et de session, mais un nouveau client IOC ne doit pas dépendre d'une session navigateur ni changer silencieusement d'hôte. Fixez l'URL de base dans la configuration et n'autorisez que HTTPS.

Envoyez une seule cible normalisée dans query. Avant l'appel, retirez les espaces, refusez une valeur vide, limitez sa longueur et classez-la comme IP, domaine, URL ou hash. Cette validation côté client compte, car une cible absente peut tout de même produire une petite réponse réussie. Un 200 de transport ne prouve donc pas qu'un enrichissement a eu lieu.

Commencez avec enrichment=standard. Considérez la réponse comme une entrée non fiable : validez la forme du JSON, limitez ce que vous stockez et ne suivez jamais automatiquement une URL présente dans le contexte retourné. Les recommandations OWASP sur la consommation non sécurisée d'API demandent notamment TLS, des timeouts, la validation des réponses et un contrôle des redirections lors de l'intégration d'une API tierce.

Pour inspecter la requête sans écrire de code, utilisez le playground API. Il permet de séparer les problèmes d'identifiant ou de paramètre des défauts propres à votre client.

Construire et protéger l'identifiant

Créez la paire dans les paramètres du compte. L'authentification de cet endpoint utilise une représentation Base64 de apiKey:apiSecret dans l'en-tête X-API-KEY. Base64 est un encodage, pas un chiffrement : la valeur encodée reste donc un secret.

Stockez la clé et le secret dans un gestionnaire de secrets ou des variables d'environnement protégées. Construisez l'en-tête en mémoire au démarrage, ne le commitez jamais, ne le placez pas dans une URL et ne l'affichez pas pendant le débogage. Utilisez des identifiants distincts pour le développement, la préproduction et la production afin qu'une fuite ne traverse pas les environnements.

Pour un test shell contrôlé :

credential="$(printf '%s' "$ISMALICIOUS_API_KEY:$ISMALICIOUS_API_SECRET" | base64)"

curl --fail-with-body --silent --show-error \
  --get 'https://api.ismalicious.com/check' \
  --data-urlencode 'query=example.com' \
  --data-urlencode 'enrichment=standard' \
  --header "X-API-KEY: $credential"

N'exécutez ce test que dans un shell où ces variables ont déjà été injectées de manière sûre. Nettoyez la sortie avant de partager une capture du terminal. Un 401 doit arrêter le client et signaler un problème d'authentification, pas provoquer des répétitions avec le même identifiant.

Effectuer un appel contrôlé dans le code

Le premier appel applicatif exige un timeout explicite et une gestion des statuts. Cet exemple Python laisse la politique hors de la couche transport :

import base64
import os
import requests

pair = f"{os.environ['ISMALICIOUS_API_KEY']}:{os.environ['ISMALICIOUS_API_SECRET']}"
credential = base64.b64encode(pair.encode()).decode()

response = requests.get(
    "https://api.ismalicious.com/check",
    params={"query": "example.com", "enrichment": "standard"},
    headers={"X-API-KEY": credential, "Accept": "application/json"},
    timeout=(3, 15),
    allow_redirects=False,
)

if response.status_code == 401:
    raise RuntimeError("Identifiant isMalicious refusé")
if response.status_code == 429:
    raise RuntimeError("Appel isMalicious limité")
response.raise_for_status()

payload = response.json()
if "malicious" not in payload or "apiVersion" not in payload:
    raise RuntimeError("Réponse IOC incomplète")

Ne supposez pas que tous les champs d'enrichissement sont toujours présents. Les fournisseurs optionnels peuvent échouer séparément et les types d'indicateurs renvoient naturellement des contextes différents. Lisez défensivement riskScore, evidence et dataTrust. Le guide sur l'enrichissement d'IOC explique comment relier ce contexte aux décisions des analystes sans copier toute la réponse dans chaque alerte.

Transformer chaque échec en résultat explicite

Définissez un petit modèle de résultat pour votre application : enriched, rejected, rate_limited, temporarily_unavailable et invalid_response. Gardez ces états séparés de malicious, suspicious ou safe. Si le fournisseur est indisponible, l'indicateur est inconnu, pas bénin.

Ne répétez que les échecs transitoires, en général les erreurs réseau, 429 et certaines réponses 5xx. Utilisez un backoff exponentiel avec jitter, un nombre maximal d'essais et l'en-tête Retry-After lorsqu'il est présent. Ne répétez pas un refus d'authentification ou une entrée locale invalide. Placez un circuit breaker autour des défaillances prolongées afin qu'une dépendance d'enrichissement saturée ne bloque pas toute la file d'alertes.

Mettez en cache les recherches répétées pendant une durée bornée, selon l'indicateur normalisé et le niveau d'enrichissement. Le cache doit réduire les doublons, pas masquer l'ancienneté. Conservez l'horodatage d'enrichissement et exigez un nouvel appel pour les décisions sensibles. Pour des ensembles préparés plus importants, utilisez la fonction de vérification en masse plutôt que de lancer une rafale incontrôlée de requêtes unitaires.

Journaliser les preuves sans exposer les secrets

Créez votre propre identifiant de corrélation avant l'appel, puis transmettez-le au ticket ou au job. Journalisez le nom de l'endpoint, le type d'indicateur, la classe de statut, la durée, le numéro de tentative, la version d'API et le résultat de la validation des champs requis. N'enregistrez l'indicateur normalisé que si votre politique de données le permet : hash, domaines et URL peuvent eux aussi révéler une enquête sensible.

Ne journalisez jamais la clé API, le secret, l'identifiant encodé, les en-têtes complets ou le corps intégral de la réponse. Conservez plutôt une décision sélectionnée : verdict, score lorsqu'il existe, fraîcheur, action recommandée, horodatage du fournisseur et hash du payload brut si une preuve d'intégrité est nécessaire. L'équipe de réponse dispose ainsi d'une piste d'audit utile, sans diffusion excessive des données.

Les mesures pertinentes comprennent le taux de succès, les timeouts, les échecs d'authentification, les appels limités, les percentiles de latence, les réponses invalides, les hits du cache et les décisions envoyées en revue manuelle. Elles décrivent la santé de l'intégration. Elles ne prouvent pas que chaque verdict malveillant a empêché un incident.

Passer du test au workflow de production

Placez le client derrière une fonction interne étroite, par exemple enrich_indicator(target). Normalisez avant cette frontière, validez la réponse à l'intérieur et appliquez la politique métier après. Cette séparation permet à une intégration SIEM de joindre du contexte aux alertes tandis qu'un service antifraude ou un workflow de pare-feu applique un seuil différent.

Déployez en trois étapes :

1. Rejouez un ensemble étiqueté de cas bénins, suspects, mal formés et indisponibles.
2. Passez en mode shadow, où les résultats sont enregistrés et joints sans modifier l'exécution.
3. Activez une seule action réversible, par exemple augmenter la priorité d'un ticket, avant tout blocage automatique.

Comparez la décision shadow au résultat des analystes et documentez les exceptions. Le playbook d'enrichissement SIEM fournit un schéma aval concret, tandis que le guide comparatif des API aide à déterminer où une seconde source ou une sandbox spécialisée reste nécessaire.

Valider, puis étendre l'intégration

La gate de livraison doit exercer un identifiant valide, un identifiant refusé, un timeout, une erreur serveur transitoire, une réponse limitée, du JSON mal formé et un succès incomplet. Vérifiez que chaque chemin produit une décision de nouvelle tentative bornée et une entrée de log expurgée. Testez la rotation de clé sans redémarrer les services indépendants.

Ajoutez un petit test de contrat à l'intégration continue, mais excluez-le des builds de forks non fiables où les secrets pourraient être exposés. Il doit appeler un indicateur non sensible, vérifier uniquement les champs stables nécessaires à l'adaptateur et échouer clairement si le schéma change. Ne prenez pas de snapshot du payload complet : le contexte d'enrichissement peut évoluer sans rompre votre contrat. Exécutez un contrôle synthétique séparé depuis la supervision de production afin de détecter l'expiration d'un identifiant, une panne DNS ou TLS, ou une forme de réponse inattendue avant la première requête d'un analyste.

Une fois le premier lookup stable, reliez-le à un workflow voisin depuis le catalogue des intégrations. Conservez le même adaptateur et le même modèle de preuve lorsque vous ajoutez le triage en masse, l'enrichissement SIEM ou l'ingestion de flux. Ce premier appel fiable établit un contrat réutilisable : entrée explicite, authentification protégée, sortie validée, échec observable et action réversible.