Raccogliere i risultati di DomainTools Iris Investigate

Questo documento spiega come importare i risultati di DomainTools Iris Investigate in Google Security Operations utilizzando Amazon S3. Il parser trasforma i dati JSON non elaborati dell'API Iris di DomainTools in un formato strutturato conforme al modello UDM (Unified Data Model) di Google SecOps. Estrae informazioni relative a dettagli del dominio, informazioni di contatto, rischi per la sicurezza, certificati SSL e altri attributi pertinenti, mappandoli ai campi UDM corrispondenti per un'analisi coerente e per la threat intelligence.

Prima di iniziare

• Istanza Google SecOps
• Accesso con privilegi all'account aziendale DomainTools (accesso API a Iris Investigate)
• Accesso privilegiato ad AWS (S3, IAM, Lambda, EventBridge)

Ottieni la chiave API e l'endpoint DomainTools

1. Accedi alla dashboard API di DomainTools (solo l'account proprietario dell'API può reimpostare la chiave API).
2. Nella sezione Il mio account, seleziona il link Visualizza dashboard API nella scheda Riepilogo account.
3. Vai alla sezione Nome utente API per ottenere il tuo nome utente.
4. Nella stessa scheda, individua la chiave API.
5. Copia e salva la chiave in un luogo sicuro.

6. Se hai bisogno di una nuova chiave, seleziona Reimposta chiave API.

7. Prendi nota dell'endpoint di Iris Investigate: https://api.domaintools.com/v1/iris-investigate/.

Configura il bucket AWS S3 e IAM per Google SecOps

1. Crea un bucket Amazon S3 seguendo questa guida utente: Creazione di un bucket
2. Salva il nome e la regione del bucket per riferimento futuro (ad esempio, domaintools-iris).
3. Crea un utente seguendo questa guida: Creazione di un utente IAM.
4. Seleziona l'utente creato.
5. Seleziona la scheda Credenziali di sicurezza.
6. Fai clic su Crea chiave di accesso nella sezione Chiavi di accesso.
7. Seleziona Servizio di terze parti come Caso d'uso.
8. Fai clic su Avanti.
9. (Facoltativo) Aggiungi un tag di descrizione.
10. Fai clic su Crea chiave di accesso.
11. Fai clic su Scarica file CSV per salvare la chiave di accesso e la chiave di accesso segreta per un utilizzo successivo.
12. Fai clic su Fine.
13. Seleziona la scheda Autorizzazioni.
14. Fai clic su Aggiungi autorizzazioni nella sezione Criteri per le autorizzazioni.
15. Seleziona Aggiungi autorizzazioni.
16. Seleziona Allega direttamente i criteri.
17. Cerca e seleziona il criterio AmazonS3FullAccess.
18. Fai clic su Avanti.
19. Fai clic su Aggiungi autorizzazioni.

Configura il ruolo e il criterio IAM per i caricamenti S3

1. Nella console AWS, vai a IAM > Policy > Crea policy > Scheda JSON.

2. Inserisci la seguente policy:

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

   • Sostituisci domaintools-iris se hai inserito un nome bucket diverso.

3. Fai clic su Avanti > Crea policy.

4. Vai a IAM > Ruoli > Crea ruolo > Servizio AWS > Lambda.

5. Allega il criterio appena creato.

6. Assegna al ruolo il nome WriteDomainToolsIrisToS3Role e fai clic su Crea ruolo.

Crea la funzione Lambda

1. Nella console AWS, vai a Lambda > Funzioni > Crea funzione.
2. Fai clic su Crea autore da zero.

3. Fornisci i seguenti dettagli di configurazione:

   Impostazione	Valore
   Nome	domaintools_iris_to_s3
   Tempo di esecuzione	Python 3.13
   Architettura	x86_64
   Ruolo di esecuzione	WriteDomainToolsIrisToS3Role

