Sintassi della sezione Outcome

Supportata in:

La sezione outcome di una query YARA-L definisce le variabili dei risultati che specificano l'output per una query di ricerca e della dashboard, nonché il contesto e le 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 scoring del rischio.

Sezione Definisci 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 gli accessi non riusciti da una nuova località:

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 di evento e segnaposto: conteggio degli accessi non riusciti, conteggio degli IP distinti e recupero dell'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 di risultato speciale $risk_score, il suo valore (numero intero o con virgola mobile) viene visualizzato nella pagina Avvisi e IoC 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 viene impostato su 15.

Il valore di $risk_score viene archiviato 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. La variabile di risultato risk_score viene utilizzata per assegnare un livello di rischio. Se questo valore non è impostato, viene utilizzato il valore di rilevamento o di avviso predefinito. Puoi configurare i valori predefiniti nelle Impostazioni.

Per garantire la coerenza sulla piattaforma, ti consigliamo di utilizzare i seguenti intervalli di punteggio quando assegni un risk_score ai rilevamenti personalizzati. Questo allineamento aiuta a standardizzare i workflow di definizione delle priorità e di risposta agli avvisi.

Gravità Intervallo di punteggi Descrizione Esempio
Avviso - Critico 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 domain controller.
Avvisi - Alta 80 - 89 Compromissione attiva di un singolo endpoint o di una singola entità. Dovrebbero essere sottoposti a revisione immediata. Server di produzione che chiama un C2 recente e noto.
Avvisi - Media 50 - 79 Potenziale problema di sicurezza che richiede un'indagine. Nessuna compromissione confermata, ma è possibile un'escalation. Una credenziale esposta, nessun segno di uso improprio.
Nessun 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 altri rilevamenti tramite regole composite per creare un avviso. Scansione delle porte interne.
Osservazioni che non generano avvisi 1 - 19 In genere, rilevamenti basati su informazioni volti a creare una consapevolezza situazionale di una minaccia. In genere non richiede una revisione; può essere combinato con altri rilevamenti tramite regole composite per generare avvisi. Un evento di accesso, nessun segno di uso improprio.

Poiché risk_score è una variabile di risultato, le regole possono esprimere sfumature a seconda di fattori come la threat intelligence o altre condizioni concomitanti.

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

Variabile di risultato risk_entity_to_score

Per impostazione predefinita, Google SecOps assegna lo scoring del rischio di un rilevamento a tutte le entità negli eventi campionati. Inoltre, assegna il punteggio a tutte le entità acquisite nelle sezioni match e outcome della regola. Per assegnare lo scoring del rischio a entità specifiche, specifica la variabile di risultato risk_entity_to_score oltre a risk_score. Lo scoring del rischio supporta le entità user e asset. Non supporta i tipi di entità RESOURCE o GROUP.

Puoi creare più variabili risk_entity_to_score aggiungendo una stringa univoca alla variabile e assegnare lo scoring del 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 valore 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 ad account amministratore con privilegi elevati. Utilizza la parola chiave risk_entity_to_score per scegliere esplicitamente come target l'utente specifico che ha eseguito l'accesso. Utilizzando questa variabile, il rilevamento garantisce che lo scoring del rischio calcolato si applichi solo a quell'utente e non ad altre entità coinvolte nell'evento, come l'indirizzo IP di origine.

Per maggiori dettagli su come scrivere una regola per più eventi, consulta Regola per più eventi.

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://docs.cloud.google.com/chronicle/docs/yara-l/yara-l-2-0-examples#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: regola che monitora le connessioni di rete interne

Questa regola verifica la presenza di movimenti laterali identificando le connessioni di rete tra i segmenti di rete interni. Utilizza $risk_entity_to_score prefix per assegnare il rischio a più entità all'interno di un singolo rilevamento. I punteggi di scoring del rischio dell'host di avvio ($risk_entity_to_score_source_asset) e dell'utente target ($risk_entity_to_score_targeted_user) vengono aggiornati. Il motore di rischio registra altre variabili di risultato che non utilizzano questo prefisso specifico per il contesto, ma le ignora (i loro punteggi di rischio rimangono invariati).

Per maggiori dettagli su come scrivere una regola per più eventi, consulta Regola per più eventi e Regola di esempio per i condizionali dei risultati.

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 dei risultati:

  • integer
  • float
  • string
  • elenchi di numeri interi
  • elenchi di numeri con virgola mobile
  • 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 delle 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 con 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 clausola 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 è una stringa o se THEN_CLAUSE è una variabile segnaposto o una variabile di risultato.

Operazioni matematiche

