Sintassi della sezione Risultato

Supportato in:

La sezione outcome di una query YARA-L definisce le variabili di risultato che specificano l'output per una query di ricerca e della dashboard, nonché contesto e informazioni aggiuntivi per un rilevamento quando viene attivata una regola. Queste variabili possono essere utilizzate per vari scopi, ad esempio per visualizzare dati pertinenti nelle dashboard e creare punteggi di rischio.

Definisci la sezione Risultato

Utilizza il carattere $, seguito dal nome di una variabile, per definire una variabile di risultato nella sezione outcome di una singola query. Puoi definire fino a 20 variabili di risultato. I nomi delle variabili sono arbitrari. Per le regole, i valori dei risultati vengono calcolati e aggregati in base a ogni rilevamento.

A ogni variabile di risultato viene assegnato un valore utilizzando un'espressione.

Questa regola cerca tentativi di accesso non riusciti da una nuova posizione:

rule failed_logins
{
  meta:
   author = "Security Team"
   description = "Detects multiple failed user logins within 10-minute windows."
   severity = "HIGH"

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

  match:
   $user over 10m

  outcome:
   $failed_login_count = count($e.metadata.id)
   $first_fail_time = min($e.metadata.event_timestamp.seconds)

  condition:
   #e >= 5
}

La sezione outcome esegue aggregazioni sulle variabili evento e segnaposto: conta gli accessi non riusciti, gli IP univoci e l'ora in cui si è verificato l'errore.

outcome:
   $failed_login_count = count($e.metadata.id)
   $first_fail_time = min($e.metadata.event_timestamp.seconds)

Se includi e compili la variabile speciale $risk_score outcome, il relativo valore (numero intero o in virgola mobile) viene visualizzato nella pagina Avvisi e indicatori di compromissione per gli avvisi generati dalla query.

Se non includi una variabile $risk_score nella sezione outcome di una query, viene impostato uno dei seguenti valori predefiniti:

  • Se la query è configurata per generare un avviso, $risk_score è impostato su 40.

  • Se la query non è configurata per generare un avviso, $risk_score è impostato su 15.

Il valore di $risk_score è memorizzato nel campo UDM security_result.risk_score.

Variabile di risultato risk_score

Google SecOps Risk Analytics associa automaticamente i rilevamenti e gli avvisi alle entità correlate a quel rilevamento o avviso. La variabile risultato risk_score viene utilizzata per assegnare un livello di rischio. Se questo valore non è impostato, viene utilizzato il valore predefinito di rilevamento o avviso. Puoi configurare i valori predefiniti in Impostazioni.

Per garantire la coerenza sulla piattaforma, ti consigliamo di utilizzare i seguenti intervalli di punteggio quando assegni un risk_score alle tue rilevazioni personalizzate. Questo allineamento contribuisce a standardizzare i workflow di assegnazione delle priorità e di risposta agli avvisi.

Gravità Intervallo di punteggi Descrizione Esempio
Avvisi - Critici 90 - 100 Compromissione attiva con il potenziale di avere un impatto oltre un singolo account utente o endpoint. Richiede una revisione immediata. Mimikatz eseguito sul controller di dominio.
Avvisi - Alto 80 - 89 Compromissione attiva di un singolo endpoint o entità. Deve essere esaminato immediatamente. Il server di produzione chiama un C2 recente e noto.
Avvisi - Medio 50 - 79 Potenziale problema di sicurezza che richiede un'indagine. Nessuna compromissione confermata, ma è possibile la riassegnazione. Una credenziale esposta, nessun segno di uso improprio.
Non avviso - Basso 20 - 49 Evento di sicurezza a basso impatto che, se combinato con altri indicatori o osservazioni, potrebbe portare a un incidente più significativo. In genere non è necessaria alcuna revisione. Può essere combinato con altre rilevazioni tramite regole composite per creare un avviso. Scansione delle porte interne.
Osservazioni senza avvisi 1 - 19 In genere, rilevamenti basati su informazioni destinate a creare consapevolezza situazionale di una minaccia. In genere non richiede revisione; può essere combinato con altre rilevazioni tramite regole composite per generare avvisi. Un evento di accesso, nessun segno di utilizzo improprio.

