Abbiamo riorganizzato la struttura di navigazione della documentazione per allinearla direttamente ai tuoi flussi di lavoro operativi. Per ulteriori informazioni, consulta le note di rilascio e il video dimostrativo.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Gestire le esclusioni delle regole

Supportato in:

Google SecOps SIEM

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

Creare un'esclusione con filtri dei risultati

Puoi creare una nuova regola di esclusione a livello di programmazione per eliminare 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 eliminazione. 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

Sostituisci quanto segue:

REGION: la Google Cloud regione dell'istanza Google SecOps.

PROJECT_ID: l' Google Cloud ID progetto.

LOCATION: la località dell'istanza Google SecOps (spesso la stessa della 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.01",
      "outcome_filter_operator": "EQUAL"
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS"
    }
  ]
}

L'esempio mostra come definire la logica di eliminazione 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 eliminazione segue una relazione AND. La richiesta crea un'esclusione che elimina 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 altostrat.com.

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

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

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

Accedere a un'esclusione

Utilizza l'endpoint GET per:

Visualizzare 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

Sostituisci quanto segue:

REGION: la Google Cloud regione dell'istanza Google SecOps.

PROJECT_ID: l' Google Cloud ID progetto.

LOCATION: la località dell'istanza Google SecOps (spesso la stessa della 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/fr_00001111-2222-3333-4444-555566667777

Applicare un'esclusione a una regola o a un set di regole

Devi applicare l'esclusione a regole specifiche o a set di regole curati. Quando applichi l'esclusione a una regola o a un set di regole, viene creata una risorsa FindingsRefinementDeployment. Puoi utilizzare questa risorsa per determinare le regole personalizzate, le regole curate o i set di regole curati che si applicano alla risorsa FindingsRefinement. Puoi quindi specificare il parametro update_mask nella richiesta API per indicare i campi in FindingsRefinementDeployment da aggiornare.

Metodo: PATCH

Endpoint:

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

Sostituisci quanto segue:

REGION: la Google Cloud regione dell'istanza Google SecOps.

PROJECT_ID: l' Google Cloud ID progetto.

LOCATION: la località dell'istanza Google SecOps (spesso la stessa della regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

REFINEMENT_ID: l'ID univoco del perfezionamento dei risultati.

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?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"
  "enabled": true,
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...list curated rule set resource names
    ],
    "curatedRules": [
      ...list curated rule resource names
    ],
    "rules": [
      ...list rule resource names
    ],
  }
}

Quando applichi l'esclusione a una regola o a un set di regole, il sistema crea una risorsa FindingsRefinementDeployment. Questa risorsa determina le regole personalizzate, le regole curate e i set di regole curati che si applicano alla risorsa FindingsRefinement. Puoi anche includere il parametro update_mask nella richiesta API per specificare i campi in FindingsRefinementDeployment da aggiornare.

Accedere al deployment per l'esclusione

Dopo aver creato o aggiornato un'esclusione, utilizza questo endpoint per verificare le regole o i set di regole a cui è stato eseguito il deployment di questa esclusione specifica.

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 Google Cloud regione dell'istanza Google SecOps.

PROJECT_ID: l' Google Cloud ID progetto.

LOCATION: la località dell'istanza Google SecOps (spesso la stessa della 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

Elencare 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 Google Cloud regione dell'istanza Google SecOps.

PROJECT_ID: l' Google Cloud ID progetto.

LOCATION: la località dell'istanza Google SecOps (spesso la stessa della 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 più risultati simili ad altri endpoint di elenco all'interno dell'API.

Elencare tutti i deployment di esclusione

Utilizza questo endpoint per ottenere l'elenco delle risorse FindingsRefinement create all'interno dell'istanza.

Metodo: GET

Endpoint:

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

Sostituisci quanto segue:

REGION: la Google Cloud regione dell'istanza Google SecOps.

