Collecter les résultats de DomainTools Iris Investigate

Ce document explique comment ingérer les résultats de DomainTools Iris Investigate dans Google Security Operations à l'aide d'Amazon S3. L'analyseur transforme les données JSON brutes de l'API Iris de DomainTools en un format structuré conforme au modèle de données unifié (UDM) de Google SecOps. Il extrait des informations sur les détails du domaine, les coordonnées, les risques de sécurité, les certificats SSL et d'autres attributs pertinents, et les mappe aux champs UDM correspondants pour une analyse cohérente et des renseignements sur les menaces.

Avant de commencer

• Instance Google SecOps
• Accès privilégié au compte DomainTools Enterprise (accès à l'API Iris Investigate)
• Accès privilégié à AWS (S3, IAM, Lambda, EventBridge)

Obtenir la clé API et le point de terminaison DomainTools

1. Connectez-vous au tableau de bord de l'API DomainTools (seul le compte du propriétaire de l'API peut réinitialiser la clé API).
2. Dans la section Mon compte, sélectionnez le lien Afficher le tableau de bord des API situé dans l'onglet Récapitulatif du compte.
3. Accédez à la section Nom d'utilisateur de l'API pour obtenir votre nom d'utilisateur.
4. Dans le même onglet, recherchez votre clé API.
5. Copiez et enregistrez la clé dans un emplacement sécurisé.

6. Si vous avez besoin d'une nouvelle clé, sélectionnez Réinitialiser la clé API.

7. Notez le point de terminaison Iris Investigate : https://api.domaintools.com/v1/iris-investigate/.

Configurer un bucket AWS S3 et IAM pour Google SecOps

1. Créez un bucket Amazon S3 en suivant ce guide de l'utilisateur : Créer un bucket.
2. Enregistrez le nom et la région du bucket pour référence ultérieure (par exemple, domaintools-iris).
3. Créez un utilisateur en suivant ce guide : Créer un utilisateur IAM.
4. Sélectionnez l'utilisateur créé.
5. Sélectionnez l'onglet Informations d'identification de sécurité.
6. Cliquez sur Créer une clé d'accès dans la section Clés d'accès.
7. Sélectionnez Service tiers comme Cas d'utilisation.
8. Cliquez sur Suivant.
9. Facultatif : ajoutez un tag de description.
10. Cliquez sur Créer une clé d'accès.
11. Cliquez sur Télécharger le fichier CSV pour enregistrer la clé d'accès et la clé d'accès secrète pour une utilisation ultérieure.
12. Cliquez sur OK.
13. Sélectionnez l'onglet Autorisations.
14. Cliquez sur Ajouter des autorisations dans la section Règles d'autorisation.
15. Sélectionnez Ajouter des autorisations.
16. Sélectionnez Joindre directement des règles.
17. Recherchez et sélectionnez la règle AmazonS3FullAccess.
18. Cliquez sur Suivant.
19. Cliquez sur Ajouter des autorisations.

Configurer la stratégie et le rôle IAM pour les importations S3

1. Dans la console AWS, accédez à IAM > Policies > Create policy > onglet JSON.

2. Saisissez la règle suivante :

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AllowPutDomainToolsIrisObjects",
         "Effect": "Allow",
         "Action": "s3:PutObject",
         "Resource": "arn:aws:s3:::domaintools-iris/*"
       }
     ]
   }
   

   • Remplacez domaintools-iris si vous avez saisi un autre nom de bucket.

3. Cliquez sur Suivant > Créer une règle.

4. Accédez à IAM > Rôles > Créer un rôle > Service AWS > Lambda.

5. Associez la règle que vous venez de créer.

6. Nommez le rôle WriteDomainToolsIrisToS3Role, puis cliquez sur Créer un rôle.

Créer la fonction Lambda

1. Dans la console AWS, accédez à Lambda > Fonctions > Créer une fonction.
2. Cliquez sur Créer à partir de zéro.

