Gestire le regole unificate con l'API Rules

Supportato in:

Google SecOps SIEM

L'API Rules fornisce endpoint programmatici per gestire regole personalizzate e curate. Questo documento descrive come utilizzare l'API Rules per gestire le regole personalizzate e curate in modo programmatico.

Utilizza l'API Rules per eseguire le seguenti attività:

Cerca ed elenca le regole:esegui ricerche strutturate, ordina i risultati e recupera le risorse delle regole espanse.
Visualizza i dettagli delle regole curate:recupera i metadati di sola lettura, i tag applicati e la logica del testo non elaborato per le regole create da Google.
Modifica in batch delle configurazioni delle regole:aggiorna in modo sincrono gli stati live, gli stati di avviso, gli stati di archiviazione e le assegnazioni di tag in più regole.

Cercare regole utilizzando le regole di elenco

Il metodo rules.list supporta risorse di regole espanse e la ricerca strutturata. Per eseguire query su queste risorse dettagliate, utilizza una delle seguenti visualizzazioni:

CONFIG_ONLY
TRENDS

Entrambe le visualizzazioni forniscono informazioni ampliate, tra cui:

Informazioni sul deployment delle regole (attivazione delle regole live, attivazione degli avvisi, stato di archiviazione, stato di esecuzione)
Tag delle regole associati
Accesso alle risorse delle regole curate nella visualizzazione CONFIG_ONLY
Dimensioni della pagina più grandi di 5000 risultati nella visualizzazione CONFIG_ONLY
Funzionalità di ricerca strutturata avanzate.

Ordina i risultati di ricerca nei campi delle risorse della regola utilizzando order_by nella richiesta rules.list. Sono supportati i seguenti campi delle regole:

alerting_enabled
archived
author
create_time
display_name
execution_state
live_mode_enabled
revision_create_time
rule_id
rule_owner
severity
type
update_time

Esempio di richiesta:

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=archived%3Dfalse&pageSize=100&pageToken=&view=TRENDS

Esempio di risposta:

JSON

{
  "rules": [
    {
      "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_fd3fe28c-2d7b-4f7e-9fca-4fdd6029d228",

      "revisionId": "v_1719339990_701951000",

      "displayName": "SomaMaglevProberRule",

      "author": "test@google.com",

      "metadata": {
        "description": "enabled live rule used for maglev rules latency prober"

      },

      "createTime": "2024-06-25T18:26:30.701951Z",

      "revisionCreateTime": "2024-06-25T18:26:30.701951Z",

      "type": "SINGLE_EVENT",

      "etag": "CNaX7LMGEJjY284C",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "CUSTOMER",

      "alertingEnabled": true,

      "liveModeEnabled": true,

      "runFrequency": "LIVE",

      "currentDayDetectionCount": 10000,

      "executionState": "DEFAULT"

    },
    {
      "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_fbf56bf1-ea5f-4b5b-bbe9-e91e13f3b3b3",

      "revisionId": "v_1696452642_197471000",

      "displayName": "LoadTestingRule",

      "author": "loadtesting@google.com",

      "createTime": "2023-10-04T20:50:42.197471Z",

      "revisionCreateTime": "2023-10-04T20:50:42.197471Z",

      "type": "SINGLE_EVENT",

      "etag": "CKKg96gGEJjWlF4=",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "CUSTOMER",

      "alertingEnabled": true,

      "liveModeEnabled": true,

      "runFrequency": "LIVE",

      "executionState": "DEFAULT"
    }
  ]
}

Visualizzare i dettagli delle regole curate utilizzando getRule e listRules

rules.getRule e rule.listRules supportano il recupero dei dettagli per le regole curate. Le risposte rule.listRules possono essere filtrate in modo da includere solo le regole curate utilizzando il filtro rule_owner: "GOOGLE". Ulteriori dettagli sull'utilizzo del filtro rule_owner sono disponibili nella sezione Sintassi di ricerca delle regole.

Esempio di richiesta listRules per leggere una regola selezionata:

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=rule_owner%3A%22GOOGLE%22pageSize=1&view=TRENDS

Esempio di risposta:

JSON

{
  "rules": [
    {
      "name": "projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c",

      "revisionId": "v_1755272664_971453000",

      "displayName": "Example Curated Rule",

      "severity": {
        "displayName": "Info"
      },

      "metadata": {
        "technique": "T1136.003",
        "rule_name": "Example Curated Rule",
        "description": "Example Curated Rule Description",
        "tactic": "TA0003"
      },

      "createTime": "2024-10-02T18:10:43.647897Z",

      "revisionCreateTime": "2025-08-15T15:44:24.971453Z",

      "type": "SINGLE_EVENT",

      "etag": "CNir/cQGEMjknM8D",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "GOOGLE",

      "tags": [
        "google.mitre.tactic.ta0003",
        "google.mitre.technique.t1136.003"
      ],

      "executionState": "DEFAULT"
    }
  ]
}