PROJECT_ID: l' Google Cloud ID progetto.

LOCATION: la località dell'istanza Google SecOps (spesso la stessa della 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 più risultati simili ad altri endpoint di elenco all'interno dell'API.
Utilizza il parametro filter per filtrare le regole o i set di regole a cui sono state applicate le esclusioni.

Testare un'esclusione utilizzando l'API

Questo endpoint testa l'esclusione rispetto ai rilevamenti delle regole e dei set di regole specificati, quindi convalida l'efficacia dell'esclusione nell'eliminazione dei rilevamenti indesiderati. L'interfaccia utente utilizza gli ultimi 30 giorni di rilevamenti per i test.

Metodo: POST

Endpoint:

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

Sostituisci quanto segue:

REGION: la Google Cloud regione dell'istanza Google SecOps.

PROJECT_ID: l' Google Cloud ID progetto.

LOCATION: la località dell'istanza Google SecOps (spesso la stessa della regione).

INSTANCE_ID: l'ID dell'istanza Google SecOps.

Esempio:

POST https://us-chronicle.googleapis.com/v1/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.01",
      "outcome_filter_operator": "EQUAL",
    },
    {
      "outcome_variable": "hostnames",
      "outcome_value": "altostrat.com",
      "outcome_filter_operator": "CONTAINS",
    },
  ]
  "interval": {
    "start_time": {
      "seconds": 1756684800, // Sep. 1 2025 00:00 UTC
    },
    "end_time": {
      "seconds": 1759276800, // Oct. 1 2025 00:00 UTC
    },
  },
  "detectionExclusionApplication": {
    "curatedRuleSets": [
      ...curated rule set resource names
    ],
    "curatedRules": [
      ...curated rule resource names
    ],
    "rules": [
      ...rule resource names
    ],
  }
}

Questo endpoint testa l'esclusione rispetto ai rilevamenti generati nelle regole e nei set di regole specificati nella richiesta. Aiuta a determinare l'efficacia dell'esclusione nell'eliminazione dei rilevamenti che non devono essere generati. Il sistema utilizza gli ultimi 30 giorni di rilevamenti come intervallo di tempo per testare le esclusioni.

Limitazioni

Tutte le esclusioni (con o senza filtri dei risultati) devono specificare un campo query. Per creare un'esclusione con solo outcomeFilters, specifica un'espressione regolare match-all.
```
  ...other fields in FindingsRefinement

  query: "principal.hostname = /.*/"

  outcomeFilters: [ your outcome filters ]
```
L'espressione regolare corrisponde a qualsiasi nome host. Pertanto, questa query corrisponde a tutti i rilevamenti. Di conseguenza, il filtro efficace è determinato esclusivamente dai filtri dei risultati.
Le esclusioni non supportano una configurazione della durata (TTL). Tuttavia, puoi creare una TTL una tantum calcolando il tempo di scadenza specifico e aggiungendo una condizione di timestamp nella definizione dell'esclusione. Ad esempio, per impostare la scadenza di un'esclusione alla fine dell'anno, specifica la query nel seguente modo:
```
  ...other fields in FindingsRefinement

  query: "metadata.event_timestamp.seconds < 1767225600" // Jan 1 2026 00:00 UTC

  outcomeFilters: [your outcome filters]
```
Questo esempio conferma che vengono eliminati solo i rilevamenti creati da eventi con un timestamp precedente alla fine dell'anno.

Nota: questa operazione potrebbe non essere visualizzata correttamente nella finestra Modifica esclusioni dell'interfaccia utente perché supporta solo i campi string.
Regole composte: le esclusioni dei campi UDM vengono valutate in base agli eventi non elaborati. Se stai tentando di escludere valori UDM specifici da una regola composta (che si attiva in base ad altri rilevamenti anziché a eventi non elaborati), devi applicare l'esclusione alle regole sottostanti fondamentali che alimentano la regola composta.

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

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