Poiché risk_score è una variabile di risultato, le regole possono esprimere sfumature a seconda di fattori quali l'intelligence sulle minacce o altre condizioni simultanee.

I punteggi di rischio delle entità possono essere utilizzati per generare avvisi basati sul rischio quasi in tempo reale. Per saperne di più, consulta la panoramica di Risk Analytics.

Variabile di risultato risk_entity_to_score

Oltre alla variabile di risultato risk_score, puoi specificare anche la variabile di risultato risk_entity_to_score. Questa variabile ti consente di designare esplicitamente l'entità o le entità di un rilevamento di regole a cui deve essere applicato il punteggio di rischio del rilevamento.

Puoi creare più variabili risk_entity_to_score aggiungendo una stringa univoca alla variabile e assegnare il punteggio di rischio a entità specifiche. Ad esempio:

$risk_entity_to_score_source_asset = $e.principal.asset.hostname
$risk_entity_to_score_targeted_user = $e.target.user.userid

Queste variabili di risultato assegnano il risk_score specificato nella sezione outcome della regola alle entità $e.principal.asset.hostname e $e.target.user.userid.

Esempio: la regola rileva gli accessi agli account amministratore

Questa regola rileva gli accessi riusciti agli account amministratore con privilegi elevati. Utilizza la parola chiave risk_entity_to_score per scegliere come target in modo esplicito l'utente specifico che ha eseguito l'accesso. Utilizzando questa variabile, il rilevamento garantisce che il punteggio di rischio calcolato si applichi solo a quell'utente e non ad altre entità coinvolte nell'evento, ad esempio l'indirizzo IP di origine.

Per informazioni dettagliate su come scrivere una regola multi-evento, vedi Regola multi-evento.

rule suspicious_admin_privilege_escalation {
 // This rule matches single events. Rules can also match multiple events within
 // the same time window.

 meta:
   // Allows for storage of arbitrary key-value pairs of rule details, such as 
   // who wrote it, what it detects on, and version control.
   // The "author" and "severity" fields are special, since they are used as
   // columns on the rules dashboard. To sort based on these fields on the 
   // dashboard, add them here.
   // Severity value should be "Low", "Medium", or "High"
   author = "analyst123"
   description = "Detects suspicious login to critical admin accounts."
   severity = "HIGH"

 events:
   $e.metadata.event_type = "USER_LOGIN"
   $e.target.user.attribute.roles.name = "ADMIN"
   $e.security_result.summary = "Successful login with high-privilege access"

 outcome:
   // Multi-event rules require an aggregation function
   // For example, risk_score = max(0)
   // See https://cloud.google.com/chronicle/docs/detection/yara-l-2-0-overview#outcome_conditionals_example_rule
   $risk_score = 80
   $risk_entity_to_score = $e.target.user.userid
   $source_ip = array_distinct($e.principal.ip)

 condition:
   $e
}

Esempio: la regola monitora le connessioni di rete interne

Questa regola verifica il movimento laterale identificando le connessioni di rete tra segmenti di rete interni. Utilizza $risk_entity_to_score prefix per assegnare il rischio a più entità all'interno di un singolo rilevamento. Sia l'host di avvio ($risk_entity_to_score_source_asset) sia l'utente di destinazione ($risk_entity_to_score_targeted_user) hanno i punteggi di rischio aggiornati. Il motore di rischio registra altre variabili di risultato che non utilizzano questo prefisso specifico per il contesto, ma le ignora (i relativi punteggi di rischio rimangono invariati).

Per informazioni dettagliate su come scrivere una regola multi-evento, vedi Regola multi-evento e Regola di esempio con condizioni di risultato.