3. Fournissez les informations de configuration suivantes :

   Paramètre	Valeur
   Nom	domaintools_iris_to_s3
   Durée d'exécution	Python 3.13
   Architecture	x86_64
   Rôle d'exécution	WriteDomainToolsIrisToS3Role

4. Une fois la fonction créée, ouvrez l'onglet Code, supprimez le stub et saisissez le code suivant (domaintools_iris_to_s3.py) :

   #!/usr/bin/env python3
   # Lambda: Pull DomainTools Iris Investigate results to S3 (no transform)
   
   import os, json, time, urllib.parse
   from urllib.request import Request, urlopen
   from urllib.error import HTTPError
   import boto3
   
   # --- Environment ---
   S3_BUCKET    = os.environ["S3_BUCKET"].strip()
   S3_PREFIX    = os.environ.get("S3_PREFIX", "domaintools/iris/").strip()
   STATE_KEY    = os.environ.get("STATE_KEY", "domaintools/iris/state.json").strip()
   
   DT_API_KEY   = os.environ["DT_API_KEY"].strip()
   DT_API_SECRET= os.environ.get("DT_API_SECRET", "").strip()  # optional if your account uses key-only auth
   
   USE_MODE     = os.environ.get("USE_MODE", "HASH").strip().upper()  # HASH | DOMAINS | QUERY
   SEARCH_HASHES= [h.strip() for h in os.environ.get("SEARCH_HASHES", "").split(";") if h.strip()]
   DOMAINS      = [d.strip() for d in os.environ.get("DOMAINS", "").split(";") if d.strip()]
   QUERY_LIST   = [q.strip() for q in os.environ.get("QUERY_LIST", "").split(";") if q.strip()]
   
   PAGE_SIZE    = int(os.environ.get("PAGE_SIZE", "500"))
   MAX_PAGES    = int(os.environ.get("MAX_PAGES", "20"))
   USE_NEXT     = os.environ.get("USE_NEXT", "true").lower() == "true"
   HTTP_TIMEOUT = int(os.environ.get("HTTP_TIMEOUT", "60"))
   RETRIES      = int(os.environ.get("HTTP_RETRIES", "2"))
   
   BASE_URL = "https://api.domaintools.com/v1/iris-investigate/"
   HDRS = {
       "X-Api-Key": DT_API_KEY,
       "Accept": "application/json",
   }
   if DT_API_SECRET:
       HDRS["X-Api-Secret"] = DT_API_SECRET
   
   s3 = boto3.client("s3")
   
   # --- HTTP helpers ---
   
   def _http_get(url: str) -> dict:
       req = Request(url, method="GET")
       for k, v in HDRS.items():
           req.add_header(k, v)
       attempt = 0
       while True:
           try:
               with urlopen(req, timeout=HTTP_TIMEOUT) as r:
                   return json.loads(r.read().decode("utf-8"))
           except HTTPError as e:
               if e.code in (429, 500, 502, 503, 504) and attempt < RETRIES:
                   delay = int(e.headers.get("Retry-After", "2"))
                   time.sleep(max(1, delay))
                   attempt += 1
                   continue
               raise
   
   def _build_url(params: dict) -> str:
       return BASE_URL + ("?" + urllib.parse.urlencode(params, doseq=True) if params else "")
   
   # --- S3 helpers ---
   
   def _write_page(obj: dict, label: str, page: int) -> str:
       ts = time.strftime("%Y/%m/%d/%H%M%S", time.gmtime())
       key = f"{S3_PREFIX.rstrip('/')}/{ts}-{label}-p{page:05d}.json"
       s3.put_object(
           Bucket=S3_BUCKET, Key=key,
           Body=json.dumps(obj, separators=(",", ":")).encode("utf-8"),
           ContentType="application/json",
       )
       return key
   
   # --- Iris paging ---
   
   def _first_page_params() -> dict:
       params: dict[str, object] = {"page_size": str(PAGE_SIZE)}
       if USE_NEXT:
           params["next"] = "true"
       return params
   
   def _paginate(label: str, params: dict) -> tuple[int, int]:
       pages = 0
       total = 0
       url = _build_url(params)
       while pages < MAX_PAGES:
           data = _http_get(url)
           _write_page(data, label, pages)
   
           resp = data.get("response") or {}
           results = resp.get("results") or []
           total += len(results)
           pages += 1
   
           # Prefer `next` absolute URL if present
           next_url = resp.get("next") if isinstance(resp, dict) else None
           if next_url:
               url = next_url
               continue
   
           # Fallback: position pager when `next=true` not used/supported
           if resp.get("has_more_results") and resp.get("position"):
               base = _first_page_params()
               base.pop("next", None)
               base["position"] = resp["position"]
               url = _build_url(base)
               continue
   
           break
       return pages, total
   
   # --- Mode runners ---
   
   def run_hashes(hashes: list[str]) -> dict:
       agg_pages = agg_results = 0
       for h in hashes:
           params = _first_page_params()
           params["search_hash"] = h
           p, r = _paginate(f"hash-{h}", params)
           agg_pages += p
           agg_results += r
       return {"pages": agg_pages, "results": agg_results}
   
   def run_domains(domains: list[str]) -> dict:
       agg_pages = agg_results = 0
       for d in domains:
           params = _first_page_params()
           # DomainTools accepts `domain` as a filter in Investigate search
           params["domain"] = d
           p, r = _paginate(f"domain-{d}", params)
           agg_pages += p
           agg_results += r
       return {"pages": agg_pages, "results": agg_results}
   
   def run_queries(queries: list[str]) -> dict:
       agg_pages = agg_results = 0
       for q in queries:
           # Merge arbitrary k=v pairs from the query string
           base = _first_page_params()
           for k, v in urllib.parse.parse_qsl(q, keep_blank_values=True):
               base.setdefault(k, v)
           p, r = _paginate(f"query-{q.replace('=','-')}", base)
           agg_pages += p
           agg_results += r
       return {"pages": agg_pages, "results": agg_results}
   
   # --- Entry point ---
   
   def lambda_handler(event=None, context=None):
       if USE_MODE == "HASH" and SEARCH_HASHES:
           res = run_hashes(SEARCH_HASHES)
       elif USE_MODE == "DOMAINS" and DOMAINS:
           res = run_domains(DOMAINS)
       elif USE_MODE == "QUERY" and QUERY_LIST:
           res = run_queries(QUERY_LIST)
       else:
           raise ValueError("Invalid USE_MODE or missing parameters. Set USE_MODE to HASH | DOMAINS | QUERY and provide SEARCH_HASHES | DOMAINS | QUERY_LIST accordingly.")
   
       return {"ok": True, "mode": USE_MODE, **res}
   
   if __name__ == "__main__":
       print(json.dumps(lambda_handler(), indent=2))
   

