Guida introduttiva: YARA-L 2.0 in SecOps

Supportato in:

YARA-L 2.0 è il linguaggio di query unico e altamente strutturato che alimenta Google Security Operations per tutte le ricerche, le dashboard e il rilevamento delle minacce basato su regole. Questo documento ti aiuta a comprendere la struttura principale di YARA-L e fornisce passaggi pratici per utilizzarlo, che tu sia un analista della sicurezza alla ricerca di minacce o un ingegnere del rilevamento che crea una nuova logica solida.

Prima di iniziare

Comprendere la struttura di YARA-L

Ogni query YARA-L è suddivisa in sezioni distinte e denominate, che determinano il comportamento della query.

Questa struttura consente l'analisi e la correlazione in più fasi.

Comando Azione Facoltativo | Obbligatorio
meta Imposta metadati descrittivi per la regola, come autore, descrizione e gravità. Facoltativo per la ricerca e le dashboard. Obbligatorio solo per le regole.
events Definisce e filtra gli eventi. Dichiara tutte le origini dati (principalmente eventi) da considerare e le filtra utilizzando i campi UDM. Obbligatorio (logica principale della query) per la ricerca, i dashboard e le regole.
match Raggruppa per eventi e consente di specificare la finestra temporale supportata (ad esempio, by 5m). Obbligatorio in alcuni casi per le ricerche statistiche in cui si verifica l'aggregazione. Obbligatorio per le query di correlazione di più eventi. La specifica dell'ora è obbligatoria in match per le regole e facoltativa per la ricerca e le dashboard.
outcome Calcola le metriche essenziali e ottiene insight (ad esempio count(), avg()). Facoltativo.
condition Definisce la logica che deve essere soddisfatta per restituire risultati (nella ricerca) o attivare un avviso (in una regola). Valuta i criteri delle variabili di query per determinare se un risultato è applicabile (ad esempio, $event >5). Facoltativo nella ricerca e nelle dashboard. Obbligatorio solo per le regole.
dedup Rimuove gli eventi duplicati raggruppandoli in base a variabili chiave o percorsi degli eventi (ad esempio target.user.userid, target.ip, principal.hostname o variabili come $host, $user). Scopri di più sulle variabili evento. Facoltativo. Non disponibile nelle regole.
order Ordina i risultati definiti da campi specifici (ad esempio, asc). Facoltativo (applicabile solo se utilizzi match). Non disponibile nelle regole.
limit Limita il numero massimo di eventi restituiti dalla query. Facoltativo. Non disponibile nelle regole.
select Specifica l'elenco dei campi UDM da includere nei risultati della query. Facoltativo. Non disponibile nelle regole.
unselect Specifica l'elenco dei campi UDM da escludere dai risultati della query. Facoltativo. Non disponibile nelle regole.

Disponibilità delle origini dati YARA-L

YARA-L ha accesso a diverse origini dati, a seconda della posizione in cui ti trovi nella piattaforma. Eventi, entità (ECG) e tabelle di dati sono completamente disponibili in ricerche, dashboard e regole.

La tabella seguente elenca le funzionalità disponibili in YARA-L:

Funzionalità Disponibile in
Richieste e cronologia delle richieste Dashboard
Tabelle dati Ricerca, dashboard, regole
Entità (ECG) Ricerca, dashboard, regole
Metriche di importazione Dashboard
Corrispondenze IoC Dashboard
Rilevamenti delle regole Dashboard, regole
Set di regole Dashboard
Eventi Ricerca, dashboard, regole
Metriche UEBA Cerca, dashboard

Tutti i dati in Google SecOps vengono cercati utilizzando due metodi principali in base ai tuoi obiettivi: ricerca con filtri e ricerca statistica (aggregazioni).

Il metodo di ricerca dei filtri ti consente di isolare eventi specifici dal flusso di telemetria più ampio senza il sovraccarico dell'aggregazione statistica. Questo metodo utilizza criteri per restringere enormi volumi di dati di sicurezza, come log o traffico di rete, in un insieme di risultati mirato. La logica richiede solo di specificare gli eventi nella sezione events.

