Aller au contenu principal

Guide d’intégration

Flux de menaces pour Elastic Security en TAXII 2.1, prêt pour les règles indicator match

L’intégration Custom Threat Intelligence interroge une collection TAXII 2.1 d’isMalicious avec votre clé API et garde un document par indicateur, prêt pour les règles indicator match. Sans offre TAXII, une liste se charge en value list.

Aucune carte bancaire requise · Clé API gratuite

Chemin des données
  1. isMalicious

    api.ismalicious.com/taxii/

    c2-indicators

  2. Elastic Security

    Étape 3

    La pointer vers une collection

  3. Créer une règle indicator match

    Étape 5
Sur cette page08

Ce que vous obtenez

Une intégration interroge une collection. Commencez par les collections par catégorie ci-dessous ; les plus larges, comme malicious-ips et malicious-domains, ne sont filtrées par aucune catégorie : lisez la taille d’une collection avant de l’ajouter (Vérifier le résultat). Les listes se chargent, elles, en value lists.

ListeEntréesRégénéréeOffres
c2-indicatorsPour commencer : IP et domaines des catégories C2 et botnet.paginéà chaque requêtePro et Enterprise
ransomware-iocsDomaines, IP, URL et empreintes de fichiers de la catégorie ransomware.paginéà chaque requêtePro et Enterprise
phishing-indicatorsDomaines et URL de la catégorie phishing.paginéà chaque requêtePro et Enterprise
blocklist-ips-critical.txtSans TAXII : une value list de type IP addresses. IP signalées par 6 sources de menaces ou plus, ou par 3 ou plus avec une catégorie critique.environ 89 000toutes les 12 hBasic, Pro et Enterprise
blocklist-domains-c2.txtSans TAXII : une value list de type Keywords, avec les domaines de commande et contrôle (C2).environ 22 000toutes les 12 hBasic, Pro et Enterprise
/app/integrations/elasticIOC envoyés dans un index Elasticsearch par l’API Bulk. Ce n’est pas un flux : voyez les limites.jusqu’à 1 000 par synchronisationà la synchronisationPro et Enterprise

Nombres arrondis d’après la génération du  ; chaque liste est régénérée toutes les 12 heures. Les chiffres du jour sont publics et ne demandent aucune clé.

Ce que reçoit chaque offre

  • FreeCompte Free, ou aucune clé : les premiers 10 % de chaque liste, signalés par X-Blocklist-Version: lite.
  • Basic, Pro et EnterpriseBasic, Pro et Enterprise : toutes les listes, complètes.
  • Pro et EnterpriseCollections TAXII 2.1 : Pro et Enterprise.
  • Pro et EnterpriseDestinations SIEM du tableau de bord (Splunk, Elastic, Sentinel) : Pro et Enterprise.

Comparer les offres

Ce que renvoie un téléchargementHTTP

GET https://api.ismalicious.com/blocklist/download/blocklist-ips-critical.txt

Liste complète ou échantillon de 10 %

ChampBasic, Pro et EnterpriseFree
X-Blocklist-Version:fulllite
X-Blocklist-Percentage:10010
Total entries:<COUNT><COUNT> (Lite Version - 10% of <TOTAL>)

Premières lignes du fichier

# IsMalicious.com Blocklist - IPs (Critical)
# Format: Plain
# Generated: <BUILD_TIME>
# Total entries: <COUNT>
# Update frequency: every 12 hours
# Category: All
# Threat level: Critical
# Website: https://ismalicious.com
# © <YEAR> IsMalicious (compilation). Licensed to the downloading account under https://ismalicious.com/terms; redistribution of the compilation prohibited. Third-party entries remain under their providers' licences — see https://ismalicious.com/sources.
#

Les valeurs entre chevrons sont fixées à chaque génération.

Prérequis

  • Elastic Stack avec Fleet et Elastic Agent, et l’intégration Custom Threat Intelligence 1.8.2 ou ultérieure, qui demande Kibana 8.19.16 ou ultérieur en 8.19, ou 9.3.5 ou ultérieur en 9.x : Kibana 9.0 à 9.3.4 n’obtient que la 1.7.2. Le mode agentless (désormais Elastic Managed Integration) est en GA sur Serverless et sur Elastic Cloud Hosted à partir de 9.5, en préversion technique de 9.0 à 9.4.
  • Des événements DNS, proxy ou réseau avec des champs ECS comme dns.question.name, source.ip et destination.ip, que les règles comparent.
  • Une clé API et son secret isMalicious, dans Compte › Accès API.
  • Un accès HTTPS sortant (TCP 443) en IPv4 depuis l’agent Elastic, ou Elastic Cloud en mode agentless, vers api.ismalicious.com, qui n’a pas d’adresse IPv6.

