Raccogliere i log di Zendesk CRM

Supportato in:

Questo documento spiega come importare i log di Zendesk Customer Relationship Management (CRM) in Google Security Operations utilizzando Amazon S3.

Prima di iniziare

Assicurati di soddisfare i seguenti prerequisiti:

  • Un'istanza Google SecOps.
  • Accesso con privilegi a Zendesk.
  • Accesso privilegiato ad AWS (S3, Identity and Access Management (IAM), Lambda, EventBridge).

Requisiti di Zendesk

  1. Conferma il piano e il ruolo
    1. Per creare token API / client OAuth, devi essere un amministratore Zendesk. L'API Audit Logs è disponibile solo con il piano Enterprise. Se il tuo account non è Enterprise, salta il passaggio audit_logs in RESOURCES.
  2. Attivare l'accesso al token API (una tantum)
    1. Nel Centro amministrativo, vai ad App e integrazioni > API > Configurazione API.
    2. Attiva Consenti l'accesso al token API.
  3. Genera un token API (per l'autenticazione di base)
    1. Vai ad App e integrazioni > API > Token API.
    2. Fai clic su Aggiungi token API > (facoltativo) aggiungi Descrizione > Salva.
    3. Copia e salva subito il token API (non potrai visualizzarlo di nuovo).
    4. Salva l'email amministratore che verrà autenticata con questo token.
      • Formato di autenticazione di base utilizzato dalla funzione Lambda: email_address/token:api_token
  4. (Facoltativo) Crea un client OAuth (per l'autenticazione Bearer anziché il token API)
    1. Vai ad App e integrazioni > API > Client OAuth > Aggiungi client OAuth.
    2. Compila i campi Nome, Identificatore univoco (automatico), URL di reindirizzamento (può essere un segnaposto se con l'API vengono creati solo token) e Salva.
    3. Crea un token di accesso per l'integrazione e concedi gli ambiti minimi richiesti da questa guida:
      • tickets:read (per i biglietti incrementali)
      • auditlogs:read (per gli audit log; solo Enterprise)
      • In caso di dubbi, read funziona anche per l'accesso di sola lettura.
    4. Copia il token di accesso (incollalo in ZENDESK_BEARER_TOKEN) e registra in modo sicuro l'ID client/client secret (per i futuri flussi di aggiornamento dei token).

  5. Registrare l'URL di base di Zendesk

    • Utilizza https://<your_subdomain>.zendesk.com (incolla nella variabile di ambiente ZENDESK_BASE_URL).

    Cosa copiare e salvare per un secondo momento

    • URL di base (ad esempio, https://acme.zendesk.com)
    • Indirizzo email dell'utente amministratore (per l'autenticazione con token API)
    • Token API (se utilizzi AUTH_MODE=token)
    • o token di accesso OAuth (se utilizzi AUTH_MODE=bearer)
    • (Facoltativo): ID/secret client OAuth per la gestione del ciclo di vita

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, zendesk-crm-logs).
  3. Crea un utente seguendo questa guida utente: 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 riferimento futuro.
  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 i criteri AmazonS3FullAccess.
  18. Seleziona la policy.
  19. Fai clic su Avanti.
  20. Fai clic su Aggiungi autorizzazioni.

Configura il ruolo e il criterio IAM per i caricamenti S3

  1. Nella console AWS, vai a IAM > Policy.
  2. Fai clic su Crea criterio > scheda JSON.
  3. Copia e incolla i seguenti criteri.

  4. JSON delle policy (sostituisci zendesk-crm-logs se hai inserito un nome del bucket diverso):

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowPutObjects",
      "Effect": "Allow",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::zendesk-crm-logs/*"
    },
    {
      "Sid": "AllowGetStateObject",
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::zendesk-crm-logs/zendesk/crm/state.json"
    }
  ]
}

  5. Fai clic su Avanti > Crea criterio.

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

  7. Allega il criterio appena creato.

  8. Assegna al ruolo il nome ZendeskCRMToS3Role 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 zendesk_crm_to_s3
    Tempo di esecuzione Python 3.13
    Architettura x86_64
    Ruolo di esecuzione ZendeskCRMToS3Role

  4. Dopo aver creato la funzione, apri la scheda Codice, elimina lo stub e incolla il seguente codice (zendesk_crm_to_s3.py).

    #!/usr/bin/env python3

import os, json, time, base64
from urllib.request import Request, urlopen
from urllib.error import HTTPError, URLError
import boto3

S3_BUCKET    = os.environ["S3_BUCKET"]
S3_PREFIX    = os.environ.get("S3_PREFIX", "zendesk/crm/")
STATE_KEY    = os.environ.get("STATE_KEY", "zendesk/crm/state.json")
BASE_URL     = os.environ["ZENDESK_BASE_URL"].rstrip("/")  # e.g. https://your_subdomain.zendesk.com
AUTH_MODE    = os.environ.get("AUTH_MODE", "token").lower()  # token|bearer
EMAIL        = os.environ.get("ZENDESK_EMAIL", "")
API_TOKEN    = os.environ.get("ZENDESK_API_TOKEN", "")
BEARER       = os.environ.get("ZENDESK_BEARER_TOKEN", "")
RESOURCES    = [r.strip() for r in os.environ.get("RESOURCES", "audit_logs,incremental_tickets").split(",") if r.strip()]
MAX_PAGES    = int(os.environ.get("MAX_PAGES", "20"))
LOOKBACK     = int(os.environ.get("LOOKBACK_SECONDS", "3600"))  # 1h default
HTTP_TIMEOUT = int(os.environ.get("HTTP_TIMEOUT", "60"))
HTTP_RETRIES = int(os.environ.get("HTTP_RETRIES", "3"))

s3 = boto3.client("s3")

def _headers() -> dict:
    if AUTH_MODE == "bearer" and BEARER:
        return {"Authorization": f"Bearer {BEARER}", "Accept": "application/json"}
    if AUTH_MODE == "token" and EMAIL and API_TOKEN:
        token = base64.b64encode(f"{EMAIL}/token:{API_TOKEN}".encode()).decode()
        return {"Authorization": f"Basic {token}", "Accept": "application/json"}
    raise RuntimeError("Invalid auth settings: provide token (EMAIL + API_TOKEN) or BEARER")

def _get_state() -> dict:
    try:
        obj = s3.get_object(Bucket=S3_BUCKET, Key=STATE_KEY)
        b = obj["Body"].read()
        return json.loads(b) if b else {"audit_logs": {}, "incremental_tickets": {}}
    except Exception:
        return {"audit_logs": {}, "incremental_tickets": {}}

def _put_state(st: dict) -> None:
    s3.put_object(
        Bucket=S3_BUCKET, Key=STATE_KEY,
        Body=json.dumps(st, separators=(",", ":")).encode("utf-8"),
        ContentType="application/json",
    )

def _http_get_json(url: str) -> dict:
    attempt = 0
    while True:
        try:
            req = Request(url, method="GET")
            for k, v in _headers().items():
                req.add_header(k, v)
            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 < HTTP_RETRIES:
                ra = 1 + attempt
                try:
                    ra = int(e.headers.get("Retry-After", ra))
                except Exception:
                    pass
                time.sleep(max(1, ra))
                attempt += 1
                continue
            raise
        except URLError:
            if attempt < HTTP_RETRIES:
                time.sleep(1 + attempt)
                attempt += 1
                continue
            raise

def _put_page(payload: dict, resource: str) -> str:
    ts = time.gmtime()
    key = f"{S3_PREFIX}/{time.strftime('%Y/%m/%d/%H%M%S', ts)}-zendesk-{resource}.json"
    s3.put_object(
        Bucket=S3_BUCKET, Key=key,
        Body=json.dumps(payload, separators=(",", ":")).encode("utf-8"),
        ContentType="application/json",
    )
    return key

def fetch_audit_logs(state: dict):
    """GET /api/v2/audit_logs.json with pagination via `next_page` (Zendesk)."""
    next_url = state.get("next_url") or f"{BASE_URL}/api/v2/audit_logs.json?page=1"
    pages = 0
    written = 0
    last_next = None
    while pages < MAX_PAGES and next_url:
        data = _http_get_json(next_url)
        _put_page(data, "audit_logs")
        written += len(data.get("audit_logs", []))
        last_next = data.get("next_page")
        next_url = last_next
        pages += 1
    return {"resource": "audit_logs", "pages": pages, "written": written, "next_url": last_next}

def fetch_incremental_tickets(state: dict):
    """Cursor-based incremental export: /api/v2/incremental/tickets/cursor.json (pagination via `links.next`)."""
    next_link = state.get("next")
    if not next_link:
        start = int(time.time()) - LOOKBACK
        next_link = f"{BASE_URL}/api/v2/incremental/tickets/cursor.json?start_time={start}"
    pages = 0
    written = 0
    last_next = None
    while pages < MAX_PAGES and next_link:
        data = _http_get_json(next_link)
        _put_page(data, "incremental_tickets")
        written += len(data.get("tickets", []))
        links = data.get("links") or {}
        next_link = links.get("next")
        last_next = next_link
        pages += 1
    return {"resource": "incremental_tickets", "pages": pages, "written": written, "next": last_next}

def lambda_handler(event=None, context=None):
    state = _get_state()
    summary = []

    if "audit_logs" in RESOURCES:
        res = fetch_audit_logs(state.get("audit_logs", {}))
        state["audit_logs"] = {"next_url": res.get("next_url")}
        summary.append(res)

    if "incremental_tickets" in RESOURCES:
        res = fetch_incremental_tickets(state.get("incremental_tickets", {}))
        state["incremental_tickets"] = {"next": res.get("next")}
        summary.append(res)

    _put_state(state)
    return {"ok": True, "summary": summary}

if __name__ == "__main__":
    print(lambda_handler())

  5. Vai a Configurazione > Variabili di ambiente.

  6. Fai clic su Modifica > Aggiungi nuova variabile di ambiente.

  7. Inserisci le variabili di ambiente fornite nella tabella seguente, sostituendo i valori di esempio con i tuoi valori.

    Variabili di ambiente

    Chiave Valore di esempio
    S3_BUCKET zendesk-crm-logs
    S3_PREFIX zendesk/crm/
    STATE_KEY zendesk/crm/state.json
    ZENDESK_BASE_URL https://your_subdomain.zendesk.com
    AUTH_MODE token
    ZENDESK_EMAIL analyst@example.com
    ZENDESK_API_TOKEN <api_token>
    ZENDESK_BEARER_TOKEN <leave empty unless using OAuth bearer>
    RESOURCES audit_logs,incremental_tickets
    MAX_PAGES 20
    LOOKBACK_SECONDS 3600
    HTTP_TIMEOUT 60

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

  9. Seleziona la scheda Configurazione.

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

  11. Modifica Timeout impostando 5 minuti (300 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).
    • Target: la tua funzione Lambda zendesk_crm_to_s3.
    • Nome: zendesk_crm_to_s3-1h
  3. Fai clic su Crea pianificazione.

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

  1. Vai alla console AWS > IAM > Utenti > Aggiungi utenti.
  2. Fai clic su Add users (Aggiungi utenti).
  3. Fornisci i seguenti dettagli di configurazione:
    • Utente: inserisci secops-reader.
    • Tipo di accesso: seleziona Chiave di accesso - Accesso programmatico.
  4. Fai clic su Crea utente.
  5. Collega la criterio per la lettura minima (personalizzata): Utenti > secops-reader > Autorizzazioni > Aggiungi autorizzazioni > Collega le norme direttamente > Crea norma.

  6. JSON:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::zendesk-crm-logs/*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::zendesk-crm-logs"
    }
  ]
}

  7. Name = secops-reader-policy.

  8. Fai clic su Crea criterio > cerca/seleziona > Avanti > Aggiungi autorizzazioni.

  9. Crea la chiave di accesso per secops-reader: Credenziali di sicurezza > Chiavi di accesso.

  10. Fai clic su Crea chiave di accesso.

  11. Scarica il .CSV. Incollerai questi valori nel feed.

Configura un feed in Google SecOps per importare i log di Zendesk CRM

  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, Zendesk CRM logs).
  4. Seleziona Amazon S3 V2 come Tipo di origine.
  5. Seleziona Zendesk CRM come Tipo di log.
  6. Fai clic su Avanti.
  7. Specifica i valori per i seguenti parametri di input:
    • URI S3: s3://zendesk-crm-logs/zendesk/crm/
    • Opzioni di eliminazione dell'origine: seleziona l'opzione di eliminazione in base alle tue preferenze.
    • Età massima del file: includi i file modificati nell'ultimo numero di giorni. Il valore predefinito è 180 giorni.
    • 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: lo spazio dei nomi dell'asset.
    • Etichette di importazione: l'etichetta applicata 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.

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