Gérer les règles unifiées avec l'API Rules
L'API Rules fournit des points de terminaison programmatiques pour gérer les règles personnalisées et organisées. Ce document explique comment utiliser l'API Rules pour gérer les règles personnalisées et organisées de manière programmatique.
Utilisez l'API Rules pour effectuer les tâches suivantes :
Rechercher et lister les règles : exécutez des recherches structurées, triez les résultats et récupérez les ressources de règles développées.
Afficher les détails des règles organisées : récupérez les métadonnées en lecture seule, les tags appliqués et la logique de texte brut pour les règles créées par Google.
Modifier par lot les configurations de règles : mettez à jour de manière synchrone les états actifs, les états d'alerte, les états d'archivage et les attributions de tags pour plusieurs règles.
Rechercher des règles à l'aide de la liste des règles
La méthode rules.list est compatible avec les ressources de règles développées et la recherche structurée.
Pour interroger ces ressources détaillées, utilisez l'une des vues suivantes :
CONFIG_ONLYTRENDS
Les deux vues fournissent des informations développées, y compris les suivantes :
Informations sur le déploiement des règles (activation des règles actives, activation des alertes, état archivé, état d'exécution)
Tags de règles associés
Accès aux ressources de règles organisées dans la vue
CONFIG_ONLYTaille de page plus importante de 5 000 résultats dans la vue
CONFIG_ONLYFonctionnalités de recherche structurée robustes
Triez les résultats de recherche sur les champs de ressources de règles à l'aide de order_by dans la requête rules.list. Les champs de règles suivants sont compatibles :
alerting_enabledarchivedauthorcreate_timedisplay_nameexecution_statelive_mode_enabledrevision_create_timerule_idrule_ownerseveritytypeupdate_time
Exemple de requête :
HTTP
GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=archived%3Dfalse&pageSize=100&pageToken=&view=TRENDS
Exemple de réponse :
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"
}
]
}
Afficher les détails des règles organisées à l'aide de getRule et listRules
rules.getRule et rule.listRules permettent de récupérer les détails des règles organisées.
Les réponses rule.listRules peuvent être filtrées pour ne contenir que les règles organisées à l'aide du
rule_owner: "GOOGLE" filtre. Pour en savoir plus sur l'utilisation du filtre rule_owner, consultez la section Syntaxe de recherche de règles.
Exemple de requête listRules pour lire une règle organisée :
HTTP
GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules?filter=rule_owner%3A%22GOOGLE%22pageSize=1&view=TRENDS
Exemple de réponse :
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"
}
]
}
La méthode rule.getRule permet de récupérer une règle organisée à l'aide de son nom de ressource.
Exemple de requête getRule pour récupérer des règles organisées :
HTTP
GET https://chronicle.googleapis.com/v1alpha/projects/<ID>/locations/us/instances/<ID>/rules/ur_e34bf150-6cfb-494c-ad9d-ec8f7216a03c?view=BASIC
Exemple de réponse :
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"
}
]
}
Modifier par lot la configuration des règles avec modifyRules
La méthode rules.modifyRules est compatible avec la mise à jour groupée suivante des règles personnalisées et organisées :
Mettre à jour l'état des règles actives
Mettre à jour l'état des alertes
Mettre à jour les tags appliqués
Mettre à jour l'état d'archivage (pour les règles personnalisées uniquement)
Les mises à jour par lot sont exécutées de manière synchrone et indépendante. Le processus n'est pas atomique et se poursuit malgré les échecs individuels. Les échecs partiels sont détaillés dans le champ failed_requests, une carte où la clé représente l'index de la requête ayant échoué et la valeur indique la raison de l'échec. Les mises à jour réussies sont documentées dans le champ rule_updates, où le résultat de chaque requête est placé à l'index correspondant du lot d'origine.
Exemple de requête 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
}
}
]
}
Exemple de réponse :
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 },
{}
]
}
Consignes pour la mise à jour des règles organisées
Lorsque vous modifiez l'état actif ou d'alerte des règles organisées, tenez compte des points suivants :
Contrôle indépendant : vous pouvez gérer l'état d'une règle indépendamment de la règle parente. Si l'état d'une règle diffère de la règle parente, votre paramètre personnalisé persiste jusqu'à la prochaine mise à jour de la règle parente.
Exigence d'autorisation : vous ne pouvez mettre à jour ces états que si votre instance est activement autorisée à utiliser le pack de règles parent.
Consignes pour la mise à jour des tags
Vous pouvez associer des tags à vos règles à l'aide des méthodes suivantes :
Incluez des codes T MITRE (tactique ou technique) dans les méta-champs
tactic,techniqueoumitre_ttpdu texte de la règle.Spécifiez les noms de ressources de tag complets dans le méta-champ
tagsdu texte de la règle.Spécifiez les noms de ressources de tag complets à l'aide des requêtes d'API
ModifyRule.
L'API ModifyRules est compatible avec les tags MITRE tactic et technique. Tous les tags fournis dans une mise à jour de l'API écrasent les tags existants, à l'exception de ceux déduits directement du texte de la règle.
Les tags MITRE tactic gérés par Google utilisent le préfixe d'espace de noms google.mitre.tactic.
Exemple de nom de ressource complet pour le tag de tactique TA0001 :
projects/11344677023/locations/eu/instances/e902a911-16e3-4c39-978d-e25234232492/google.mitre.tactic.TA0001
Vous avez encore besoin d'aide ? Obtenez des réponses auprès des membres de la communauté et des professionnels Google SecOps.