Raccogli i log degli switch Ubiquiti Unifi

Supportata in:

Google SecOps SIEM

Questo documento spiega come importare i log degli switch Ubiquiti Unifi in Google Security Operations utilizzando Bindplane. Il parser estrae i campi dai messaggi syslog utilizzando i pattern grok, convertendo i dati di log non elaborati in un formato strutturato conforme al modello UDM (Unified Data Model). Gestisce vari formati di log, estrae informazioni chiave come timestamp, nomi host, descrizioni e dettagli di rete e arricchisce i dati con un contesto aggiuntivo prima di unirli all'evento UDM finale.

Prima di iniziare

Assicurati di soddisfare i seguenti prerequisiti:

• Un'istanza Google SecOps
• Un host Windows 2016 o versioni successive o Linux con systemd
• Se l'esecuzione avviene dietro un proxy, assicurati che le porte del firewall siano aperte in base ai requisiti dell'agente BindPlane
• Accesso con privilegi alla UI di Ubiquiti Controller

Ottieni le credenziali di Google SecOps per l'agente Bindplane

Per autenticare l'agente Bindplane in Google SecOps, scegli uno dei seguenti metodi:

• Nuovi deployment: utilizza l'API Chronicle (opzione 1).
• Deployment legacy: continua a utilizzare il file di autenticazione dell'acquisizione (opzione 2) fino alla dismissione dell'API Ingestion il 20 luglio 2027.

Opzione 1: crea un account di servizio per l'API Chronicle (consigliato)

1. Accedi alla consoleGoogle Cloud e seleziona il progetto Google Cloud collegato alla tua istanza di Google SecOps.
2. Vai a IAM e amministrazione > Service account.
3. Fai clic su Crea account di servizio.
4. Fornisci i seguenti dettagli di configurazione:
   • Nome account di servizio: inserisci un nome per l'account (ad esempio bindplane-ingest).
   • Descrizione service account: inserisci una descrizione (ad esempio, Bindplane agent log ingestion).
5. Fai clic su Crea e continua.
6. Nella sezione Concedi a questo account di servizio l'accesso al progetto, fai clic su Seleziona un ruolo e seleziona Chronicle Editor.
7. Fai clic su Continua e poi su Fine.
8. Fai clic sul account di servizio che hai creato, quindi vai alla scheda Chiavi.
9. Fai clic su Aggiungi chiave > Crea nuova chiave.
10. Seleziona JSON e fai clic su Crea. Il file della chiave viene scaricato sul computer.
11. Salva il file della chiave come ingestion-auth.json nella directory del raccoglitore Bindplane (/opt/observiq-otel-collector/ingestion-auth.json su Linux o C:\Program Files\observIQ OpenTelemetry Collector\ingestion-auth.json su Windows) o aggiorna creds_file_path in config.yaml in modo che corrisponda al percorso in cui lo salvi.
12. Vai a IAM e amministrazione > Impostazioni e copia il Numero progetto. Ti servirà per la configurazione dell'esportatore.

Nota: la chiave JSON è una credenziale. Limita l'accesso al file sull'host Bindplane e ruota la chiave in base alle policy della tua organizzazione.

Opzione 2: scarica il file di autenticazione dell'acquisizione (legacy)

1. Accedi alla console Google SecOps.
2. Vai a Impostazioni > Gestione dei dati > Agenti di raccolta. Se utilizzi una piattaforma solo SIEM, vai a Impostazioni > Agenti di raccolta.
3. Scarica il file di autenticazione dell'acquisizione.
4. Salva il file in modo sicuro sul sistema in cui verrà installato l'agente Bindplane.

Nota: questo file autentica l'agente nell'API Ingestion precedente (malachiteingestion-pa.googleapis.com), che Google ha programmato per la fine del ciclo di vita il 20 luglio 2027. Pianifica il passaggio all'Opzione 1 prima di questa data.

Ottieni l'ID cliente Google SecOps