Mise en place

  1. Copier la clé API et le secret

    Ouvrez Compte › Accès API et copiez la Clé API et le Secret API. Les collections TAXII demandent une offre Pro ou Enterprise ; les autres offres reçoivent un 403. Les value lists demandent Basic, Pro ou Enterprise.
  2. Ajouter l’intégration Custom Threat Intelligence

    Dans Kibana, ouvrez Integrations, cherchez Custom Threat Intelligence et cliquez sur Add Custom Threat Intelligence. Utilisez la version 1.8.2 ou ultérieure : avant elle, les pages qui suivent la première perdent added_after, et le serveur renvoie alors tous les indicateurs sur ces pages.
  3. La pointer vers une collection

    • Activez Collect STIX data via RESTful API, désactivé à l’ajout de l’intégration, et saisissez les valeurs ci-dessous ; les identifiants, Limit et Feed name se trouvent dans les options avancées.
    • L’intégration envoie la clé et le secret en HTTP Basic à chaque requête.
    • Laissez API Key vide (renseignée, elle partirait en jeton Bearer à la place), les en-têtes Accept et Content-Type à leurs valeurs par défaut, et n’ajoutez jamais de paramètres à l’URL : l’intégration ajoute les siens.
    • Gardez Initial Interval renseigné : sans lui, l’intégration n’envoie jamais added_after.
    • Ici, la première interrogation lit 30 jours.
    Réglages de Custom Threat IntelligenceKibana
    URL API endpoint
    https://api.ismalicious.com/taxii/api-root/collections/c2-indicators/objects/
    Enable TAXII 2.1
    on
    Interval
    1h
    Initial Interval
    720h
    IOC Expiration Duration
    90d

    # Advanced options:

    Basic Auth Username
    <API_KEY>
    Basic Auth Password
    <API_SECRET>
    Limit
    1000
    Feed name
    isMalicious c2-indicators
    URL API endpoint ........ https://api.ismalicious.com/taxii/api-root/collections/c2-indicators/objects/
    Enable TAXII 2.1 ........ on
    Interval ................ 1h
    Initial Interval ........ 720h
    IOC Expiration Duration . 90d
    
    # Advanced options:
    Basic Auth Username ..... <API_KEY>
    Basic Auth Password ..... <API_SECRET>
    Limit ................... 1000
    Feed name ............... isMalicious c2-indicators
  4. L’enregistrer, puis recommencer par collection

    Choisissez la politique d’agent, ou le mode agentless d’Elastic Cloud ou Serverless, puis Save and continue. L’URL nomme la collection : chaque collection demande sa propre intégration, avec un nom de flux qui commence par isMalicious, que la règle ci-dessous retrouve en entier.
  5. Créer une règle indicator match

    • Dans Règles de détection (SIEM) (Detection rules), cliquez sur Créer une nouvelle règle, puis Correspondance d’indicateur (Indicator Match).
    • Lisez les indicateurs dans logs-ti_custom_latest.indicator, l’alias qui garde un document par indicateur et l’écarte quand sa stix.ioc_expiration_date passe.
    • Remplacez la requête d’index d’indicateurs par défaut, @timestamp > "now-30d/d", par celle ci-dessous, sans filtre de date : l’intégration fixe @timestamp à la date created du STIX, et Elastic garde les dates de la première livraison d’un indicateur, si bien qu’un filtre sur l’une ou l’autre écarte des indicateurs que les sources signalent encore.
    • L’intégration range les domaines dans threat.indicator.url.original ; pour les IP, une seconde règle sur vos index réseau associe destination.ip, ou source.ip dans un groupe séparé, à threat.indicator.ip.
    Règles indicator match pour les domaines et les IPKibana
    Rule type
    Indicator Match
    Index patterns
    <DNS_INDEX_PATTERN>
    Custom query
    dns.question.name:*
    Indicator index patterns
    logs-ti_custom_latest.indicator
    Indicator index query
    threat.feed.name:isMalicious* and threat.indicator.type:"domain-name"
    Indicator mapping
    dns.question.name MATCHES threat.indicator.url.original

    # The IP rule, on your network indices:

    Indicator index query
    threat.feed.name:isMalicious* and threat.indicator.type:(ipv4-addr or ipv6-addr)
    Indicator mapping
    destination.ip MATCHES threat.indicator.ip
    OR
    source.ip MATCHES threat.indicator.ip
    Rule type ................ Indicator Match
    Index patterns ........... <DNS_INDEX_PATTERN>
    Custom query ............. dns.question.name:*
    Indicator index patterns . logs-ti_custom_latest.indicator
    Indicator index query .... threat.feed.name:isMalicious* and threat.indicator.type:"domain-name"
    Indicator mapping ........ dns.question.name MATCHES threat.indicator.url.original
    
    # The IP rule, on your network indices:
    Indicator index query .... threat.feed.name:isMalicious* and threat.indicator.type:(ipv4-addr or ipv6-addr)
    Indicator mapping ........ destination.ip MATCHES threat.indicator.ip
                        OR ... source.ip MATCHES threat.indicator.ip
  6. Ou charger une liste en value list

    • Sans offre TAXII, téléchargez une liste, comparez ses deux nombres, vérifiez que ce n’est pas l’échantillon de 10 %, et retirez ses lignes d’en-tête #.
    • Dans Detection rules (SIEM) › Manage value lists, choisissez le type IP addresses (Keywords pour des domaines), sélectionnez le fichier et cliquez sur Import value list : la liste prend le nom du fichier comme identifiant.
    • Dans une règle indicator match, prenez .items-default comme index d’indicateurs (dans un autre espace, .items- suivi de l’identifiant de l’espace) et interrogez cet identifiant ; une liste Keywords s’associe à keyword.
    • Pour rafraîchir, supprimez la value list et importez-la de nouveau : importer un fichier du même nom ajoute ses valeurs à la liste au lieu de la remplacer.
    Télécharger et préparer une value listsh
    # ~/.ismalicious.netrc (mode 600) holds the three netrc lines of your key.
    curl -fsS --netrc-file ~/.ismalicious.netrc -o list.txt \
      https://api.ismalicious.com/blocklist/download/blocklist-ips-critical.txt
    # The header's count, the entries' count, and the 10% sample marker:
    grep -m1 'Total entries' list.txt
    grep -c '^[^#]' list.txt
    grep -q 'Lite Version' list.txt && echo 'lite list: check the key and the plan'
    grep -v '^#' list.txt > ismalicious-ips-critical.txt
    Règle indicator match sur une value listKibana
    Indicator index patterns
    .items-default
    Indicator index query
    list_id : "ismalicious-ips-critical.txt"
    Indicator mapping
    destination.ip MATCHES ip

    # A Keywords list of domains maps to keyword:

    Indicator mapping
    dns.question.name MATCHES keyword
    Indicator index patterns . .items-default
    Indicator index query .... list_id : "ismalicious-ips-critical.txt"
    Indicator mapping ........ destination.ip MATCHES ip
    
    # A Keywords list of domains maps to keyword:
    Indicator mapping ........ dns.question.name MATCHES keyword
  7. Envoyer des IOC dans un index (facultatif, Pro ou Enterprise)

    • Créez une clé API Elasticsearch avec les privilèges index et auto_configure sur ismalicious-* et copiez sa valeur encoded.
    • Dans /app/integrations/elastic, saisissez l’URL de base Elastic (le point d’accès Elasticsearch, pas Kibana), la valeur encodée en Clé API, et ismalicious-iocs en Index des IOC.
    • Cliquez sur Tester, puis sur Synchroniser maintenant : chaque synchronisation envoie jusqu’à 1 000 IOC (100 par défaut) à partir de l’endroit où la précédente s’est arrêtée.
    • Lancez ensuite GET ismalicious-iocs/_count dans Dev Tools : l’API Bulk répond 200 même quand elle rejette tous les documents, si bien qu’une clé sans auto_configure ou un conflit de mapping passe pour livré dans le tableau de bord.