Per creare la prima ricerca con filtro YARA-L, segui questi passaggi per cercare gli utenti con accessi non riusciti:

  1. In Google SecOps, vai alla pagina Ricerca.
  2. Filtra gli eventi di accesso:
    metadata.event_type = "USER_LOGIN"

    Suggerimento: puoi omettere l'intestazione della sezione events: nelle tue ricerche. Per impostazione predefinita, la sintassi di ricerca implica questa sezione.

  3. Aggiungi event azioni per gli accessi non riusciti da parte di utenti che non hanno un userid vuoto. 
    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
  4. Esegui questa ricerca per visualizzare i risultati.

Utilizzare le variabili segnaposto

Utilizza le variabili segnaposto per estrarre valori specifici dagli eventi, ad esempio un nome utente o un indirizzo IP. Queste variabili fungono da ancore temporanee che ti consentono di confrontare i dati tra diversi eventi o di visualizzare questi valori nell'output finale.

Applica le variabili segnaposto per:

  • Dati ponte: utilizza segnaposto come $userid o $ip per trovare corrispondenze tra diverse variabili evento (ad esempio, puoi utilizzare $userid per collegare l'identificatore utente tra gli eventi di accesso e disconnessione).
  • Risultati del gruppo: nella sezione match, utilizza le variabili segnaposto per definire la finestra dell'output della query, ad esempio match: $userid over 1h.
  • Crea risultati: utilizza i segnaposto per acquisire e visualizzare punti dati specifici nell'output della query.

Ad esempio, se assegni $user = principal.user.userid, la variabile $user ora contiene il valore specifico estratto dall'evento. Quindi, utilizzi $user nella sezione match per raggruppare tutte le attività correlate a quell'utente specifico.

Il metodo di ricerca statistica ti aiuta a ottenere approfondimenti, tendenze o anomalie eseguendo calcoli su insiemi di eventi. Anziché restituire un elenco di singoli log, fornisce riepiloghi aggregati dei dati. La logica utilizza la sezione match (per il raggruppamento) e la sezione outcome (per i calcoli). La sezione outcome supporta le funzioni di aggregazione, come count(), sum(), avg(), max(), min() e stddev().

L'esempio seguente utilizza la seguente logica di query:

  • events: filtra i dati non elaborati per i tentativi di accesso non riusciti.
  • match: definisce gli eventi di raggruppamento (per userid).
  • outcome: esegue l'aggregazione statistica (conteggio eventi per utente).

Esempio: aggregare l'attività di accesso non riuscito utilizzando le funzioni outcome

L'esempio seguente utilizza le funzioni di aggregazione della sezione outcome (come count() o sum()) per riepilogare l'attività di accesso non riuscito.

  1. Utilizza la sezione match per raggruppare gli eventi di accesso non riuscito per userid:

    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""

match:
  principal.user.userid

  2. Utilizza il count di tentativi di accesso non riusciti per ogni utente ($failed_login_count), definito dalla variabile outcome:

    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""

match:
  principal.$user.userid

outcome:
  $failed_login_count = count(metadata.id)

  3. Esegui questa ricerca per visualizzare i risultati.

  4. (Facoltativo) Aggiungi un elemento temporale alla sezione match (in questo caso, day). Poi, aggiorna la variabile outcome in modo che sia più esplicita ($daily_failed_login_count):

    metadata.event_type = "USER_LOGIN"
security_result.action = "FAIL"
principal.user.userid != ""
$user =principal.user.userid

match:
  principal.$user.userid by day

outcome:
  $daily_failed_login_count = count(metadata.id)

Creare un widget della dashboard dalla ricerca

Puoi creare un widget della dashboard dalle ricerche aggregate, come mostrato nell'esempio di creazione della prima ricerca.

Una volta convalidata la ricerca, puoi salvarla come widget e aggiungerla alla dashboard nel seguente modo:

  1. Quando visualizzi i risultati, fai clic sulla scheda Visualizza > Aggiungi alla dashboard.
  2. Configura il widget:
    1. Assegna un nome al widget (ad esempio, "Daily Failed Login").
    2. Seleziona un intervallo di tempo.
    3. Scegli se aggiungerlo a una dashboard esistente o nuova.
    4. Fai clic su Aggiungi.
  3. (Facoltativo) Crea query direttamente nelle dashboard. In alternativa, puoi copiare le dashboard curate e modificare le query al loro interno come punto di partenza.
  4. (Facoltativo) Puoi creare una dashboard personalizzata e aggiungervi widget utilizzando YARA-L. Per maggiori dettagli, vedi Creare una dashboard personalizzata.

Configura una dashboard

Quando crei una nuova dashboard, la sezione events è un punto di partenza obbligatorio. Da qui, puoi utilizzare match (per raggruppare i risultati) o outcome (per calcolare output e aggregazioni).

Ad esempio, puoi avere una dashboard con sezioni events e match, in cui la dashboard mostra la gravità ($severity) dei rilevamenti raggruppati in bucket by hour.

Esempio: aggregare le serie temporali per gravità

Puoi creare una dashboard utilizzando le sezioni events e match per visualizzare la gravità ($severity) dei rilevamenti raggruppati in bucket hour:

detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

Esempio: aggregare l'impatto critico totale

Allo stesso modo, puoi creare una dashboard utilizzando le sezioni events e outcome per monitorare i rilevamenti di gravità elevata:

detection.detection.severity = "CRITICAL"
$severity = detection.detection.severity

outcome:
  $detection_count = count_distinct($severity)

Esempio: visualizzare il volume di rilevamento per gravità nel tempo

Nell'esempio seguente, puoi contare i rilevamenti critici e specificare l'intervallo di tempo tramite la console. In molti casi, utilizzerai sia le sezioni match che outcome quando crei una visualizzazione in una dashboard:

detection.detection.severity != "UNKNOWN_SEVERITY"
$severity = detection.detection.severity

match:
  $severity by hour

outcome:
  $detection_count = count_distinct(detection.id)

Esempio: calcola la frequenza di accesso degli utenti

L'esempio seguente si concentra sul calcolo del login_count per utenti specifici utilizzando le sezioni match e outcome:

events:
  metadata.event_type = "USER_LOGIN"

match:
  target.user.userid

outcome:
  $login_count = count(metadata.id)

Creare una regola

Una regola richiede le seguenti sezioni:

  • meta: contiene il nome della regola e i dettagli descrittivi.
  • events: definisce le origini dati e i filtri utilizzando le variabili evento.
  • condition: specifica quali variabili evento devono esistere affinché la regola venga attivata.

Definire e utilizzare le variabili evento

Le variabili evento fungono da contenitore logico, raggruppando i filtri in modo da poter fare riferimento a un'attività specifica nella ricerca, nella regola o nella dashboard.

Quando definisci la logica nella sezione events, puoi utilizzare le variabili evento (ad esempio $e) per rappresentare un evento specifico (o un gruppo di eventi) che corrisponde ai tuoi criteri.

Esempio: definire e filtrare le variabili evento

Per definire una variabile evento (ad esempio, $e), utilizza un prefisso nella sezione events della query. In questo modo, gli eventi vengono dichiarati come rappresentati dalla variabile. Ad esempio, l'espressione $e.principal.hostname = "dev" valuta ogni evento per determinare se il nome host corrisponde esattamente.

$e.principal.hostname = "dev"
$e.metadata.event_type = "USER_LOGIN"

Puoi quindi utilizzare questa variabile in altre sezioni della query per fare riferimento a quel gruppo specifico di eventi (nelle sezioni match, outcome, condition) e ai relativi campi di dati.

Organizzare la struttura e la sintassi delle regole

Utilizza la seguente struttura e sintassi delle regole per definire le variabili, la logica di raggruppamento e le soglie di attivazione:

Elemento Descrizione Esempio
Struttura della regola Racchiude la query in un blocco rule e assegna un nome univoco per identificare il rilevamento. rule DailyFailedLoginAttempts { }
Sezione meta Obbligatorio. Include metadati descrittivi (ad esempio `author`, `description`, `severity`) per migliorare la gestione delle regole e fornire contesto al tuo team. Consigliato come best practice per la gestione delle regole. author = "Alex"
severity = "Medium"
Variabile evento In una query sulle regole, ogni campo della sezione events è preceduto da una variabile evento (come $e) per rappresentare un evento specifico (o un gruppo di eventi) che corrisponde ai tuoi criteri. Fungono da raggruppamenti logici di filtri.

Nell'esempio Converti la ricerca in una regola YARA-L, $e rappresenta tutti gli accessi non riusciti degli utenti.		 $e.metadata.event_type = "USER_LOGIN"
Variabile segnaposto Assegna un evento a un nome comune a cui puoi fare riferimento in un secondo momento nella query. Per maggiori dettagli, vedi Utilizzare le variabili segnaposto. $userid = $e.principal.user.userid
Sezione match Definisce i raggruppamenti e specifica un intervallo di tempo supportato. Nell'esempio Converti la ricerca in una regola YARA-L, il raggruppamento match: $userid over day raggruppa correttamente gli eventi in base all'ID utente in ogni periodo di 24 ore (1d).

Quando scrivi una regola, devi specificare un intervallo di tempo supportato per definire il periodo di analisi retrospettiva. Puoi implementare una finestra hop, sliding o tumbling a seconda dei requisiti della logica. L'utilizzo dell'operatore over crea esplicitamente una finestra di salto. 		$userid over 1d
Sezione outcome Esegue aggregazioni statistiche o acquisisce variabili specifiche per rendere più informative le notifiche risultanti.

Utilizza la funzione count() su $e.metadata.id per aggregare gli eventi all'interno di ogni gruppo match. Puoi anche assegnare variabili, ad esempio $userid, per acquisire campi UDM specifici e fornire più contesto nell'output di rilevamento risultante.		 $failed_count = count($e.metadata.id)
Sezione condition Necessario per generare un rilevamento.

Definisce la soglia di rilevamento nella sezione condition. Ad esempio, l'utilizzo di #e > 5 richiede che il conteggio eventi superi cinque (5) per attivare un avviso. Se non esegui calcoli, devi comunque includere una sezione condition e indicare l'esistenza della variabile evento (ad esempio, #e).

Analizza la baseline del tuo ambiente per impostare soglie che rilevino attività sospette riducendo al minimo i falsi positivi. Se non esegui calcoli, devi comunque includere una sezione condition e indicare semplicemente l'esistenza della variabile evento, ad esempio #e.		 #e > 5 o $e

Per capire come funziona questa struttura, consulta l'esempio seguente.

Esempio: rilevare attacchi di forza bruta (più tentativi di accesso non riusciti)

Il seguente esempio rileva più tentativi di accesso non riusciti per un singolo utente nell'arco di 24 ore:

rule DailyFailedLoginAttempts {
  meta:
    author = "Alex"
    description = "Detects multiple failed login attempts for a single user within a day."
    severity = "Medium"

  events:
    $e.metadata.event_type = "USER_LOGIN"
    $e.security_result.action = "FAIL"
    $e.principal.user.userid != ""
    $userid = $e.principal.user.userid

  match:
    $userid over 1d

  outcome:
    $daily_failed_login_count = count($e.metadata.id)

  condition:
    $daily_failed_login_count > 5
}

Per convertire una query di ricerca finalizzata in una regola affidabile per generare rilevamenti, in genere segui questi passaggi:

  1. In Google SecOps, vai all'editor di regole.
  2. Inizia una nuova regola.
  3. Incolla la query di ricerca e modificala in modo che corrisponda alla struttura della regola, tra cui:
    • Sezione meta: definisce la regola dei metadati, inclusi il nome, l'autore e il livello di gravità della regola
    • Sezione event: obbligatoria. A differenza della ricerca, devi avere un'intestazione di sezione event.
    • Variabili evento: dichiarano e fanno riferimento a eventi specifici (o gruppi di eventi) all'interno della logica.
    • Sezione match con intervalli di tempo supportati: specifica le chiavi di raggruppamento e definisce i parametri temporali (ad esempio 5m o 1d). Nota: se utilizzi una sezione match nelle regole, devi aggiungere un intervallo di tempo.
    • Sezione condition: definisce la logica o la soglia finale che deve essere soddisfatta per attivare una regola.

Avanzato: crea una regola multi-evento

Utilizzi una regola multi-evento per correlare diversi tipi di attività che si verificano in un periodo di tempo specifico. Anziché esaminare un singolo evento, colleghi più eventi, ad esempio l'accesso di un utente e il download immediato di un file insolito, per identificare minacce complesse.

Una regola multi-evento richiede le seguenti sezioni:

  • meta: contiene il nome della regola e i dettagli descrittivi.
  • events: definisce le origini dati e i filtri utilizzando le variabili evento.
  • match: imposta il periodo di tempo e la variabile segnaposto utilizzata per collegare gli eventi.
  • outcomeAcquisisce un contesto aggiuntivo per l'avviso. Le regole multi-evento richiedono una funzione di aggregazione.
  • condition: specifica quali variabili evento devono esistere affinché la regola venga attivata.

Per creare una regola multi-evento:

  1. Definisci le variabili evento: nella sezione degli eventi, definisci $e1 per acquisire gli eventi "PROCESS_LAUNCH" e $e2 per acquisire hash di file dannosi specifici.
  2. Correlare con i segnaposto: utilizza la variabile segnaposto $user per collegare questi due flussi di eventi distinti tramite un ID utente principale condiviso (ad esempio, $user = $e1.principal.user.userid and $user = $e2.principal.user.userid).
  3. Raggruppa la corrispondenza: nella sezione match, specifica che questi eventi devono verificarsi per lo stesso $user entro un determinato periodo di tempo, ad esempio 5 minuti (5m).

Esempio: creare una regola multi-evento

Nell'esempio seguente, $e1 rappresenta un evento PROCESS_LAUNCH e $e2 rappresenta un evento con un hash dannoso specifico. La variabile segnaposto $user correla questi eventi in base allo stesso ID utente principale.

rule MultiEventExample {
  meta:
    author = "Alex"
    description = "Detects a bad hash execution or a process launch from a specific IP for the same user."

  events:
    $e1.principal.ip = "1.1.1.1"
    $e1.metadata.event_type = "PROCESS_LAUNCH"
    $e2.target.file.sha256 = "badhash..."
    $user = $e1.principal.user.userid
    $user = $e2.principal.user.userid

  match:
    $user over 5m

  condition:
    $e1 or $e2
}

I seguenti componenti della regola descrivono la logica utilizzata nell'esempio:

  • Variabili evento: sono state definite due variabili evento, $e1 e $e2. Utilizza la variabile segnaposto $user per unire questi eventi nel campo comune userid.
  • Sezione match: è stata inclusa una sezione match per questa regola multi-evento per raggruppare gli eventi per utente e specificare una finestra temporale di salto di cinque minuti (5m) per correlare gli eventi.
  • condition: definisce la logica per attivare l'avviso. Questo esempio attiva un avviso se esiste il primo o il secondo evento.

Utilizzare altri strumenti per creare la query

Questi strumenti sono essenziali per scrivere, convalidare e accelerare l'adozione di YARA-L:

  • Strumento di ricerca UDM: cerca e fai riferimento rapidamente a nomi, definizioni e tipi di dati dei campi UDM direttamente all'interno della UI. Se l'ID campo è sconosciuto, dai la priorità al controllo di questo riferimento.
  • Ricerca dal linguaggio naturale a YARA-L: nella barra di ricerca, inserisci le descrizioni per creare la query iniziale o ottenere o tradurre i suggerimenti YARA-L corrispondenti.
  • SPL → YARA-L Translator (strumento Labs): se stai eseguendo la transizione da piattaforme concorrenti, utilizza questo strumento (disponibile nella sezione Labs) per convertire le query SPL legacy di Splunk in YARA-L. In questo modo viene generato un punto di partenza strutturato, che accelera la migrazione e perfeziona la logica di rilevamento. Per utilizzare lo strumento Labs, in Google SecOps, vai a yourinstancename.chronicle.security/labs.

Passaggi successivi

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