rule lateral_movement_network_connection {
 // This rule matches single events. You can also match multiple events within
 // the same time window.

 meta:
   // Allows for storage of arbitrary key-value pairs of rule details (for 
   // example, who wrote it, what it detects on, and version control).
   // The "author" and "severity" fields are special, since they are used as
   // columns on the rules dashboard. To sort based on these fields on the 
   // dashboard, add them here. Severity value should be "Low", "Medium" or "High"
   author = "analyst123"
   description = "Detects lateral movement attempts between internal segments."
   severity = "MEDIUM"

 events:
   $e.metadata.event_type = "NETWORK_CONNECTION"
   $e.principal.asset.hostname != ""
   $e.target.user.userid != ""
   // Can also use: $e.target.ip = /10\..*/
   net.ip_in_range_cidr($e.target.ip, "10.0.0.0/8")

 outcome:
   // Multi-event rules require an aggregation function
   // for example, risk_score = max(0)
   // See https://docs.cloud.google.com/chronicle/docs/yara-l/yara-l-2-0-examples#outcome-conditionals-example-rule
   $risk_score = 50
   $risk_entity_to_score_source_asset = $e.principal.asset.hostname
   $risk_entity_to_score_targeted_user = $e.target.user.userid
   $target_ip_info = array_distinct($e.target.ip)

 condition:
   $e
}

Tipi di dati delle variabili di risultato

Ogni variabile di risultato può avere un tipo di dati diverso, determinato dall'espressione utilizzata per calcolarla. In Google SecOps sono supportati i seguenti tipi di dati sugli esiti:

  • integer
  • float
  • string
  • elenchi di numeri interi
  • elenchi di numeri decimali
  • elenchi di stringhe

Logica condizionale

Puoi utilizzare la logica condizionale per calcolare il valore di un risultato. Le condizioni vengono specificate utilizzando il seguente pattern di sintassi:

if(BOOL_CLAUSE, THEN_CLAUSE)
if(BOOL_CLAUSE, THEN_CLAUSE, ELSE_CLAUSE)

Puoi leggere un'espressione condizionale come "se BOOL_CLAUSE è true, restituisci THEN_CLAUSE, altrimenti restituisci ELSE_CLAUSE".

BOOL_CLAUSE deve restituire un valore booleano. Un'espressione BOOL_CLAUSE ha una forma simile alle espressioni nella sezione events. Ad esempio, può contenere:

  • Nomi dei campi UDM con operatore di confronto:

    if($context.graph.entity.user.title = "Vendor", 100, 0)

  • Variabile segnaposto definita nella sezione events:

    if($severity = "HIGH", 100, 0)

  • Un'altra variabile di risultato definita nella sezione outcome:

    if($risk_score > 20, "HIGH", "LOW")

  • Funzioni che restituiscono un valore booleano:

    if(re.regex($e.network.email.from, `.*altostrat.com`), 100, 0)

  • Cerca in un elenco di riferimento:

    if($u.principal.hostname in %my_reference_list_name, 100, 0)

  • Confronto tra aggregazioni:

    if(count($login.metadata.event_timestamp.seconds) > 5, 100, 0)

THEN_CLAUSE ed ELSE_CLAUSE devono essere dello stesso tipo di dati. Supportiamo numeri interi, numeri in virgola mobile e stringhe.

Puoi omettere ELSE_CLAUSE se il tipo di dati è un numero intero o un numero in virgola mobile. Se omessa, la ELSE_CLAUSE restituisce 0. Ad esempio:

`if($e.field = "a", 5)` is equivalent to `if($e.field = "a", 5, 0)`

Devi fornire ELSE_CLAUSE se il tipo di dati è stringa o se THEN_CLAUSE è una variabile segnaposto o una variabile risultato.

Operazioni matematiche

Puoi utilizzare operazioni matematiche per calcolare il tipo di dati integer o float nelle sezioni outcome e events di una query. Google Security Operations supporta addizione, sottrazione, moltiplicazione, divisione e modulo come operatori di primo livello in un calcolo.

Il seguente snippet è un esempio di calcolo nella sezione outcome:

outcome:
  $risk_score = max(100 + if($severity = "HIGH", 10, 5) - if($severity = "LOW", 20, 0))

Le operazioni matematiche sono consentite sui seguenti tipi di operandi, a condizione che ogni operando e l'intera espressione aritmetica siano aggregati correttamente (vedi Aggregazioni):

  • Campi evento numerici
  • Variabili segnaposto numeriche definite nella sezione events
  • Variabili numeriche dei risultati definite nella sezione outcome
  • Funzioni che restituiscono numeri interi o numeri in virgola mobile
  • Aggregazioni che restituiscono numeri interi o numeri in virgola mobile

Il modulo non è consentito per i numeri in virgola mobile.

Variabili segnaposto nei risultati