Vérifier le résultat

  • Dans Fleet, la politique d’agent affiche l’intégration en bonne santé. Une requête en échec apparaît comme un événement dont le error.message commence par GET: et contient la réponse du serveur.
  • Dans Discover, créez une vue de données sur logs-ti_custom_latest.indicator et élargissez la période à plusieurs années : @timestamp est la date où une source a signalé chaque indicateur pour la première fois. La requête ci-dessous affiche alors les indicateurs, avec threat.indicator.type, threat.indicator.ip ou threat.indicator.url.original, et stix.ioc_expiration_date.
  • La ressource de la collection donne sa taille dans x_ismalicious_total, comptée toutes les 12 heures et absente jusqu’au premier comptage. La première interrogation ne lit que l’Initial Interval, et un indicateur présent dans deux collections n’est gardé qu’une fois : attendez-vous à moins.
  • Les résultats d’exécution de la règle listent ses passages. Un événement contenant une valeur listée déclenche une alerte enrichie de l’indicateur correspondant.
  • Manage value lists ouvre la liste depuis son nom de fichier ; le Total items affiché correspond au nombre de lignes du fichier préparé.
VérificationsKibana · sh
# Discover, on a data view for logs-ti_custom_latest.indicator, with a time
# range of several years (@timestamp is the date a source first reported it):
threat.feed.name:isMalicious*