5. Accédez à Configuration> Variables d'environnement> Modifier> Ajouter une variable d'environnement.

6. Saisissez les variables d'environnement suivantes en remplaçant les valeurs par les vôtres :

   Clé	Exemple de valeur	Description
   S3_BUCKET	domaintools-iris	Nom du bucket S3 dans lequel les données seront stockées.
   S3_PREFIX	domaintools/iris/	Préfixe S3 facultatif (sous-dossier) pour les objets.
   STATE_KEY	domaintools/iris/state.json	Clé de fichier d'état/de point de contrôle facultative.
   DT_API_KEY	DT-XXXXXXXXXXXXXXXXXXXX	Clé API DomainTools.
   DT_API_SECRET	YYYYYYYYYYYYYYYYYYYYYYYY	Secret de l'API DomainTools (le cas échéant).
   USE_MODE	HASH | DOMAINS | QUERY	Sélectionnez le mode à utiliser (un seul peut être actif à la fois).
   SEARCH_HASHES	hash1;hash2;hash3	Obligatoire si USE_MODE=HASH. Liste des hachages de recherches enregistrées de l'interface utilisateur Iris, séparés par un point-virgule.
   DOMAINS	example.com;domaintools.com	Obligatoire si USE_MODE=DOMAINS. Liste de domaines séparés par un point-virgule.
   QUERY_LIST	ip=1.1.1.1;ip=8.8.8.8;domain=example.org	Obligatoire si USE_MODE=QUERY. Liste de chaînes de requête séparées par un point-virgule (k=v&k2=v2).
   PAGE_SIZE	500	Nombre de lignes par page (500 par défaut).
   MAX_PAGES	20	Nombre maximal de pages par requête

