Gestire l'esclusione delle regole utilizzando l'API

Supportato in:

Google secops SIEM

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 Unified Data Model (UDM) per impedire che rilevamenti specifici generino avvisi. Identificando attività note o sicure, questi filtri eliminano il rumore non necessario nella dashboard.

Crea 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 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

Sostituisci quanto segue:

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

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la posizione 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 vengono 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 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 all'interno dell'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 (i filtri di query e risultati). Il nome (ID) della risorsa viene utilizzato per le operazioni successive sull'esclusione

Accedere 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

Sostituisci quanto segue:

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

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la posizione 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 insieme di regole

Devi applicare l'esclusione a regole specifiche o a insiemi di regole selezionati. Quando applichi l'esclusione a una regola o a un insieme di regole, viene creata una risorsa FindingsRefinementDeployment. Puoi utilizzare questa risorsa per determinare le regole personalizzate, le regole curate o i set di regole curate che si applicano alla risorsa FindingsRefinement. Puoi quindi specificare il parametro update_mask nella richiesta API per indicare quali campi di FindingsRefinementDeployment 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'ID progetto Google Cloud .

LOCATION: la posizione 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 insieme di regole, il sistema crea una risorsa FindingsRefinementDeployment. Questa risorsa determina quali regole personalizzate, regole curate e insiemi di regole curate si applicano alla risorsa FindingsRefinement. Puoi anche includere il parametro update_mask nella richiesta API per specificare i campi in FindingsRefinementDeployment da aggiornare.

Accedi al deployment per l'esclusione

Dopo aver creato o aggiornato un'esclusione, utilizza questo endpoint per verificare a quali regole o insiemi di regole viene implementata l'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'ID progetto Google Cloud .

LOCATION: la posizione 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

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

PROJECT_ID: l'ID progetto Google Cloud .

LOCATION: la posizione 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.

Elenco di tutti i deployment di esclusione

Utilizza questo endpoint per ottenere l'elenco delle risorse FindingsRefinement create all'interno della tua 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'ID progetto Google Cloud .

LOCATION: la posizione 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 esclusioni.

Testare un'esclusione utilizzando l'API

Questo endpoint testa l'esclusione rispetto ai rilevamenti delle regole e dei set di regole specificati, quindi ne convalida l'efficacia nella soppressione dei rilevamenti indesiderati. L'interfaccia utente utilizza i rilevamenti degli ultimi 30 giorni 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'ID progetto Google Cloud .

LOCATION: la posizione 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 nel sopprimere i rilevamenti che non dovrebbero 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 solo con 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 tutte le rilevazioni. Di conseguenza, il filtraggio effettivo è determinato esclusivamente dai filtri sui risultati.
Le esclusioni non supportano una configurazione della durata (TTL). Tuttavia, puoi creare un TTL una tantum calcolando la data di scadenza specifica e aggiungendo una condizione di timestamp nella definizione dell'esclusione. Ad esempio, per impostare un'esclusione che scada 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 soppressi solo i rilevamenti creati da eventi con un timestamp precedente alla fine dell'anno.

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

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