1. Accedi alla console Google SecOps.
2. Vai a Impostazioni > Amministrazione > Profilo. Se utilizzi una piattaforma solo SIEM, vai a Impostazioni > Profilo.
3. Copia e salva l'ID cliente dalla sezione Dettagli organizzazione.

Installa l'agente Bindplane

Installa l'agente Bindplane sul tuo sistema operativo Windows o Linux seguendo le istruzioni riportate di seguito.

Installazione di finestre

1. Apri il prompt dei comandi o PowerShell come amministratore.

2. Esegui questo comando:

   msiexec /i "https://github.com/observIQ/bindplane-agent/releases/latest/download/observiq-otel-collector.msi" /quiet
   

Installazione di Linux

1. Apri un terminale con privilegi root o sudo.

2. Esegui questo comando:

   sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-agent/releases/latest/download/install_unix.sh)" install_unix.sh
   

Risorse aggiuntive per l'installazione

• Per ulteriori opzioni di installazione, consulta questa guida all'installazione.

Nota: la configurazione dell'esportatore dell'API Chronicle richiede Bindplane Collector v1.106.0 o versioni successive. I comandi precedenti installano l'ultima release. Se stai aggiornando un'installazione esistente, esegui l'upgrade del raccoglitore prima di modificare la configurazione.

Configura l'agente Bindplane per importare Syslog e inviarlo a Google SecOps

1. Accedi al file di configurazione:

   1. Individua il file config.yaml. In genere, si trova nella directory /opt/observiq-otel-collector/ su Linux o nella directory di installazione su Windows.
   2. Apri il file utilizzando un editor di testo (ad esempio nano, vi o Blocco note).

2. Modifica il file config.yaml come segue:

   receivers:
     udplog:
       # Replace the port and IP address as required
       listen_address: "0.0.0.0:514"
   
   exporters:
     chronicle/chronicle_w_labels:
       protocol: https
       # Region of your instance, for example us, europe, asia-southeast1
       location: <LOCATION>
       # Project number of the Google Cloud project linked to the instance
       project: '<PROJECT_NUMBER>'
       compression: gzip
       # Adjust the path to the credentials file you downloaded in Step 1
       creds_file_path: '/path/to/ingestion-authentication-file.json'
       # Replace with your actual customer ID from Step 2
       customer_id: <CUSTOMER_ID>
       endpoint: chronicle.googleapis.com
       # Add optional ingestion labels for better organization
       log_type: 'UBIQUITI_SWITCH'
       raw_log_field: body
       ingestion_labels:
   
   service:
     pipelines:
       logs/source0__chronicle_w_labels-0:
         receivers:
           - udplog
         exporters:
           - chronicle/chronicle_w_labels
   

   • Sostituisci la porta e l'indirizzo IP come richiesto nella tua infrastruttura.
   • Sostituisci <LOCATION> con la regione della tua istanza Google SecOps (ad esempio us, europe o asia-southeast1). L'esportatore antepone chronicle.googleapis.com a questo valore.
   • Sostituisci <PROJECT_NUMBER> con il numero di progetto indicato in IAM e amministrazione > Impostazioni.
   • Sostituisci <CUSTOMER_ID> con l'ID cliente effettivo.
   • Aggiorna /path/to/ingestion-authentication-file.json con il percorso in cui è stato salvato il file della chiave del account di servizio (Opzione 1) nella sezione Ottieni le credenziali di Google SecOps per l'agente Bindplane.

Esportatore API di importazione precedente

• Se utilizzi il file di autenticazione dell'acquisizione dell'Opzione 2, sostituisci il blocco exporters con il seguente. Imposta creds_file_path sul percorso del file di autenticazione dell'acquisizione e, se l'istanza si trova al di fuori degli Stati Uniti, sostituisci malachiteingestion-pa.googleapis.com con il tuo endpoint regionale (ad esempio, europe-malachiteingestion-pa.googleapis.com).

  exporters:
    chronicle/chronicle_w_labels:
      compression: gzip
      # Adjust the path to the credentials file you downloaded in Step 1
      creds_file_path: '/path/to/ingestion-authentication-file.json'
      # Replace with your actual customer ID from Step 2
      customer_id: <CUSTOMER_ID>
      endpoint: malachiteingestion-pa.googleapis.com
      # Add optional ingestion labels for better organization
      log_type: 'UBIQUITI_SWITCH'
      raw_log_field: body
      ingestion_labels:
  

