Raccogli i log degli avvisi di Netskope

Supportata in:

Questo documento spiega come importare i log degli avvisi di Netskope in Google Security Operations utilizzando Google Cloud Storage V2. Netskope è una piattaforma di sicurezza cloud che fornisce protezione dei dati e dalle minacce in tempo reale per servizi cloud, siti web e applicazioni private. Gli avvisi di Netskope acquisiscono eventi di sicurezza, tra cui violazioni DLP, rilevamenti di malware, comportamenti anomali, credenziali compromesse e violazioni delle policy nel traffico SaaS, IaaS e web.

Per saperne di più, consulta Raccogli i log degli avvisi di Netskope.

Prima di iniziare

Assicurati di soddisfare i seguenti prerequisiti:

  • Un'istanza Google SecOps.
  • Un progetto GCP con l'API Storage di Cloud Storage abilitata.
  • Autorizzazioni per creare e gestire bucket GCS e policy IAM.
  • Autorizzazioni per creare servizi Cloud Run, argomenti Pub/Sub e job Cloud Scheduler.
  • Accesso con privilegi alla console di amministrazione del tenant Netskope.
  • Un token API REST Netskope v2 con autorizzazione in lettura per gli avvisi.

Raccogli le credenziali dell'API Netskope v2

Crea un token API REST v2

  1. Accedi alla Console di amministrazione del tenant Netskope (ad esempio, https://your-tenant.goskope.com).
  2. Vai a Impostazioni > Strumenti > API REST v2.
  3. Fai clic su New Token (Nuovo token).
  4. Fornisci i seguenti dettagli di configurazione:
    • Nome token: inserisci un nome descrittivo (ad esempio SecOps-Alert-Integration).
    • Scadenza: imposta la data di scadenza del token in base alle tue norme di sicurezza.
  5. In Endpoint, attiva quanto segue:
    • /api/v2/events/data/alert: autorizzazione in lettura.
  6. Fai clic su Salva.
  7. Copia e salva il valore del token in modo sicuro. Il token viene visualizzato una sola volta.

Verifica l'accesso all'API

  • Testa le tue credenziali prima di procedere con l'integrazione:

    NETSKOPE_TENANT="[https://your-tenant.goskope.com](https://your-tenant.goskope.com)"
    API_TOKEN="your-api-v2-token"
    
    curl -v -H "Netskope-Api-Token: ${API_TOKEN}" \
        "${NETSKOPE_TENANT}/api/v2/events/data/alert?limit=1"
    

Crea un bucket Google Cloud Storage

  1. Vai alla console Google Cloud.
  2. Seleziona il tuo progetto o creane uno nuovo.
  3. Nel menu di navigazione, vai a Cloud Storage > Bucket.
  4. Fai clic su Crea bucket.
  5. Fornisci i seguenti dettagli di configurazione:

    Impostazione Valore
    Assegna un nome al bucket Inserisci un nome globalmente univoco (ad esempio netskope-alerts-logs)
    Tipo di località Scegli in base alle tue esigenze (Regione, a due regioni, multiregionale)
    Località Seleziona la località più vicina alla tua istanza Google SecOps
    Classe di archiviazione Standard (consigliato per i log ad accesso frequente)
    Controllo degli accessi Uniforme (consigliata)
  6. Fai clic su Crea.

Crea un account di servizio per la funzione Cloud Run

La funzione Cloud Run richiede un account di servizio con le autorizzazioni per scrivere nel bucket GCS ed essere richiamata da Pub/Sub.

Crea service account

  1. Nella console GCP, vai a IAM e amministrazione > service account.
  2. Fai clic su Crea account di servizio.
  3. Fornisci i seguenti dettagli di configurazione:
    • Nome del service account: netskope-alerts-collector-sa.
    • Descrizione service account: Service account for Cloud Run function to collect Netskope Alerts logs.
  4. Fai clic su Crea e continua.
  5. Nella sezione Concedi a questo account di servizio l'accesso al progetto, aggiungi i seguenti ruoli:
    1. Storage Object Admin
    2. Cloud Run Invoker
    3. Cloud Functions Invoker
  6. Fai clic su Continua, quindi su Fine.

Concedi le autorizzazioni IAM sul bucket GCS

  1. Vai a Cloud Storage > Bucket.
  2. Fai clic sul bucket netskope-alerts-logs.
  3. Vai alla scheda Autorizzazioni.
  4. Fai clic su Concedi l'accesso.
  5. Fornisci i seguenti dettagli di configurazione:
    • Aggiungi entità: inserisci l'indirizzo email del account di servizio (ad esempio netskope-alerts-collector-sa@PROJECT_ID.iam.gserviceaccount.com).
    • Assegna i ruoli: seleziona Storage Object Admin.
  6. Fai clic su Salva.

Crea argomento Pub/Sub

Crea un argomento Pub/Sub in cui Cloud Scheduler pubblicherà e a cui la funzione Cloud Run si iscriverà.

  1. Nella console Google Cloud, vai a Pub/Sub > Argomenti.
  2. Fai clic su Crea argomento.
  3. Fornisci i seguenti dettagli di configurazione:
    • ID argomento: netskope-alerts-trigger.
    • Lascia invariate le altre impostazioni predefinite.
  4. Fai clic su Crea.

Crea una funzione Cloud Run per raccogliere i log

La funzione Cloud Run verrà attivata dai messaggi Pub/Sub di Cloud Scheduler per recuperare gli avvisi dall'API REST Netskope v2 e scriverli in GCS.

  1. Nella console Google Cloud, vai a Cloud Run.
  2. Fai clic su Crea servizio.
  3. Seleziona Funzione.
  4. Nella sezione Configura, fornisci i seguenti dettagli di configurazione:

    Impostazione Valore
    Nome servizio netskope-alerts-collector
    Regione Seleziona la regione corrispondente al tuo bucket GCS (ad esempio, us-central1)
    Tempo di esecuzione Python 3.12 o versioni successive
  5. Nella sezione Trigger:

    1. Fai clic su + Aggiungi trigger.
    2. Seleziona Cloud Pub/Sub.
    3. In Seleziona un argomento Cloud Pub/Sub, scegli netskope-alerts-trigger.
    4. Fai clic su Salva.
  6. Nella sezione Autenticazione, seleziona Richiedi autenticazione e seleziona Identity and Access Management (IAM).

  7. Scorri verso il basso fino a Container, networking, sicurezza.

  8. Nella scheda Sicurezza, seleziona il account di servizio netskope-alerts-collector-sa.

  9. Nella scheda Container, fai clic su Variabili e secret e aggiungi quanto segue:

    Nome variabile Valore di esempio Descrizione
    GCS_BUCKET netskope-alerts-logs Nome bucket GCS
    GCS_PREFIX netskope/alerts Prefisso per i file di log
    STATE_KEY netskope/alerts/state.json Percorso del file di stato
    NETSKOPE_TENANT https://your-tenant.goskope.com URL tenant Netskope
    NETSKOPE_API_TOKEN your-api-v2-token Token API REST v2
    MAX_RECORDS 5000 Numero massimo di record per esecuzione
    PAGE_SIZE 1000 Record per pagina
    LOOKBACK_HOURS 24 Periodo di riferimento iniziale
  10. Nella sezione Richieste, imposta Timeout richiesta su 600 secondi.

  11. Nella scheda Impostazioni (Risorse), seleziona 512 MiB di memoria e 1 CPU.

  12. Fai clic su Crea. Dopo aver creato il servizio, l'editor di codice incorporato si aprirà automaticamente.

Aggiungi codice per la funzione

  1. Inserisci main nel campo Punto di ingresso.
  2. Nell'editor di codice incorporato, crea due file:

    • main.py:
    import functions_framework
    from google.cloud import storage
    import json
    import os
    import urllib3
    from datetime import datetime, timezone, timedelta
    import time
    
    http = urllib3.PoolManager(
        timeout=urllib3.Timeout(connect=5.0, read=30.0),
        retries=False,
    )
    
    storage_client = storage.Client()
    
    GCS_BUCKET = os.environ.get('GCS_BUCKET')
    GCS_PREFIX = os.environ.get('GCS_PREFIX', 'netskope/alerts')
    STATE_KEY = os.environ.get('STATE_KEY', 'netskope/alerts/state.json')
    NETSKOPE_TENANT = os.environ.get('NETSKOPE_TENANT')
    NETSKOPE_API_TOKEN = os.environ.get('NETSKOPE_API_TOKEN')
    MAX_RECORDS = int(os.environ.get('MAX_RECORDS', '5000'))
    PAGE_SIZE = int(os.environ.get('PAGE_SIZE', '1000'))
    LOOKBACK_HOURS = int(os.environ.get('LOOKBACK_HOURS', '24'))
    
    def to_epoch_seconds(dt):
        if dt.tzinfo is None:
            dt = dt.replace(tzinfo=timezone.utc)
        return int(dt.timestamp())
    
    def parse_datetime(value):
        if isinstance(value, (int, float)):
            return datetime.fromtimestamp(value, tz=timezone.utc)
        if isinstance(value, str):
            if value.endswith("Z"):
                value = value[:-1] + "+00:00"
            return datetime.fromisoformat(value)
        return None
    
    @functions_framework.cloud_event
    def main(cloud_event):
        if not all([GCS_BUCKET, NETSKOPE_TENANT, NETSKOPE_API_TOKEN]):
            print('Error: Missing required environment variables')
            return
    
        try:
            bucket = storage_client.bucket(GCS_BUCKET)
            state = load_state(bucket, STATE_KEY)
    
            now = datetime.now(timezone.utc)
            last_time = None
    
            if isinstance(state, dict) and state.get("last_event_time"):
                try:
                    last_time = parse_datetime(state["last_event_time"])
                    last_time = last_time - timedelta(minutes=2)
                except Exception as e:
                    print(f"Warning: Could not parse last_event_time: {e}")
    
            if last_time is None:
                last_time = now - timedelta(hours=LOOKBACK_HOURS)
    
            print(f"Fetching alerts from {last_time.isoformat()} to {now.isoformat()}")
    
            records, newest_event_time = fetch_alerts(
                tenant=NETSKOPE_TENANT,
                token=NETSKOPE_API_TOKEN,
                start_time=last_time,
                end_time=now,
                page_size=PAGE_SIZE,
                max_records=MAX_RECORDS,
            )
    
            if not records:
                print("No new alert records found.")
                save_state(bucket, STATE_KEY, to_epoch_seconds(now))
                return
    
            timestamp = now.strftime('%Y%m%d_%H%M%S')
            object_key = f"{GCS_PREFIX}/alerts_{timestamp}.ndjson"
            blob = bucket.blob(object_key)
    
            ndjson = '\n'.join([json.dumps(r, ensure_ascii=False) for r in records]) + '\n'
            blob.upload_from_string(ndjson, content_type='application/x-ndjson')
    
            print(f"Wrote {len(records)} records to gs://{GCS_BUCKET}/{object_key}")
    
            if newest_event_time:
                save_state(bucket, STATE_KEY, newest_event_time)
            else:
                save_state(bucket, STATE_KEY, to_epoch_seconds(now))
    
            print(f"Successfully processed {len(records)} records")
    
        except Exception as e:
            print(f'Error processing alerts: {str(e)}')
            raise
    
    def load_state(bucket, key):
        try:
            blob = bucket.blob(key)
            if blob.exists():
                state_data = blob.download_as_text()
                return json.loads(state_data)
        except Exception as e:
            print(f"Warning: Could not load state: {e}")
        return {}
    
    def save_state(bucket, key, last_event_time):
        try:
            state = {'last_event_time': last_event_time}
            blob = bucket.blob(key)
            blob.upload_from_string(
                json.dumps(state, indent=2),
                content_type='application/json'
            )
            print(f"Saved state: last_event_time={last_event_time}")
        except Exception as e:
            print(f"Warning: Could not save state: {e}")
    
    def fetch_alerts(tenant, token, start_time, end_time, page_size, max_records):
        base_url = tenant.rstrip('/')
        endpoint = f"{base_url}/api/v2/events/data/alert"
    
        headers = {
            'Netskope-Api-Token': token,
            'Accept': 'application/json',
            'User-Agent': 'GoogleSecOps-NetskopeAlertCollector/1.0'
        }
    
        records = []
        newest_time = None
        page_num = 0
        backoff = 1.0
    
        start_epoch = to_epoch_seconds(start_time)
        end_epoch = to_epoch_seconds(end_time)
        operation_id = None
    
        url = f"{endpoint}?limit={page_size}&starttime={start_epoch}&endtime={end_epoch}"
    
        while True:
            page_num += 1
    
            if len(records) >= max_records:
                print(f"Reached max_records limit ({max_records})")
                break
    
            if operation_id:
                url = f"{endpoint}?limit={page_size}&operation={operation_id}"
    
            try:
                response = http.request('GET', url, headers=headers)
    
                if response.status == 429:
                    retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
                    print(f"Rate limited (429). Retrying after {retry_after}s...")
                    time.sleep(retry_after)
                    backoff = min(backoff * 2, 30.0)
                    continue
    
                backoff = 1.0
    
                if response.status != 200:
                    print(f"HTTP Error: {response.status}")
                    response_text = response.data.decode('utf-8')
                    print(f"Response body: {response_text}")
                    return [], None
    
                data = json.loads(response.data.decode('utf-8'))
                page_results = data.get('result', [])
    
                if not page_results:
                    print("No more results (empty page)")
                    break
    
                print(f"Page {page_num}: Retrieved {len(page_results)} alerts")
                records.extend(page_results)
    
                for event in page_results:
                    try:
                        event_time = event.get('timestamp')
                        if event_time:
                            if newest_time is None or event_time > newest_time:
                                newest_time = event_time
                    except Exception as e:
                        print(f"Warning: Could not parse event time: {e}")
    
                wait_time = data.get('wait_time')
                operation_id = data.get('operation')
    
                if not operation_id or len(page_results) < page_size:
                    break
    
                if wait_time and wait_time > 0:
                    time.sleep(wait_time)
    
            except Exception as e:
                print(f"Error fetching alerts: {e}")
                return [], None
    
        print(f"Retrieved {len(records)} total records from {page_num} pages")
        return records, newest_time
    
    • requirements.txt:
    functions-framework==3.*
    google-cloud-storage==2.*
    urllib3>=2.0.0
    
  3. Fai clic su Esegui il deployment per salvare la funzione ed eseguirne il deployment.

Crea job Cloud Scheduler

  1. Nella console Google Cloud, vai a Cloud Scheduler.
  2. Fai clic su Crea job.
  3. Fornisci i seguenti dettagli di configurazione:

    Impostazione Valore
    Nome netskope-alerts-collector-hourly
    Regione Seleziona la stessa regione della funzione Cloud Run
    Frequenza 0 * * * * (ogni ora, allo scoccare dell'ora)
    Fuso orario Seleziona il fuso orario (consigliato UTC)
    Tipo di target Pub/Sub
    Argomento Seleziona netskope-alerts-trigger
    Corpo del messaggio {}
  4. Fai clic su Crea.

Configura un feed in Google SecOps

  1. Vai a Impostazioni > Gestione dei dati > Feed. Se utilizzi una piattaforma solo SIEM, vai a Impostazioni > Feed.
  2. Fai clic su Aggiungi nuovo feed > Configura un singolo feed.
  3. Nome del feed: Netskope Alerts.
  4. Tipo di origine: Google Cloud Storage V2.
  5. Tipo di log: Netskope Alert.
  6. Fai clic su Ottieni service account e copia l'indirizzo email fornito.
  7. Fai clic su Avanti.
  8. URL del bucket di archiviazione: gs://netskope-alerts-logs/netskope/alerts/ (includi la barra finale).
  9. Opzione di eliminazione dell'origine: seleziona l'opzione che preferisci (ad es. Mai per i test).
  10. Fai clic su Avanti, rivedi e fai clic su Invia.

Concedi le autorizzazioni IAM al account di servizio Google SecOps

  1. Vai a Cloud Storage > Bucket.
  2. Fai clic su netskope-alerts-logs.
  3. Vai alla scheda Autorizzazioni.
  4. Fai clic su Concedi l'accesso.
  5. Aggiungi entità: incolla l'indirizzo email del account di servizio Google SecOps.
  6. Assegna ruoli: seleziona Visualizzatore oggetti Storage. (Utilizza Storage Object Admin se utilizzi un'opzione di eliminazione nel feed).
  7. Fai clic su Salva.

Tabella di mappatura UDM

Campo log Mappatura UDM Logica
app_activity_label additional.fields Unita
count_label additional.fields Unita
object_field additional.fields Unita
object_id_field additional.fields Unita
object_type_field additional.fields Unita
publisher_cn_field additional.fields Unita
publisher_name_field additional.fields Unita
site_label additional.fields Unita
tunnel_id_field additional.fields Unita
tunnel_type_field additional.fields Unita
access_method extensions.auth.auth_details Mappatura diretta
accessmethod extensions.auth.auth_details Mappato quando result != ``
activity extensions.auth.type Mapped: Login Failed → MACHINE, Login Successful → MACHINE, Login Attempt → MACHINE
published metadata.event_timestamp Analizzato come RFC 3339
timestamp metadata.event_timestamp Analizzato come RFC 3339
Protocol metadata.event_type Mappatura: HTTP → NETWORK_HTTP
activity metadata.event_type Mapped: Introspection Scan → EMAIL_UNCATEGORIZED, Login Failed → USER_LOGIN, `Login …
has_principal metadata.event_type Mappatura: true → NETWORK_HTTP, true → NETWORK_CONNECTION
Id metadata.product_log_id Mappato quando result != ``
_id metadata.product_log_id Mappatura diretta
protocol network.application_protocol Rinominato/mappato
from_user network.email.from Mappatura diretta
useridemail network.email.to Mappatura: @ → useridemail
user_agent network.http.parsed_user_agent Rinominato/mappato
useragent network.http.parsed_user_agent Rinominato/mappato
browser_version network.http.parsed_user_agent.browser_version Mappatura diretta
browserversion network.http.parsed_user_agent.browser_version Mappato quando result != ``
page network.http.referral_url Mappatura diretta
referer network.http.referral_url Rinominato/mappato
Browser network.http.user_agent Mappato quando result != ``
browser network.http.user_agent Mappatura diretta
user_agent network.http.user_agent Mappatura diretta
useragent network.http.user_agent Mappatura diretta
ip_protocol_out network.ip_protocol Mappatura diretta
server_bytes network.received_bytes Rinominato/mappato
client_bytes network.sent_bytes Rinominato/mappato
browserSessionid network.session_id Mappato quando result != ``
browser_sess network.session_id Rinominato/mappato
network_session_id network.session_id Rinominato/mappato
ja3 network.tls.client.ja3 Mappatura diretta
ja3s network.tls.server.ja3s Mappatura diretta
netskope_pop observer.hostname Mappatura diretta
organization_unit principal.administrative_domain Mappatura diretta
Host principal.asset.hostname Mappato quando result != ``
hostname principal.asset.hostname Mappatura diretta
instance_id principal.asset.hostname Mappatura diretta
srcIP principal.asset.ip Unita
srcip principal.asset.ip Unita
Host principal.hostname Mappato quando result != ``
hostname principal.hostname Mappatura diretta
instance_id principal.hostname Mappatura diretta
srcIP principal.ip Unita
srcip principal.ip Unita
src_location principal.location.city Rinominato/mappato
src_country principal.location.country_or_region Rinominato/mappato
srccountry principal.location.country_or_region Mappato quando result != ``
src_region principal.location.name Rinominato/mappato
srcregion principal.location.name Mappato quando result != ``
srclatitude principal.location.region_coordinates.latitude Rinominato/mappato
srclongitude principal.location.region_coordinates.longitude Rinominato/mappato
src_latitude principal.location.region_latitude Rinominato/mappato
src_longitude principal.location.region_longitude Rinominato/mappato
os principal.platform Mapped: (?i)Windows → WINDOWS, (?i)MAC → MAC, (?i)LINUX → LINUX
os_version principal.platform_version Rinominato/mappato
osversion principal.platform_version Mappato quando result != ``
srcport principal.port Rinominato/mappato
from_user_category_label principal.resource.attribute.labels Unita
Device principal.resource.resource_subtype Mappato quando result != ``
device principal.resource.resource_subtype Mappatura diretta
User principal.user.email_addresses Unita
matched_username principal.user.email_addresses Unita
user principal.user.email_addresses Unita
user principal.user.userid Rinominato/mappato
_security_result security_result Unita
security_result1 security_result Unita
app target.application Rinominato/mappato
appName target.application Mappato quando result != ``
domain target.asset.hostname Mappatura diretta
dstIP target.asset.ip Unita
dst_ip target.asset.ip Unita
dstip target.asset.ip Unita
dlp_file target.file.full_path Mappatura diretta
file_path target.file.full_path Mappatura diretta
md5 target.file.md5 Rinominato/mappato
file_type target.file.mime_type Mappatura diretta
sha256 target.file.sha256 Rinominato/mappato
file_size target.file.size Rinominato/mappato
domain target.hostname Mappatura diretta
dstIP target.ip Unita
dst_ip target.ip Unita
dstip target.ip Unita
dst_location target.location.city Rinominato/mappato
dst_country target.location.country_or_region Rinominato/mappato
dstcountry target.location.country_or_region Mappato quando result != ``
dst_region target.location.name Rinominato/mappato
dstregion target.location.name Mappato quando result != ``
dstlatitude target.location.region_coordinates.latitude Rinominato/mappato
dstlongitude target.location.region_coordinates.longitude Rinominato/mappato
dstport target.port Rinominato/mappato
app_session_label target.resource.attribute.labels Unita
to_user_category_label target.resource.attribute.labels Unita
Url target.url Mappato quando result != ``
url target.url Rinominato/mappato
to_user target.user.email_addresses Mappatura: ^.+@.+$ → touser
touser target.user.email_addresses Mappatura: ^.+@.+$ → touser
N/D extensions.auth.type Costante: MACHINE
N/D metadata.event_type Costante: GENERIC_EVENT
N/D metadata.product_name Costante: Netskope Alert
N/D metadata.vendor_name Costante: Netskope
N/D network.http.parsed_user_agent.family Costante: USER_DEFINED
N/D principal.platform Costante: WINDOWS
N/D principal.resource.type Costante: DEVICE
N/D target.asset.hostname Costante: dsthost
N/D target.hostname Costante: dsthost
action security_result.action_details Mappato dal log delle modifiche
dlp_rule_severity security_result.severity Mappato dal log delle modifiche
useragent" and "user_agent network.http.user_agent Mappato dal log delle modifiche
traffic_type security_result.detection_fields Mappato dal log delle modifiche
device principal.resource.resource_sub_type Mappato dal log delle modifiche
type security_result.detection_fields Mappato dal log delle modifiche
app_session_id target.resource.attribute.labels Mappato dal log delle modifiche
malware_severity security_result.severity Mappato dal log delle modifiche
malware_type security_result.detection_fields Mappato dal log delle modifiche
threat_match_field security_result.detection_fields Mappato dal log delle modifiche
cci", "ccl additional.fields Mappato dal log delle modifiche
dlp_profile security_result.rule_type Mappato dal log delle modifiche
dlp_rule security_result.rule_name Mappato dal log delle modifiche
security_result.alert_state ALERTING Mappato dal log delle modifiche
security_result.alert_state NOT_ALERTING Mappato dal log delle modifiche
security_result.alert_state UNSPECIFIED Mappato dal log delle modifiche

Log delle modifiche

Visualizza il log delle modifiche per questo parser

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