4. Dopo aver creato la funzione, apri la scheda Codice, elimina lo stub e inserisci il seguente codice (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. Vai a Configurazione > Variabili di ambiente > Modifica > Aggiungi nuova variabile di ambiente.

6. Inserisci le seguenti variabili di ambiente, sostituendole con i tuoi valori:

   Chiave	Valore di esempio	Descrizione
   S3_BUCKET	domaintools-iris	Nome del bucket S3 in cui verranno archiviati i dati.
   S3_PREFIX	domaintools/iris/	Prefisso S3 (sottocartella) facoltativo per gli oggetti.
   STATE_KEY	domaintools/iris/state.json	Chiave facoltativa del file di stato/checkpoint.
   DT_API_KEY	DT-XXXXXXXXXXXXXXXXXXXX	Chiave API DomainTools.
   DT_API_SECRET	YYYYYYYYYYYYYYYYYYYYYYYY	API secret di DomainTools (se applicabile).
   USE_MODE	HASH | DOMAINS | QUERY	Seleziona la modalità da utilizzare (solo una è attiva alla volta).
   SEARCH_HASHES	hash1;hash2;hash3	Obbligatorio se USE_MODE=HASH. Elenco separato da punto e virgola degli hash delle ricerche salvate dall'interfaccia utente di Iris.
   DOMAINS	example.com;domaintools.com	Obbligatorio se USE_MODE=DOMAINS. Elenco di domini separati da punti e virgola.
   QUERY_LIST	ip=1.1.1.1;ip=8.8.8.8;domain=example.org	Obbligatorio se USE_MODE=QUERY. Elenco di stringhe di query separate da punto e virgola (k=v&k2=v2).
   PAGE_SIZE	500	Righe per pagina (valore predefinito 500).
   MAX_PAGES	20	Numero massimo di pagine per richiesta

7. Dopo aver creato la funzione, rimani sulla relativa pagina (o apri Lambda > Funzioni > la tua funzione).

8. Seleziona la scheda Configurazione.

9. Nel riquadro Configurazione generale, fai clic su Modifica.

10. Modifica Timeout impostando 15 minuti (900 secondi) e fai clic su Salva.

Creare una pianificazione EventBridge

1. Vai a Amazon EventBridge > Scheduler > Crea pianificazione.
2. Fornisci i seguenti dettagli di configurazione:
   • Programma ricorrente: Tariffa (1 hour).
   • Destinazione: la tua funzione Lambda.
   • Nome: domaintools-iris-1h
3. Fai clic su Crea pianificazione.

(Facoltativo) Crea chiavi e utente IAM di sola lettura per Google SecOps

1. Nella console AWS, vai a IAM > Utenti, poi fai clic su Aggiungi utenti.
2. Fornisci i seguenti dettagli di configurazione:
   • Utente: inserisci un nome univoco (ad esempio secops-reader)
   • Tipo di accesso: seleziona Chiave di accesso - Accesso programmatico
   • Fai clic su Crea utente.
3. Allega criterio per la lettura minimi (personalizzati): Utenti > seleziona secops-reader > Autorizzazioni > Aggiungi autorizzazioni > Allega criteri direttamente > Crea criteri

4. Nell'editor JSON, inserisci la seguente policy:

   {
     "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. Imposta il nome su secops-reader-policy.

6. Vai a Crea criterio > cerca/seleziona > Avanti > Aggiungi autorizzazioni.

7. Vai a Credenziali di sicurezza > Chiavi di accesso > Crea chiave di accesso.

8. Scarica il file CSV (questi valori vengono inseriti nel feed).

Configura un feed in Google SecOps per importare i risultati di DomainTools Iris Investigate

1. Vai a Impostazioni SIEM > Feed.
2. Fai clic su Aggiungi nuovo feed.
3. Nel campo Nome feed, inserisci un nome per il feed (ad esempio, DomainTools Iris Investigate).
4. Seleziona Amazon S3 V2 come Tipo di origine.
5. Seleziona DomainTools Threat Intelligence come Tipo di log.
6. Fai clic su Avanti.
7. Specifica i valori per i seguenti parametri di input:
   • URI S3: s3://domaintools-iris/domaintools/iris/
   • Opzioni di eliminazione dell'origine: seleziona l'opzione di eliminazione in base alle tue preferenze.
   • Durata massima del file: 180 giorni per impostazione predefinita.
   • ID chiave di accesso: chiave di accesso utente con accesso al bucket S3.
   • Chiave di accesso segreta: chiave segreta dell'utente con accesso al bucket S3.
   • Spazio dei nomi dell'asset: domaintools.threat_intel
   • Etichette di importazione: l'etichetta da applicare agli eventi di questo feed.
8. Fai clic su Avanti.
9. Controlla la nuova configurazione del feed nella schermata Finalizza e poi fai clic su Invia.

Tabella di mappatura UDM

Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.