Il metodo rule.getRule supporta il recupero di una regola curata utilizzando il relativo nome risorsa.

Esempio di richiesta getRule per recuperare le regole curate:

HTTP

GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c?view=BASIC

Esempio di risposta:

JSON

{
  "rules": [
    {
      "name": "projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c",

      "revisionId": "v_1755272664_971453000",

      "displayName": "Example Curated Rule",

      "severity": {
        "displayName": "Info"
      },

      "metadata": {
        "technique": "T1136.003",
        "rule_name": "Example Curated Rule",
        "description": "Example curated rule description",
        "tactic": "TA0003"
      },

      "createTime": "2024-10-02T18:10:43.647897Z",

      "revisionCreateTime": "2025-08-15T15:44:24.971453Z",

      "text": "Example curated rule text",

      "type": "SINGLE_EVENT",

      "etag": "CNir/cQGEMjknM8D",

      "nearRealTimeLiveRuleEligible": true,

      "ruleOwner": "GOOGLE",

      "tags": [
        "google.mitre.tactic.ta0003",
        "google.mitre.technique.t1136.003"
      ],

      "executionState": "DEFAULT"
    }
  ]
}

Modifica in batch della configurazione delle regole con modifyRules

Il metodo rules.modifyRules supporta il seguente aggiornamento batch per le regole personalizzate e curate:

Aggiornare lo stato della regola pubblicata
Aggiorna stato avvisi
Aggiorna i tag applicati
Aggiorna lo stato di archiviazione (solo per le regole personalizzate)

Gli aggiornamenti batch vengono eseguiti in modo sincrono e indipendente. Il processo non è atomico e continua nonostante i singoli errori. Gli errori parziali sono descritti in dettaglio nel campo failed_requests, una mappa in cui la chiave rappresenta l'indice della richiesta non riuscita e il valore fornisce il motivo dell'errore. Gli aggiornamenti riusciti sono documentati nel campo rule_updates, dove il risultato di ogni richiesta viene inserito nell'indice corrispondente del batch originale.

Esempio di richiesta modifyRules:

HTTP

POST https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules:modifyRules

JSON

{
  "parent": "projects/<ID>/locations/us/instances/<ID>",
  "requests": [
    {
      "update_mask": "liveModeEnabled",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_aaaaaaaaaaaaaaaaaaaaaaa",
        "liveModeEnabled": true
      }
    },
    {
      "update_mask": "alertingEnabled",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ur_zzzzzzzzzzzzzzzzzzzzz",
        "alertingEnabled": false
      }
    },
    {
      "update_mask": "tags",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_bbbbbbbbbbbbbbbbbbbbbbb",
        "tags": [
          "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.tactic.TA0043",
          "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.technique.T1595"
        ]
      }
    },
    {
      "update_mask": "archived",
      "rule": {
        "name": "projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/rules/ru_cccccccccccccccccccccc",
        "archived": true
      }
    }
  ]
}

Esempio di risposta:

JSON

{
  "failed_requests": {
    "0": {
      "code": 5,
      "message": "rule is already enabled"
    },
    "3": {
      "code": 5,
      "message": "rule is already archived"
    }
  },
  "rule_updates": [
    {},
    { "alerting_state_updated": true },
    { "tagsUpdated": true },
    {}
  ]
}

Linee guida per l'aggiornamento delle regole curate

Quando modifichi gli stati live o di avviso per le regole curate, tieni presente quanto segue:

Controllo indipendente:puoi gestire lo stato di una regola indipendentemente dalle norme del relativo insieme di regole principale. Se lo stato di una regola si discosta dal criterio principale, l'impostazione personalizzata viene mantenuta fino al successivo aggiornamento del criterio principale.
Requisito di diritto: puoi aggiornare questi stati solo se la tua istanza ha diritto attivo al pacchetto di regole principale.

Linee guida per l'aggiornamento dei tag

Puoi associare tag alle regole utilizzando i seguenti metodi:

Includi i codici T (tattica o tecnica) MITRE nei campi meta tactic, technique o mitre_ttp nel testo della regola.
Specifica i nomi completi delle risorse tag nel campo meta tags del testo della regola.
Specifica i nomi completi delle risorse dei tag utilizzando le richieste API ModifyRule.

L'API ModifyRules supporta i tag MITRE tactic e technique. Tutti i tag forniti in un aggiornamento dell'API sovrascrivono i tag esistenti, ad eccezione di quelli dedotti direttamente dal testo della regola.

I tag MITRE tactic gestiti da Google utilizzano il prefisso dello spazio dei nomi google.mitre.tactic.

Esempio di nome completo della risorsa per il tag tattica TA0001:


projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.tactic.TA0001

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