Gestisci le esclusioni delle regole

Supportata in:

Questo documento spiega come gestire in modo programmatico le esclusioni delle regole in Google Security Operations utilizzando l'API. Le esclusioni fungono da filtri che definisci in base ai campi del modello UDM (Unified Data Model) per impedire che rilevamenti specifici generino avvisi. Identificando le attività note o sicure, questi filtri eliminano il rumore non necessario nella dashboard.

Crea un'esclusione con i filtri dei risultati

Puoi creare una nuova regola di esclusione in modo programmatico per sopprimere risultati di rilevamento specifici che corrispondono ai criteri definiti, riducendo così il rumore e dando la priorità agli avvisi ad alta fedeltà.

Utilizza l'endpoint POST per definire la logica di soppressione. Tutti i filtri con l'array outcomeFilters sono collegati da una clausola AND implicita.

Metodo: POST

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

Sostituisci quanto segue:

REGION: la regione Google Cloud per l'istanza Google SecOps.

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la località dell'istanza Google SecOps (spesso corrisponde alla regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

Esempio:

POST https://us-chronicle.googleapis.com/v1/projects/my-project/locations/us/instances/my-instance/findingsRefinements

Corpo della richiesta:

{
  "displayName": "Exclusion with outcome filters",
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ]
}

L'esempio mostra come definire la logica di soppressione in cui più filtri nell'array outcomeFilters sono collegati da una clausola AND implicita.

Campi obbligatori: displayName, type, query

Campi generati dal sistema: non specificare name, createTime o updateTime. Questi campi sono gestiti dal sistema e vengono ignorati o causano errori se inclusi nella richiesta.

La logica di soppressione segue una relazione AND. La richiesta crea un'esclusione che sopprime tutti i rilevamenti che hanno un evento con quanto segue:

  • "altostrat.com" come nome host principale

  • Una variabile di risultato ip con un valore di 127.0.0.1

  • Una variabile di risultato hostnames con almeno uno dei suoi valori aggregati pari a altostrat.com.

Tutti i filtri specificati nell'esclusione sono implicitamente collegati da una clausola AND.

Risposta dell'API: l'API restituisce il nome della risorsa FindingsRefinement.

La risorsa FindingsRefinement contiene la logica di soppressione principale (i filtri di query e di risultato). Il nome della risorsa (ID) viene utilizzato per le operazioni successive sull'esclusione

Accedi a un'esclusione

Utilizza l'endpoint GET per:

  • Recupera i dettagli di una singola definizione di esclusione in base al suo ID univoco.

  • Quando hai un refinement-id specifico e devi verificare la query esatta o i filtri dei risultati che contiene.

Metodo: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID

Sostituisci quanto segue:

REGION: la regione Google Cloud per l'istanza Google SecOps.

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la località dell'istanza Google SecOps (spesso corrisponde alla regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

REFINEMENT_ID: l'ID univoco della risorsa FindingsRefinement.

Esempio:

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777

Applica un'esclusione a una regola o a un set di regole selezionate

Per attivare un'esclusione, applicala a regole o set di regole selezionate specifiche aggiornando la relativa risorsa FindingsRefinementDeployment. Utilizza il parametro di query update_mask per specificare i campi da aggiornare nel deployment.

Metodo: PATCH

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID/deployment

Sostituisci quanto segue:

REGION: la regione Google Cloud per l'istanza Google SecOps.

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la località dell'istanza Google SecOps (spesso corrisponde alla regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

REFINEMENT_ID: l'ID univoco della risorsa FindingsRefinement.

Esempio:

PATCH https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment?update_mask=enabled,detectionExclusionApplication

Corpo della richiesta:

{
  "name": "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment",
  "enabled": true,
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/CATEGORY_ID/curatedRuleSets/RULE_SET_ID"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/RULE_ID"
    ]
  }
}

Nel corpo della richiesta, specifica gli elenchi dei nomi delle risorse dei set di regole selezionate e dei nomi delle risorse delle regole selezionate negli array curatedRuleSets e curatedRules. Sostituisci CATEGORY_ID, RULE_SET_ID e RULE_ID con l'ID categoria del set di regole selezionate, l'ID del set di regole selezionate e l'ID della regola selezionata.