Puoi utilizzare operazioni matematiche per calcolare il tipo di dati intero o con virgola mobile 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 (consulta Aggregazioni):

  • Campi evento numerici
  • Variabili segnaposto numeriche definite nella sezione events
  • Variabili di risultato numeriche definite nella sezione outcome
  • Funzioni che restituiscono int o float
  • Aggregazioni che restituiscono numeri interi o con virgola mobile

Il modulo non è consentito per i valori con virgola mobile.

I valori letterali interi standard vengono impostati per impostazione predefinita su numeri interi con segno a 64 bit (INT64), che non sono compatibili con i campi UDM di numeri interi senza segno a 64 bit (UINT64), come network.received_bytes, network.sent_bytes e principal.file.size. La combinazione di questi tipi in operazioni aritmetiche (+, -, *) o modulo (%) può causare un errore di runtime nella sezione outcome. Per risolvere il problema, utilizza cast.as_int() o cast.as_uint() per trovare i tipi di numeri interi corrispondenti. Per l'operatore % è richiesto il casting esplicito. Per le operazioni aritmetiche, puoi anche forzare le costanti intere a comportarsi come numeri in virgola mobile utilizzando valori letterali in rappresentazione in virgola mobile, come 2.0 o 100.0, o la coercizione della divisione, come (2/1), nelle espressioni senza altri operatori / sulla stessa riga. Per saperne di più, consulta Aritmetica con campi di eventi non firmati.

Variabili segnaposto nei risultati

Quando calcoli le variabili dei risultati, 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: multievento 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.0
    + $email_sent_bytes
    + $file_event.principal.file.size
  )

condition:
  $email_event and $file_event

Variabili dei risultati nelle espressioni di assegnazione dei risultati

Le variabili di risultato possono essere utilizzate per ricavare altre variabili di risultato, in modo simile alle variabili segnaposto definite nella sezione events. Puoi fare riferimento a una variabile di risultato nell'assegnazione di un'altra variabile di risultato con un token $ seguito dal nome della variabile. Le variabili di risultato devono essere definite prima di poter essere richiamate nel testo della query. Se utilizzate in un'espressione di assegnazione, le variabili dei risultati non devono essere aggregate (consulta 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 di risultato possono essere utilizzate in qualsiasi tipo di espressione sul lato destro di un'assegnazione di risultato, ad eccezione delle seguenti espressioni:

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

Aggregazioni

I campi di evento ricorrente sono valori non scalari. In altre parole, 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 più valori IP. È un valore non scalare. La variabile del campo evento $e.principal.hostname, invece, non è un campo ripetuto e ha un solo valore (ovvero un valore scalare).

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

Esempio: raggruppa 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 potrebbe contenere zero, uno o più eventi. La sezione outcome opera su tutti gli eventi in una finestra di corrispondenza. Qualsiasi variabile di campo evento a cui si fa riferimento nella sezione dei risultati 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 rimanda a 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 dei risultati devono sempre restituire un singolo valore scalare, qualsiasi valore non scalare da cui dipende un'assegnazione dei risultati deve essere aggregato per restituire un singolo valore scalare. In una sezione dei risultati, i seguenti valori non sono scalari e devono essere aggregati:

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

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

Le variabili dei risultati vengono trattate come aggregazioni: non devono essere riaggregate quando viene fatto riferimento a un'altra assegnazione dei risultati.

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 con virgola mobile.
min() Restituisce il valore minimo tra tutti i valori possibili. Funziona solo con numeri interi e con virgola mobile.
sum() Restituisce la somma di tutti i valori possibili. Funziona solo con numeri interi e con 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 distinto dei valori possibili.
array_distinct() Raccoglie tutti i possibili valori distinti, quindi restituisce un elenco di questi valori. La deduplicazione per produrre un elenco distinto viene applicata per prima, seguita dal troncamento. Nella Ricerca, l'elenco viene troncato a un massimo di 1000 elementi casuali. In Dashboard e Regole, l'elenco viene troncato a un massimo di 25 elementi casuali.
array() Si comporta come array_distinct(), ma restituisce un elenco di valori non distinti. Nella Ricerca, l'elenco viene troncato a un massimo di 1000 elementi casuali. In Dashboard e Regole, l'elenco viene troncato a un massimo di 25 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 a risultati e condizioni 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 che sia presente più di un "event" per ogni rilevamento, le funzioni aggregate opereranno 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 di evento che non sono state definite nella sezione events.

  • La sezione outcome può utilizzare un campo evento che non è stato 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 di evento che sono già state correlate nella sezione events. Le correlazioni si verificano quando due campi di eventi di variabili di eventi diverse vengono equiparati.

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

Per informazioni dettagliate sulla deduplicazione dei rilevamenti con la sezione outcome, consulta Crea 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.