Einheitliche Regeln mit der Rules API verwalten

Unterstützt in:

Google SecOps SIEM

Die Rules API bietet programmatische Endpunkte zum Verwalten von benutzerdefinierten und kuratierten Regeln. In diesem Dokument wird beschrieben, wie Sie die Rules API verwenden, um benutzerdefinierte und kuratierte Regeln programmatisch zu verwalten.

Mit der Rules API können Sie die folgenden Aufgaben ausführen:

Regeln suchen und auflisten:Führen Sie strukturierte Suchvorgänge aus, sortieren Sie Ergebnisse und rufen Sie erweiterte Regelressourcen ab.
Details zu kuratierten Regeln ansehen:Ruft schreibgeschützte Metadaten, angewendete Tags und die Rohtextlogik für von Google erstellte Regeln ab.
Regelkonfigurationen im Batchverfahren ändern:Sie können den Live-Status, den Benachrichtigungsstatus, den Archivierungsstatus und die Tag-Zuweisungen für mehrere Regeln gleichzeitig aktualisieren.

Regeln mit Listenregeln suchen

Die rules.list-Methode unterstützt erweiterte Regelressourcen und die strukturierte Suche. Verwenden Sie eine der folgenden Ansichten, um diese detaillierten Ressourcen abzufragen:

CONFIG_ONLY
TRENDS

Beide Ansichten enthalten erweiterte Informationen, darunter:

Informationen zur Regelbereitstellung (Aktivierung von Live-Regeln, Aktivierung von Benachrichtigungen, archivierter Status, Ausführungsstatus)
Zugeordnete Regel-Tags
Zugriff auf ausgewählte Regelressourcen in der Ansicht CONFIG_ONLY
Größere Seitengröße von 5.000 Ergebnissen in der Ansicht CONFIG_ONLY
Effiziente strukturierte Suchfunktionen.

Sortieren Sie die Suchergebnisse anhand der Felder der Regelressource mit order_by in der rules.list-Anfrage. Die folgenden Regelfelder werden unterstützt:

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

Beispielanfrage:

HTTP

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

Beispielantwort:

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"
    }
  ]
}

Details zu kuratierten Regeln mit „getRule“ und „listRules“ ansehen

Mit rules.getRule und rule.listRules können Details für kuratierte Regeln abgerufen werden. rule.listRules-Antworten können mit dem Filter rule_owner: "GOOGLE" so gefiltert werden, dass nur kuratierte Regeln angezeigt werden. Weitere Informationen zur Verwendung des Filters rule_owner finden Sie im Abschnitt zur Syntax für die Regelsuche.

Beispiel für eine „listRules“-Anfrage zum Lesen einer zusammengestellten Regel:

HTTP

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

Beispielantwort:

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"
    }
  ]
}

Mit der Methode „rule.getRule“ kann eine kuratierte Regel anhand ihres Ressourcennamens abgerufen werden.

Beispiel für eine „getRule“-Anfrage zum Abrufen kuratierter Regeln:

HTTP

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

Beispielantwort:

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"
    }
  ]
}

Regelkonfigurationen mit „modifyRules“ im Batch ändern

Die Methode rules.modifyRules unterstützt die folgenden Batchaktualisierungen für benutzerdefinierte und kuratierte Regeln:

Status von Live-Regeln aktualisieren
Benachrichtigungsstatus aktualisieren
Angewendete Tags aktualisieren
Archivierungsstatus aktualisieren (nur für benutzerdefinierte Regeln)

Batch-Updates werden synchron und unabhängig ausgeführt. Der Prozess ist nicht atomar und wird trotz einzelner Fehler fortgesetzt. Teilfehler werden im Feld failed_requests detailliert beschrieben. Dabei handelt es sich um eine Map, in der der Schlüssel den Index der fehlgeschlagenen Anfrage und der Wert den Grund für den Fehler angibt. Erfolgreiche Aktualisierungen werden im Feld rule_updates dokumentiert. Das Ergebnis für jede Anfrage wird an der entsprechenden Indexposition aus dem ursprünglichen Batch platziert.

Beispiel für eine modifyRules-Anfrage:

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
      }
    }
  ]
}

Beispielantwort:

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 },
    {}
  ]
}

Richtlinien zum Aktualisieren kuratierter Regeln

Wenn Sie die Live- oder Benachrichtigungsstatus für kuratierte Regeln ändern, sollten Sie Folgendes beachten:

Unabhängige Steuerung:Sie können den Status einer Regel unabhängig von der Richtlinie des übergeordneten Regelsets verwalten. Wenn der Status einer Regel von der übergeordneten Richtlinie abweicht, bleibt Ihre benutzerdefinierte Einstellung bis zur nächsten Aktualisierung der übergeordneten Richtlinie erhalten.
Berechtigungsanforderung:Sie können diese Status nur aktualisieren, wenn Ihre Instanz aktiv für das übergeordnete Regelpaket berechtigt ist.

Richtlinien zum Aktualisieren von Tags

Sie haben folgende Möglichkeiten, Tags mit Ihren Regeln zu verknüpfen:

Fügen Sie im Regeltext MITRE-T-Codes (Taktik oder Technik) in die Metafelder tactic, technique oder mitre_ttp ein.
Geben Sie die vollständigen Ressourcennamen der Tags im Metafeld tags des Regeltexts an.
Geben Sie vollständige Tag-Ressourcennamen mit ModifyRule-API-Anfragen an.

Die ModifyRules API unterstützt die MITRE-Tags tactic und technique. Alle in einer API-Aktualisierung angegebenen Tags überschreiben vorhandene Tags, mit Ausnahme der Tags, die direkt aus dem Regeltext abgeleitet werden.

Von Google verwaltete MITRE-tactic-Tags verwenden das Namespace-Präfix google.mitre.tactic.

Beispiel für einen vollständigen Ressourcennamen für das Taktik-Tag TA0001:


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

Benötigen Sie weitere Hilfe? Antworten von Community-Mitgliedern und Google SecOps-Experten erhalten