Nota: questo strumento di esportazione smetterà di funzionare quando l'API Ingestion non sarà più disponibile il 20 luglio 2027.

Riavvia l'agente Bindplane per applicare le modifiche

• Per riavviare l'agente Bindplane in Linux, esegui questo comando:

  sudo systemctl restart observiq-otel-collector
  

• Per riavviare l'agente Bindplane in Windows, puoi utilizzare la console Servizi o inserire il seguente comando:

  net stop observiq-otel-collector && net start observiq-otel-collector
  

Configura lo switch Ubiquiti per l'invio del syslog del control plane

1. Accedi alla UI di Unifi Controller.
2. Apri Unifi Network.
3. Vai a Impostazioni > Control plane > scheda Integrazioni.
4. Trova la sezione Log delle attività (Syslog).
5. Attiva l'opzione Server SIEM.
6. Fornisci i seguenti dettagli di configurazione:
   • Fai clic su Modifica categorie e aggiungi le categorie di log richieste.
   • Indirizzo server: inserisci l'indirizzo IP dell'agente Bindplane.
   • Port (Porta): inserisci il numero di porta dell'agente Bindplane (è richiesto UDP).
7. Fai clic su Applica modifiche.

Configura lo switch Ubquiti per l'invio di Syslog CyberSecure

1. Accedi alla UI di Unifi Controller.
2. Apri Unifi Network.
3. Vai a Impostazioni > CyberSecure > scheda Registrazione del traffico.
4. Trova la sezione Log delle attività (Syslog).
5. Attiva l'opzione Server SIEM.
6. Fornisci i seguenti dettagli di configurazione:
   • Fai clic su Modifica categorie e aggiungi le categorie di log richieste.
   • Indirizzo server: inserisci l'indirizzo IP dell'agente Bindplane.
   • Port (Porta): inserisci il numero di porta dell'agente Bindplane (è richiesto UDP).
   • Disattiva Log di debug.
7. Fai clic su Applica modifiche.

Tabella di mappatura UDM