Quando calcoli le variabili di risultato, puoi utilizzare le variabili segnaposto definite nella sezione degli eventi della query. In questo esempio, supponiamo che $email_sent_bytes sia stato definito nella sezione degli eventi della regola:

Esempio: evento singolo senza sezione di corrispondenza

// No match section, so this is a single-event query.

outcome:
  // Use placeholder directly as an outcome value.
  $my_outcome = $email_sent_bytes

  // Use placeholder in a conditional.
  $other_outcome = if($file_size > 1024, "SEVERE", "MODERATE")

condition:
  $e

Esempio: evento multiplo con sezione della partita

match:
  // This is a multi event query with a match section.
  $hostname over 5m

outcome:
  // Use placeholder directly in an aggregation function.
  $max_email_size = max($email_sent_bytes)

  // Use placeholder in a mathematical computation.
  $total_bytes_exfiltrated = sum(
    1024
    + $email_sent_bytes
    + $file_event.principal.file.size
  )

condition:
  $email_event and $file_event

Variabili di risultato nelle espressioni di assegnazione del risultato

Le variabili risultato possono essere utilizzate per derivare altre variabili risultato, in modo simile alle variabili segnaposto definite nella sezione events. Puoi fare riferimento a una variabile risultato nell'assegnazione di un'altra variabile risultato con un token $ seguito dal nome della variabile. Le variabili di risultato devono essere definite prima di poter essere utilizzate nel testo della query. Se utilizzate in un'espressione di assegnazione, le variabili di risultato non devono essere aggregate (vedi Aggregazioni).

Nell'esempio seguente, la variabile di risultato $risk_score deriva il suo valore dalla variabile di risultato $event_count:

Esempio: variabile di risultato derivata da un'altra variabile di risultato

match:
  // This is a multi event query with a match section.
  $hostname over 5m

outcome:
  // Aggregates all timestamp on login events in the 5 minute match window.
  $event_count = count($login.metadata.event_timestamp.seconds)

  // $event_count cannot be aggregated again.
  $risk_score = if($event_count > 5, "SEVERE", "MODERATE")

  // This is the equivalent of the 2 outcomes combined.
  $risk_score2 = if(count($login.metadata.event_timestamp.seconds) > 5, "SEVERE", "MODERATE")

condition:
  $e

Le variabili risultato possono essere utilizzate in qualsiasi tipo di espressione sul lato destro di un'assegnazione del risultato, tranne nelle seguenti espressioni:

  • Aggregazioni
  • Arrays.length() chiamate di funzione
  • Con i modificatori any o all

Aggregazioni

I campi evento ripetuti sono valori non scalari. ovvero una singola variabile punta a più valori. Ad esempio, la variabile del campo evento $e.target.ip è un campo ripetuto e può avere zero, uno o molti valori IP. È un valore non scalare. mentre la variabile di campo evento $e.principal.hostname non è un campo ripetuto e ha un solo valore (ovvero un valore scalare).

Analogamente, sia i campi evento non ripetuti sia quelli ripetuti utilizzati nella sezione outcome di una query con una finestra di corrispondenza sono valori non scalari.

Esempio: raggruppare gli eventi con la sezione di corrispondenza e il campo non ripetuto

La seguente query raggruppa gli eventi utilizzando una sezione "match" e fa riferimento a un campo evento non ripetuto nella sezione "outcome":

rule OutcomeAndMatchWindow{
  ...
  match:
    $userid over 5m
  outcome:
    $hostnames = array($e.principal.hostname)
  ...
}

Qualsiasi finestra di 5 minuti in cui viene eseguita la query può contenere zero, uno o molti eventi. La sezione Risultato opera su tutti gli eventi in una finestra di corrispondenza. Qualsiasi variabile di campo evento a cui viene fatto riferimento nella sezione risultato può puntare a zero, uno o più valori del campo in ogni evento nella finestra di corrispondenza. Ad esempio, se una finestra di 5 minuti contiene 5 eventi $e, $e.principal.hostname nella sezione dei risultati indica cinque nomi host diversi. La variabile del campo evento $e.principal.hostname viene trattata come un valore non scalare nella sezione outcome di questa query.

