Gérer les règles unifiées avec l'API Rules

Compatible avec :

Google SecOps SIEM

L'API Rules fournit des points de terminaison programmatiques permettant de gérer les règles personnalisées et sélectionnées. Ce document explique comment utiliser l'API Rules pour gérer les règles personnalisées et sélectionné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 sélectionné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 les configurations de règles par lot : 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 commande "list rules"

La méthode rules.list est compatible avec les ressources de règles étendues et la recherche structurée. Pour interroger ces ressources détaillées, utilisez l'une des vues suivantes :

CONFIG_ONLY
TRENDS

Les deux vues fournissent des informations détaillées, y compris les suivantes :

Informations sur le déploiement des règles (activation des règles en direct, activation des alertes, état archivé, état d'exécution)
Tags de règles associés
Accès aux ressources de règles sélectionnées dans la vue CONFIG_ONLY
Taille de page plus grande (5 000 résultats) dans la vue CONFIG_ONLY
Fonctionnalité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ègle suivants sont acceptés :

alerting_enabled
archived
author
create_time
display_name
execution_state
live_mode_enabled
revision_create_time
rule_id
rule_owner
severity
type
update_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 sélectionnées à l'aide de getRule et listRules

rules.getRule et rule.listRules permettent de récupérer les détails des règles sélectionnées. Les réponses rule.listRules peuvent être filtrées pour n'afficher que les règles sélectionnées à l'aide du filtre rule_owner: "GOOGLE". Pour en savoir plus sur l'utilisation du filtre rule_owner, consultez la section sur la syntaxe de recherche des règles.

Exemple de requête listRules pour lire une règle sélectionné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 sélectionnée à l'aide de son nom de ressource.

Exemple de requête getRule pour récupérer des règles sélectionné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 la configuration des règles par lot avec modifyRules

La méthode rules.modifyRules est compatible avec la mise à jour par lot suivante des règles personnalisées et sélectionnées :

Modifier l'état d'une règle en direct
Mettre à jour l'état des alertes
Mettre à jour les tags appliqués
Modifier l'état d'archivage (pour les règles personnalisées uniquement)

Les mises à jour groupées 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, qui est 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 modifier les règles sélectionnées

Lorsque vous modifiez l'état en direct ou d'alerte des règles sélectionné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 celui de la règle parente, votre paramètre personnalisé est conservé jusqu'à la prochaine mise à jour de la règle parente.
Exigence relative aux droits d'accès : vous ne pouvez modifier ces états que si votre instance est activement autorisée à accéder au pack de règles parent.

Consignes pour mettre à jour les tags

Vous pouvez associer des tags à vos règles à l'aide des méthodes suivantes :

Incluez les codes T MITRE (tactique ou technique) dans les champs de métadonnées tactic, technique ou mitre_ttp du texte de la règle.
Spécifiez les noms de ressources complets des tags dans le champ de métadonnées tags du texte de la règle.
Spécifiez les noms complets des ressources de tag à l'aide des requêtes d'API ModifyRule.

L'API ModifyRules est compatible avec les tags MITRE tactic et technique. Toutes les balises fournies dans une mise à jour de l'API remplacent les balises existantes, à l'exception de celles déduites 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 de membres de la communauté et de professionnels Google SecOps.