Campo del log	mappatura UDM	Logica
anomalies	security_result.detection_fields[].key: "anomalies" security_result.detection_fields[].value: valore anomalies dal log	Mappato direttamente dal campo anomalies nel log non elaborato.
application	observer.application	Mappato direttamente dal campo application nel log non elaborato.
assoc_status	security_result.detection_fields[].key: "assoc_status" security_result.detection_fields[].value: valore assoc_status dal log	Mappato direttamente dal campo assoc_status nel log non elaborato.
asset_details	observer.asset.product_object_id: estratto utilizzando il pattern grok %{GREEDYDATA:asset_id},%{GREEDYDATA:asset_version} asset_software.version: estratto utilizzando il pattern grok %{GREEDYDATA:asset_id},%{GREEDYDATA:asset_version}	Il campo asset_details viene analizzato utilizzando un pattern grok per estrarre asset_id e asset_version.
asset_id	observer.asset.product_object_id	Mappato direttamente dal campo asset_id estratto da asset_details.
asset_version	observer.asset.software.version	Mappato direttamente dal campo asset_version estratto da asset_details.
bssid	principal.mac	Mappato direttamente dal campo bssid nel log non elaborato.
description	metadata.description	Mappato direttamente dal campo description nel log non elaborato.
device	metadata.product_name	Mappato direttamente dal campo device nel log non elaborato. Se device non è presente, viene utilizzato il valore "UBIQUITI_SWITCH".
dns_resp_seen	security_result.detection_fields[].key: "dns_resp_seen" security_result.detection_fields[].value: valore dns_resp_seen dal log	Mappato direttamente dal campo dns_resp_seen nel log non elaborato.
DST	target.ip	Mappato direttamente dal campo DST nel log non elaborato.
DPT	principal.port	Mappato direttamente dal campo DPT nel log non elaborato dopo averlo convertito in un numero intero.
event_type	security_result.detection_fields[].key: "event_type" security_result.detection_fields[].value: valore event_type dal log	Mappato direttamente dal campo event_type nel log non elaborato.
host	principal.hostname	Mappato direttamente dal campo host nel log non elaborato.
ID	additional.fields[].key: "ID" additional.fields[].value.string_value: valore ID dal log	Mappato direttamente dal campo ID nel log non elaborato.
IN	additional.fields[].key: "IN" additional.fields[].value.string_value: valore IN del log	Mappato direttamente dal campo IN nel log non elaborato.
interface	additional.fields[].key: "interface" additional.fields[].value.string_value: valore interface dal log	Mappato direttamente dal campo interface nel log non elaborato.
LEN	additional.fields[].key: "LEN" additional.fields[].value.string_value: valore LEN del log	Mappato direttamente dal campo LEN nel log non elaborato.
mac	principal.mac	Mappato direttamente dal campo mac nel log non elaborato.
metadata.event_type	metadata.event_type	Derivato dalla logica del parser. Impostato su "STATUS_SHUTDOWN" se state è "Down", "STATUS_STARTUP" se state è "Up", "STATUS_UPDATE" se kv_msg e DST sono presenti o principal_present è true e "GENERIC_EVENT" in caso contrario.
metadata.log_type	metadata.log_type: "UBIQUITI_SWITCH"	Valore costante impostato dal parser.
metadata.vendor_name	metadata.vendor_name: "UBIQUITI"	Valore costante impostato dal parser.
principal_ip	principal.ip	Mappato direttamente dal campo principal_ip nel log non elaborato.
process_id	observer.process.pid	Mappato direttamente dal campo process_id nel log non elaborato.
product_event_type	metadata.product_event_type	Mappato direttamente dal campo product_event_type nel log non elaborato.
PROTO	network.ip_protocol	Mappato direttamente dal campo PROTO nel log non elaborato. Se PROTO è "ICMPv6", il valore viene modificato in "ICMP".
query_1	target.administrative_domain	Mappato direttamente dal campo query_1 nel log non elaborato.
query_server_1	target.ip	Mappato direttamente dal campo query_server_1 nel log non elaborato.
radio	security_result.detection_fields[].key: "radio" security_result.detection_fields[].value: valore radio dal log	Mappato direttamente dal campo radio nel log non elaborato.
satisfaction_now	security_result.detection_fields[].key: "satisfaction_now" security_result.detection_fields[].value: valore satisfaction_now del log	Mappato direttamente dal campo satisfaction_now nel log non elaborato.
source_port	principal.port	Mappato direttamente dal campo source_port nel log non elaborato dopo averlo convertito in un numero intero.
SPT	target.port	Mappato direttamente dal campo SPT nel log non elaborato dopo averlo convertito in un numero intero.
SRC	principal.ip, principal.hostname	Mappato direttamente dal campo SRC nel log non elaborato.
sta	principal.mac	Mappato direttamente dal campo sta nel log non elaborato.
state	additional.fields[].key: "state" additional.fields[].value.string_value: valore state dal log	Mappato direttamente dal campo state nel log non elaborato.
timestamp	metadata.event_timestamp	Mappato direttamente dal campo timestamp nel log non elaborato dopo l'analisi da parte del filtro della data.
TTL	additional.fields[].key: "TTL" additional.fields[].value.string_value: valore TTL dal log	Mappato direttamente dal campo TTL nel log non elaborato.
vap	metadata.ingestion_labels[].key: "Vap" metadata.ingestion_labels[].value: valore vap dal log	Mappato direttamente dal campo vap nel log non elaborato.
version	metadata.product_version	Mappato direttamente dal campo version nel log non elaborato.

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.