# The collection's size, counted every 12 hours (x_ismalicious_total):
curl -fsS --netrc-file ~/.ismalicious.netrc \
  -H 'Accept: application/taxii+json;version=2.1' \
  https://api.ismalicious.com/taxii/api-root/collections/c2-indicators/

# Pushed documents, in Dev Tools:
GET ismalicious-iocs/_count

Dépannage

401 Unauthorized

La clé ou le secret est faux, ou absent : ressaisissez Basic Auth Username et Basic Auth Password. Régénérer la clé dans Compte › Accès API invalide l’ancienne paire.

403 UPGRADE_REQUIRED

Les collections TAXII demandent une offre Pro ou Enterprise. Avec une autre offre, utilisez les value lists.

429 Too Many Requests

Une offre Pro autorise 60 requêtes par 60 secondes pour tout le compte, et chaque page est une requête : les intégrations qui interrogent en même temps s’additionnent. Elastic Agent réessaie un 429 jusqu’à 5 fois, en attendant le délai Retry-After. Si le dernier essai échoue, le parcours s’arrête, et l’intervalle suivant commence un nouveau parcours après la dernière page lue, ce qui peut sauter des indicateurs (voir les limites). Gardez Limit à 1000, interrogez moins de collections à la fois, ou passez à Enterprise, qui autorise 5 000 requêtes par 60 secondes.

« exceeding maximum number of CEL executions »

Le parcours a demandé plus de pages que Maximum Pages Per Interval. Elastic Agent 8.19 ne consigne qu’un avertissement, 9.0 à 9.3 passent l’intégration en Degraded, et 9.4 et ultérieur consignent « reached maximum number of CEL executions » sans changer d’état ; le parcours continue à l’intervalle suivant. Augmentez ce réglage, ou raccourcissez Initial Interval.

400 Bad Request

À chaque requête : l’URL porte ses propres paramètres, comme ?min_score= ; retirez-les. Une seule fois, avec « Invalid or expired next pagination token » : le parcours s’arrête, et l’intervalle suivant commence un nouveau parcours après la dernière page lue, ce qui peut sauter des indicateurs (voir les limites).

503 ou 504

Une erreur passagère de notre côté. Elastic Agent réessaie jusqu’à 5 fois ; si tous les essais échouent, l’intervalle suivant commence un nouveau parcours après la dernière page lue.

Aucune alerte alors que les indicateurs sont là

La requête d’index d’indicateurs filtre encore sur une date, @timestamp ou threat.indicator.last_seen, ou les domaines sont associés à threat.indicator.url.domain au lieu de threat.indicator.url.original.

Une value list contient environ un dixième de la liste

Aucun identifiant n’est parvenu au serveur, ou l’offre est Free ou interrompue : un abonnement impayé, en retard de paiement, annulé, incomplet ou suspendu compte comme Free. La ligne Total entries du fichier indique alors Lite Version. TAXII n’a pas d’échantillon : une offre sans TAXII reçoit un 403.