Accedi al deployment per l'esclusione

Dopo aver creato o aggiornato un'esclusione, utilizza questo endpoint per verificare in quali regole o set di regole selezionati viene eseguito il deployment dell'esclusione.

Metodo: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements/REFINEMENT_ID/deployment

Sostituisci quanto segue:

REGION: la regione Google Cloud per l'istanza Google SecOps.

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la località dell'istanza Google SecOps (spesso corrisponde alla regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

REFINEMENT_ID: l'ID univoco del perfezionamento dei risultati.

Esempio:

   GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements/fr_00001111-2222-3333-4444-555566667777/deployment

Elenca tutte le esclusioni

Utilizza questo endpoint per recuperare l'elenco delle risorse findingsRefinements.

Metodo: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID/findingsRefinements

Sostituisci quanto segue:

REGION: la regione Google Cloud per l'istanza Google SecOps.

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la località dell'istanza Google SecOps (spesso corrisponde alla regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

Esempio:

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/findingsRefinements

Parametri di query facoltativi: pageSize, pageToken

Puoi utilizzare i parametri facoltativi per elencare altri risultati simili ad altri endpoint di elenco all'interno dell'API.

Elenca tutti i deployment di esclusione

Utilizza il seguente endpoint per ottenere l'elenco delle risorse FindingsRefinementDeployment create all'interno della tua istanza.

Metodo: GET

Endpoint:

https://REGION-chronicle.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:listAllFindingsRefinementDeployments

Sostituisci quanto segue:

REGION: la regione Google Cloud per l'istanza Google SecOps.

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la località dell'istanza Google SecOps (spesso corrisponde alla regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

Esempio:

GET https://us-chronicle.googleapis.com/v1/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:listAllFindingsRefinementDeployments

Parametri di query facoltativi:

  • Utilizza i parametri pageSize e pageToken per elencare altri risultati simili ad altri endpoint di elenco all'interno dell'API.

  • Utilizza il parametro filter per filtrare in base a detection_exclusion_application.curated_rules o detection_exclusion_application.curated_rule_sets.

Testa un'esclusione utilizzando l'API

Il seguente endpoint testa un'esclusione rispetto ai rilevamenti di regole selezionate e set di regole selezionate specificati per convalidare l'efficacia con cui elimina i rilevamenti indesiderati. La console utilizza gli ultimi 30 giorni di rilevamenti per i test.

Metodo: POST

Endpoint:

https://REGION-chronicle.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:testFindingsRefinement

Sostituisci quanto segue:

REGION: la regione Google Cloud per l'istanza Google SecOps.

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la località dell'istanza Google SecOps (spesso corrisponde alla regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

Esempio:

POST https://us-chronicle.googleapis.com/v1alpha/projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210:testFindingsRefinement

Corpo della richiesta:

{
  "type": "DETECTION_EXCLUSION",
  "query": "principal.hostname = \"altostrat.com\"",
  "outcomeFilters": [
    {
      "outcome_variable": "ip",
      "outcome_value": "127.0.0.1",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ],
  "interval": {
    "start_time": {
      "seconds": 1756684800
    },
    "end_time": {
      "seconds": 1759276800
    }
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRuleSetCategories/CATEGORY_ID/curatedRuleSets/RULE_SET_ID"
    ],
    "curatedRules": [
      "projects/0123456789/locations/us/instances/01234567-89ab-cdef-fedc-ba9876543210/curatedRules/RULE_ID"
    ]
  }
}

Nell'esempio precedente, il campo interval testa i rilevamenti dal 1° settembre 2025 alle 00:00 UTC (1756684800) al 1° ottobre 2025 alle 00:00 UTC (1759276800). In detectionExclusionApplication, specifica i nomi delle risorse del set di regole selezionate e delle regole selezionate da testare sostituendo CATEGORY_ID, RULE_SET_ID e RULE_ID.

Sintassi delle query e regole dei campi

Il campo findingsRefinements.query supporta un sottoinsieme limitato della sintassi YARA-L 2.0 anziché la sintassi completa della ricerca UDM (udmSearch). Poiché queste due sintassi delle query sono diverse, una query che ha esito positivo in udmSearch può non riuscire con un errore 400 INVALID_ARGUMENT in un'esclusione.