7. Une fois la fonction créée, restez sur sa page (ou ouvrez Lambda > Fonctions > votre-fonction).

8. Accédez à l'onglet Configuration.

9. Dans le panneau Configuration générale, cliquez sur Modifier.

10. Définissez Délai avant expiration sur 15 minutes (900 secondes), puis cliquez sur Enregistrer.

Créer une programmation EventBridge

1. Accédez à Amazon EventBridge> Scheduler> Create schedule (Créer une programmation).
2. Fournissez les informations de configuration suivantes :
   • Planning récurrent : Tarif (1 hour).
   • Cible : votre fonction Lambda.
   • Nom : domaintools-iris-1h.
3. Cliquez sur Créer la programmation.

Facultatif : Créez un utilisateur et des clés IAM en lecture seule pour Google SecOps

1. Dans la console AWS, accédez à IAM> Utilisateurs, puis cliquez sur Ajouter des utilisateurs.
2. Fournissez les informations de configuration suivantes :
   • Utilisateur : saisissez un nom unique (par exemple, secops-reader).
   • Type d'accès : sélectionnez Clé d'accès – Accès programmatique.
   • Cliquez sur Créer un utilisateur.
3. Associez une règle de lecture minimale (personnalisée) : Utilisateurs> sélectionnez secops-reader > Autorisations> Ajouter des autorisations> Associer des règles directement> Créer une règle

4. Dans l'éditeur JSON, saisissez la stratégie suivante :

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": ["s3:GetObject"],
         "Resource": "arn:aws:s3:::<your-bucket>/*"
       },
       {
         "Effect": "Allow",
         "Action": ["s3:ListBucket"],
         "Resource": "arn:aws:s3:::<your-bucket>"
       }
     ]
   }
   

5. Définissez le nom sur secops-reader-policy.

6. Accédez à Créer une règle > recherchez/sélectionnez > Suivant > Ajouter des autorisations.

7. Accédez à Identifiants de sécurité > Clés d'accès > Créer une clé d'accès.

8. Téléchargez le CSV (ces valeurs sont saisies dans le flux).

Configurer un flux dans Google SecOps pour ingérer les résultats de DomainTools Iris Investigate

1. Accédez à Paramètres SIEM> Flux.
2. Cliquez sur Add New Feed (Ajouter un flux).
3. Dans le champ Nom du flux, saisissez un nom pour le flux (par exemple, DomainTools Iris Investigate).
4. Sélectionnez Amazon S3 V2 comme type de source.
5. Sélectionnez DomainTools Threat Intelligence comme Type de journal.
6. Cliquez sur Suivant.
7. Spécifiez les valeurs des paramètres d'entrée suivants :
   • URI S3 : s3://domaintools-iris/domaintools/iris/
   • Options de suppression de la source : sélectionnez l'option de suppression de votre choix.
   • Âge maximal des fichiers : 180 jours par défaut.
   • ID de clé d'accès : clé d'accès utilisateur ayant accès au bucket S3.
   • Clé d'accès secrète : clé secrète de l'utilisateur ayant accès au bucket S3.
   • Espace de noms de l'asset : domaintools.threat_intel
   • Libellés d'ingestion : libellé à appliquer aux événements de ce flux.
8. Cliquez sur Suivant.
9. Vérifiez la configuration de votre nouveau flux sur l'écran Finaliser, puis cliquez sur Envoyer.

Table de mappage UDM

Vous avez encore besoin d'aide ? Obtenez des réponses de membres de la communauté et de professionnels Google SecOps.