ניהול כללים מאוחדים באמצעות 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 meta של טקסט הכלל.

  • מציינים שמות מלאים של משאבי תגים באמצעות בקשות 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.