Le sezioni seguenti descrivono le regole di sintassi per il campo findingsRefinements.query:

Per convalidare una query di esclusione prima del deployment, chiama l'endpoint testFindingsRefinement anziché udmSearch.

Grammatica booleana

Il campo findingsRefinements.query richiede una sintassi booleana in forma normale congiuntiva (CNF) piatta. Nella CNF semplice, unisci una o più clausole con AND e ogni clausola tra parentesi contiene solo confronti OR semplici senza parentesi nidificate.

Il campo findingsRefinements.query supporta le seguenti strutture booleane:

  • Un singolo confronto o una sequenza piatta di confronti OR, ad esempio field_a = "val_1" OR field_b = "val_2".
  • Più clausole unite da AND (o spazio vuoto implicito AND), dove ogni clausola tra parentesi contiene solo confronti OR semplici. Ad esempio field_a = "val_1" AND (field_b = "val_2" OR field_c = "val_3").
  • Aggiungi il prefisso NOT prima di un singolo confronto, ad esempio NOT principal.hostname = "scanner.example.com".

Il campo findingsRefinements.query rifiuta le seguenti strutture booleane con un errore 400 INVALID_ARGUMENT:

  • Parentesi nidificate, ad esempio A AND (B OR (C AND D)).
  • Operatori logici OR tra clausole tra parentesi, ad esempio (A AND B) OR (C AND D).

Puoi riscrivere la logica nidificata come A OR (B AND C) in CNF piatta come (A OR B) AND (A OR C). Per condizioni OR-of-AND complesse in cui l'espansione CNF diventa troppo grande, crea risorse FindingsRefinement separate per ogni ramo AND.

Operatori e valori letterali supportati

La tabella seguente elenca ogni funzionalità di query, il relativo supporto in findingsRefinements.query e un esempio o un'alternativa validi:

Funzionalità Assistenza in findingsRefinements.query Esempio o alternativa
Operatori di confronto Supporta =, !=, <, <=, > e >=. I confronti di stringhe, espressioni regolari e mappe supportano = e !=. metadata.log_type = "WINDOWS_SYSMON"
Espressioni regolari Supporta espressioni regolari delimitate da barre (/.../) nei campi di stringhe e mappe. principal.hostname = /^scanner-[0-9]+\.example\.com$/
Modificatore senza distinzione tra maiuscole e minuscole Supporta nocase nei confronti di stringhe ed espressioni regolari. I campi enum non supportano nocase. principal.user.userid = "admin" nocase
Valori letterali Supporta stringhe tra virgolette doppie, numeri interi, numeri con virgola mobile, valori booleani (true o false) e valori letterali byte base64 (b"..."). security_result.about.file.sha256 = "e3b0c4..."
Corrispondenza dell'intervallo CIDR Supporta la parola chiave CIDR_RANGE nei campi degli indirizzi IP. principal.ip = CIDR_RANGE "192.0.2.0/24"
Funzioni YARA-L Non supporta le funzioni YARA-L, come net.ip_in_range_cidr o re.regex. Utilizza CIDR_RANGE per le subnet IP o /.../ per le espressioni regolari.
Elenchi di riferimento e tabelle di dati Non supporta l'elenco di riferimento (%list_name) o le ricerche nelle tabelle di dati nelle query di esclusione. Enumera i valori con confronti OR o outcomeFilters semplici.

Campi UDM supportati e limiti di profondità del percorso

Il campo findingsRefinements.query applica le seguenti regole per i campi UDM:

  • I percorsi dei campi supportano un massimo di 6 segmenti separati da punti, ad esempio target.process.file.sha256 (4 segmenti) o target.resource.attribute.labels["env"] (4 segmenti).
  • I percorsi dei campi con 7 o più segmenti separati da punti non superano la convalida e generano un errore 400 INVALID_ARGUMENT (Not a valid field path). Ad esempio, target.process.file.signature_info.sigcheck.signers.name ha 7 segmenti ed è stato rifiutato.
  • I campi foglia supportano i tipi di dati scalari (string, numeri interi, numeri in virgola mobile e bool), enum e bytes.
  • I campi mappa e Label supportano le ricerche con chiavi tra parentesi, ad esempio additional.fields["key"] = "value" e target.resource.attribute.labels["project"] = "prod".
  • Gli alias di ricerca UDM raggruppati, come ip, hostname, user e hash, sono supportati insieme ai percorsi completi dei campi degli eventi UDM.
  • I percorsi del grafo delle entità (graph.*) e i campi message senza chiave non sono supportati nelle query di esclusione.

