ניהול כללים מאוחדים באמצעות Rules API

נתמך ב:

ממשק Rules API מספק נקודות קצה (endpoints) לתכנות כדי לנהל כללים בהתאמה אישית וכללים שנבחרו בקפידה. במאמר הזה מוסבר איך להשתמש ב-Rules API כדי לנהל כללים מותאמים אישית וכללים שנבחרו באופן פרוגרמטי.

אפשר להשתמש ב-Rules API כדי לבצע את המשימות הבאות:

  • חיפוש ורשימת כללים: ביצוע חיפושים מובְנים, מיון תוצאות ואחזור משאבי כללים מורחבים.

  • הצגת פרטים של כללים שנאספו: אפשר לאחזר מטא נתונים לקריאה בלבד, תגים שהוחלו ולוגיקה של טקסט גולמי עבור כללים שנכתבו על ידי Google.

  • שינוי הגדרות של כללים בקבוצה: עדכון סינכרוני של מצבים פעילים, מצבי התראה, סטטוסים של ארכיונים והקצאות של תגים בכמה כללים.

חיפוש כללים באמצעות כללי רשימה

השיטה rules.list תומכת במשאבי כללים מורחבים ובחיפוש מובנה. כדי לשלוח שאילתות למשאבים המפורטים האלה, משתמשים באחד מהתצוגות הבאות:

  • CONFIG_ONLY

  • TRENDS

שתי התצוגות מספקות מידע מורחב, שכולל את הפרטים הבאים:

  • מידע על פריסת הכלל (הפעלת כלל פעיל, הפעלת התראות, מצב בארכיון, מצב הפעלה)

  • תגי כללים משויכים

  • גישה למשאבי כללים שנאספו בתצוגה CONFIG_ONLY

  • גודל דף גדול יותר של 5,000 תוצאות בתצוגה CONFIG_ONLY

  • יכולות חיפוש מובנה חזקות.

כדי למיין את תוצאות החיפוש בשדות של משאב הכלל, משתמשים ב-order_by בבקשת rules.list. השדות הבאים של כללים נתמכים:

  • alerting_enabled

  • archived

  • author

  • create_time

  • display_name

  • execution_state

  • live_mode_enabled

  • revision_create_time

  • rule_id

  • rule_owner

  • severity

  • type

  • update_time

דוגמה לבקשה:

HTTP

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

דוגמה לתגובה:

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

צפייה בפרטים של כלל שנבחר באמצעות getRule ו-listRules

הפונקציות rules.getRule ו-rule.listRules תומכות באחזור פרטים של כללים שנבחרו בקפידה. אפשר לסנן את התשובות של rule.listRules כך שיוצגו רק כללים שנבחרו באמצעות המסנן rule_owner: "GOOGLE". פרטים נוספים על השימוש במסנן rule_owner זמינים בקטע על תחביר החיפוש של כללים.

דוגמה לבקשת listRules לקריאת כלל שנבחר:

HTTP

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

דוגמה לתגובה:

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

השיטה rule.getRule תומכת באחזור של כלל שנבחר באמצעות שם המשאב שלו.

דוגמה לבקשת getRule לאחזור כללים שנבחרו:

HTTP

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

דוגמה לתגובה:

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

שינוי קבוצתי של הגדרות כללים באמצעות modifyRules

השיטה rules.modifyRules תומכת בחבילת עדכונים של כללים מותאמים אישית וכללים שנבחרו בקפידה:

  • עדכון הסטטוס של כלל בזמן אמת

  • עדכון סטטוס ההתראה

  • עדכון התגים שהוחלו

  • עדכון סטטוס הארכיון (לכללים מותאמים אישית בלבד)

עדכונים בכמות גדולה מתבצעים באופן סינכרוני ועצמאי. התהליך לא אטומי ונמשך למרות כשלים ספציפיים. פירוט של כשלים חלקיים מופיע בשדה failed_requests, שהוא מפה שבה המפתח מייצג את האינדקס של הבקשה שנכשלה והערך מספק את הסיבה לכשל. עדכונים מוצלחים מתועדים בשדה rule_updates, שבו התוצאה של כל בקשה ממוקמת באינדקס המתאים שלה מתוך קבוצת הבקשות המקורית.

בקשה 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
      }
    }
  ]
}

דוגמה לתגובה:

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

הנחיות לעדכון כללים שנבחרו בקפידה

כשמשנים את הסטטוסים של כללים שנבחרו בקפידה, צריך לקחת בחשבון את הנקודות הבאות:

  • שליטה עצמאית: אתם יכולים לנהל את הסטטוס של כלל בנפרד ממדיניות קבוצת הכללים שאליה הוא משויך. אם הסטטוס של כלל מסוים שונה מהמדיניות של ההורה, ההגדרה המותאמת אישית שלכם תישמר עד לעדכון הבא של המדיניות של ההורה.

  • דרישות זכאות: אפשר לעדכן את הסטטוסים האלה רק אם המופע שלכם זכאי באופן פעיל לחבילת הכללים של ההורה.

הנחיות לעדכון תגים

אפשר לשייך תגים לכללים באמצעות השיטות הבאות:

  • כוללים קודי T של MITRE (טקטיקה או טכניקה) בשדות המטא tactic, technique או mitre_ttp בטקסט של הכלל.

  • מציינים את שמות המשאבים המלאים של התגים בtags שדה המטא של טקסט הכלל.

  • מציינים שמות מלאים של משאבי תגים באמצעות בקשות ModifyRule API.

‫ModifyRules API תומך בתגי MITRE‏ tactic ו-technique. כל התגים שמסופקים בעדכון API מחליפים את התגים הקיימים, למעט התגים שנובעים ישירות מטקסט הכלל.

תגי MITRE tactic שמנוהלים על ידי Google משתמשים בקידומת מרחב השמות google.mitre.tactic.

דוגמה לשם מלא של משאב עבור תג הטקטיקה TA0001:


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

הבעיה עדיין לא נפתרה? קבלת תשובות מחברי הקהילה וממומחי Google SecOps.