Gestire le regole unificate con l'API Rules
L'API Rules fornisce endpoint programmatici per gestire sia le regole personalizzate sia quelle 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à:
Cercare ed elencare le regole: esegui ricerche strutturate, ordina i risultati e recupera le risorse delle regole espanse.
Visualizzare 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.
Modificare in batch le 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 le regole utilizzando listRules
Il metodo rules.list supporta le risorse delle regole espanse e la ricerca strutturata.
Per eseguire query su queste risorse dettagliate, utilizza una delle seguenti visualizzazioni:
CONFIG_ONLYTRENDS
Entrambe le visualizzazioni forniscono informazioni espanse, 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_ONLYDimensioni della pagina maggiori di 5000 risultati nella visualizzazione
CONFIG_ONLYFunzionalità di ricerca strutturata robuste.
Ordina i risultati di ricerca nei campi delle risorse delle regole utilizzando order_by nella richiesta rules.list. Sono supportati i seguenti campi delle regole:
alerting_enabledarchivedauthorcreate_timedisplay_nameexecution_statelive_mode_enabledrevision_create_timerule_idrule_ownerseveritytypeupdate_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
I metodi rules.getRule e rule.listRules supportano il recupero dei dettagli delle 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 relativa alla sintassi di ricerca delle regole.
Esempio di richiesta listRules per leggere una regola curata:
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"
}
]
}
Modificare in batch la configurazione delle regole con modifyRules
Il metodo rules.modifyRules supporta il seguente aggiornamento batch per le regole personalizzate e curate:
Aggiornare lo stato delle regole live
Aggiornare lo stato degli avvisi
Aggiornare i tag applicati
Aggiornare 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, in cui 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 dalla relativa policy del set di regole principale. Se lo stato di una regola è diverso dalla policy principale, l'impostazione personalizzata rimane valida fino al successivo aggiornamento della policy principale.
Requisito di autorizzazione: puoi aggiornare questi stati solo se la tua istanza è autorizzata attivamente al pacchetto di regole principale.
Linee guida per l'aggiornamento dei tag
Puoi associare i tag alle regole utilizzando i seguenti metodi:
Includi i codici T MITRE (tattica o tecnica) nei campi meta
tactic,techniqueomitre_ttpnel testo della regola.Specifica i nomi completi delle risorse dei tag nel campo meta
tagsdel testo della regola.Specifica i nomi completi delle risorse dei tag utilizzando le richieste API
ModifyRule.
L'API ModifyRules supporta i tag tactic e technique MITRE. 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 gestiti da Google tactic utilizzano il prefisso dello spazio dei nomi google.mitre.tactic.
Esempio di nome risorsa completo per il tag tattico 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.