Limitazioni

  • Tutte le esclusioni (con o senza filtri dei risultati) devono specificare un campo query. Per creare un'esclusione utilizzando solo il campo outcomeFilters, includi i campi FindingsRefinement obbligatori e imposta il campo query su un'espressione regolare match-all:

    {
      "displayName": "Exclusion with only outcome filters",
      "type": "DETECTION_EXCLUSION",
      "query": "principal.hostname = /.*/",
      "outcomeFilters": [
        {
          "outcome_variable": "ip",
          "outcome_value": "127.0.0.1",
          "outcome_filter_operator": "EQUAL"
        }
      ]
    }
    

    L'espressione regolare corrisponde a qualsiasi nome host. Pertanto, questa query corrisponde a tutti i rilevamenti. Di conseguenza, il filtro effettivo è determinato esclusivamente dai filtri dei risultati.

  • Le esclusioni non supportano una configurazione della durata (TTL). Tuttavia, puoi creare un TTL una tantum calcolando la data e l'ora di scadenza specifiche e aggiungendo una condizione di timestamp nella definizione di esclusione. Ad esempio, per impostare la scadenza di un'esclusione il 1° gennaio 2026 alle ore 00:00 UTC (1767225600), specifica la query come segue:

    {
      "displayName": "Exclusion with expiration timestamp",
      "type": "DETECTION_EXCLUSION",
      "query": "metadata.event_timestamp.seconds < 1767225600",
      "outcomeFilters": [
        {
          "outcome_variable": "ip",
          "outcome_value": "127.0.0.1",
          "outcome_filter_operator": "EQUAL"
        }
      ]
    }
    

    Includi gli altri campi FindingsRefinement obbligatori e i filtri dei risultati in base alle tue esigenze. L'esempio precedente conferma che vengono soppressi solo i rilevamenti creati da eventi con un timestamp precedente al 1° gennaio 2026 alle ore 00:00 UTC (1767225600).

    Nota: questo potrebbe non essere visualizzato correttamente nella finestra Modifica esclusioni dell'interfaccia utente perché supporta solo i campi string.

  • Regole composite: non applicare un'esclusione di regola direttamente a una regola composita. Devi applicare l'esclusione alle regole di base sottostanti che alimentano la regola composita. Questo perché le esclusioni delle regole vengono valutate in base ai campi UDM (come principal.user.userid), ma le regole composite vengono attivate in base ad altri rilevamenti anziché ai campi UDM. Se applichi un'esclusione di regola direttamente a una regola composita, l'esclusione non corrisponderà e l'evento non verrà escluso.

    Per trovare la regola di base, puoi esaminare la definizione della regola composita nella console Google SecOps (in Content Hub > Rilevamenti predefiniti) e rivedere la sezione events: della logica YARA-L per identificare i nomi delle regole di base.

  • Sintassi delle query e profondità dei campi: le query di esclusione devono utilizzare la sintassi booleana della forma normale congiuntiva (CNF) piatta e i percorsi dei campi UDM con un massimo di 6 segmenti separati da punti. Per saperne di più, consulta Sintassi delle query e regole dei campi.

  • Regole personalizzate: non applicare un'esclusione di regola a una regola personalizzata. Le esclusioni delle regole si applicano solo alle regole selezionate e ai set di regole selezionate che utilizzano i campi curatedRules e curatedRuleSets. Se includi rules in detectionExclusionApplication, l'API ignora il campo senza applicare l'esclusione. Per eliminare gli avvisi dalle regole personalizzate, aggiungi la logica di esclusione alla definizione della regola YARA-L o utilizza le tabelle di dati per gestire gli elenchi di esclusione in più regole. Per ulteriori informazioni, consulta Filtra i dati di eventi ed entità UDM utilizzando una tabella di dati e Esempi di anti-join sinistro nelle regole.

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