Le test de l’envoi échoue

L’URL de base doit être en HTTPS public : les adresses privées, de bouclage, link-local et réservées sont refusées, et un envoi expire au bout de 5 secondes.

Limites

  • Les interrogations incrémentales reprennent à l’en-tête X-Taxii-Date-Added-Last de la dernière page lue. Un parcours complet se termine sur une page dont l’en-tête donne le début du parcours, moins dix minutes : l’interrogation suivante ne manque rien et renvoie ce qui a été ajouté pendant le parcours. Un parcours interrompu, par des essais ratés, un jeton next expiré ou un redémarrage de l’agent, laisse le curseur sur une page antérieure, dont l’en-tête ne donne que la date la plus récente de cette page, et les pages suivent l’ordre de stockage, pas l’ordre des dates : l’interrogation suivante peut sauter ce que le parcours n’avait pas lu. Les petites collections réduisent la fenêtre. Elle n’a pas été mesurée.
  • Elastic garde chaque indicateur tel qu’il a été livré la première fois : un signalement ultérieur ne le renvoie pas, si bien qu’il quitte logs-ti_custom_latest.indicator 90 jours après la date de dernière observation qu’il avait alors, même si des sources le signalent encore.
  • Un indicateur présent dans deux collections n’est gardé qu’une fois, sous l’un des noms de flux : l’alias se fonde sur l’identifiant STIX, le même dans toutes les collections. Filtrez sur threat.feed.name:isMalicious*, jamais sur un seul nom de flux.
  • Les domaines arrivent dans threat.indicator.url.original, un choix de l’intégration. Les règles indicator match fournies par Elastic n’y associent aucun champ DNS : écrivez vous-même la règle des domaines.
  • Pas de filtre par score : l’intégration ajoute ses propres paramètres à l’URL, si bien que min_score et max_score ne peuvent pas être fixés.
  • L’envoi n’est pas un flux : il s’exécute quand vous cliquez sur Synchroniser maintenant et envoie au plus 1 000 IOC par synchronisation. Ses documents portent des champs isMalicious, ni @timestamp ni champs ECS threat.indicator : une règle indicator match ne peut pas les lire sans un pipeline d’ingestion de votre cru.
  • Les value lists se rafraîchissent à la main, acceptent des fichiers jusqu’à 9 Mo par défaut, et un nouvel import du même nom s’ajoute à la liste.
  • Aucune liste CSV, JSON, CIDR ou à jokers n’est servie. Les patterns TAXII portent une seule valeur chacun, que l’intégration lit entièrement.

Questions fréquentes

Quelle version de Custom Threat Intelligence faut-il ?

1.8.2 ou ultérieure, qui demande Kibana 8.19.16 ou ultérieur en 8.19, ou 9.3.5 ou ultérieur en 9.x. Avant 1.8.2, les pages qui suivent la première perdent added_after, et le serveur renvoie alors tous les indicateurs sur ces pages.

Pourquoi changer la requête d’index d’indicateurs par défaut ?

La requête par défaut, @timestamp > "now-30d/d", garde les indicateurs ingérés depuis 30 jours, et l’intégration fixe @timestamp à la date où une source a signalé l’indicateur pour la première fois. Elastic garde aussi les dates de la première livraison d’un indicateur : tout filtre de date écarte des indicateurs que les sources signalent encore. Filtrez plutôt sur le nom du flux et le type : l’alias des derniers indicateurs écarte déjà un indicateur quand sa date d’expiration passe.

À quel rythme une offre Pro peut-elle interroger ?

Une offre Pro autorise 60 requêtes TAXII par 60 secondes pour tout le compte, une par page, et une page contient jusqu’à 1 000 indicateurs avec Limit à 1000. Enterprise autorise 5 000 requêtes par 60 secondes. Les interrogations ne comptent pas dans le quota mensuel de requêtes.

Puis-je utiliser isMalicious dans Elastic Security sans offre TAXII ?

Oui, avec les value lists. Une offre Basic, Pro ou Enterprise télécharge les listes complètes, que vous importez en value lists et rafraîchissez à la main. Les collections TAXII demandent Pro ou Enterprise.

Commencer

Prêt à commencer ?

Aucune carte bancaire requise · Clé API gratuite