Poiché le variabili di risultato devono sempre produrre un singolo valore scalare, qualsiasi valore non scalare da cui dipende un'assegnazione del risultato deve essere aggregato per produrre un singolo valore scalare. In una sezione dei risultati, i seguenti sono valori non scalari e devono essere aggregati:

  • Campi evento (ripetuti o non ripetuti) quando la query utilizza una sezione match
  • Segnaposto per eventi (ripetuti o non ripetuti) quando la query utilizza una sezione match
  • Campi evento ripetuti quando la query non utilizza una sezione match
  • Segnaposto per eventi ripetuti quando la query non utilizza una sezione match

I campi evento scalari, i segnaposto evento scalari e le costanti possono essere racchiusi in funzioni di aggregazione nelle query che non includono una sezione match. Tuttavia, nella maggior parte dei casi, queste aggregazioni restituiscono il valore sottoposto a wrapping, rendendole non necessarie. Un'eccezione è l'aggregazione array(), che puoi utilizzare per convertire esplicitamente un valore scalare in un array.

Le variabili di risultato vengono trattate come aggregazioni: non devono essere riaggregate quando vengono utilizzate in un'altra assegnazione di risultato.

Puoi utilizzare le seguenti funzioni di aggregazione:

Funzione di aggregazione Descrizione
max() Restituisce il valore massimo tra tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.
min() Restituisce il valore minimo tra tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.
sum() Restituisce la somma di tutti i valori possibili. Funziona solo con numeri interi e in virgola mobile.
count_distinct() Raccoglie tutti i valori possibili, quindi restituisce il conteggio distinto dei valori possibili.
count() Si comporta come `count_distinct()`, ma restituisce un conteggio non univoco dei valori possibili.
array_distinct() Raccoglie tutti i possibili valori distinti, quindi restituisce un elenco di questi valori. Tronca l'elenco dei valori distinti a 1000 elementi casuali. Viene applicata prima la deduplicazione per ottenere un elenco distinto, poi il troncamento.
array() Si comporta come array_distinct(), ma restituisce un elenco di valori non distinti. Inoltre,tronca l'elenco dei valori a 1000 elementi casuali.

La funzione di aggregazione è importante quando una regola include una sezione condition che specifica che devono esistere più eventi, perché la funzione di aggregazione opererà su tutti gli eventi che hanno generato il rilevamento.

Esempio: condizione per più eventi

Di seguito è riportato un esempio di condizione per più eventi. Se la sezione relativa al risultato e alla condizione contiene:

outcome:
  $asset_id_count = count($event.principal.asset_id)
  $asset_id_distinct_count = count_distinct($event.principal.asset_id)

  $asset_id_list = array($event.principal.asset_id)
  $asset_id_distinct_list = array_distinct($event.principal.asset_id)

condition:
  #event > 1

Poiché la sezione `condition` richiede la presenza di più di un `event` per ogni rilevamento, le funzioni di aggregazione operano su più eventi. Supponiamo che i seguenti eventi abbiano generato un rilevamento:

event:
  // UDM event 1
  asset_id="asset-a"

event:
  // UDM event 2
  asset_id="asset-b"

event:
  // UDM event 3
  asset_id="asset-b"

I valori dei risultati saranno:

    $asset_id_count = 3
    $asset_id_distinct_count = 2
    $asset_id_list = `["asset-a", "asset-b", "asset-b"]
    $asset_id_distinct_list = `["asset-a", "asset-b"]

Limitazioni

  • La sezione outcome non può fare riferimento a una nuova variabile segnaposto che non è già stata definita nella sezione events o nella sezione outcome.

  • La sezione outcome non può utilizzare variabili evento che non sono state definite nella sezione events.

  • La sezione outcome può utilizzare un campo evento non utilizzato nella sezione events, a condizione che la variabile evento a cui appartiene il campo evento sia già stata definita nella sezione events.

  • La sezione outcome può correlare solo le variabili evento che sono già state correlate nella sezione events. Le correlazioni si verificano quando vengono equiparati due campi evento di variabili evento diverse.

Consulta la sezione Panoramica di YARA-L 2.0 per esempi di outcome.

Per informazioni dettagliate sulla deduplicazione del rilevamento con la sezione outcome, vedi Creare analisi sensibili al contesto.

Passaggi successivi

Informazioni aggiuntive

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