קידוד של מודול מותאם אישית ל-Security Health Analytics

בדף הזה מוסבר איך לכתוב קוד להגדרת מודול בהתאמה אישית באמצעות Common Expression Language ‏ (CEL) ו-YAML.

משתמשים ב-Google Cloud CLI כדי להעלות את ההגדרות של המודולים המותאמים אישית ל-Security Health Analytics.

בקובץ YAML, הגדרה של מודול בהתאמה אישית מורכבת מקבוצה מובנית של מאפיינים שמשמשים להגדרת הרכיבים הבאים של מודול בהתאמה אישית ב-Security Health Analytics:

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

המאפיינים הספציפיים הנדרשים והאופציונליים שמרכיבים הגדרת YAML מוסברים במאמר שלבי קידוד.

איך להימנע מיצירת גלאים מיותרים

כדי לשלוט בנפח הממצאים, מומלץ להימנע מיצירה והפעלה של מודולים שמכילים פונקציונליות מיותרת.

לדוגמה, אם יוצרים מודול מותאם אישית שבודק אם מפתחות ההצפנה לא הוחלפו אחרי 30 יום, כדאי להשבית את גלאי KMS_KEY_NOT_ROTATED של Security Health Analytics, כי הבדיקה שלו, שמשתמשת בערך של 90 יום, תהיה מיותרת.

מידע נוסף על השבתת גלאים זמין במאמר הפעלה והשבתה של גלאים.

שלבי הקידוד

אתם מקודדים את ההגדרה של מודול בהתאמה אישית עבור Security Health Analytics כסדרה של מאפייני YAML, שחלקם מכילים ביטויי CEL.

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

יוצרים קובץ טקסט עם סיומת שם הקובץ yaml.
בקובץ הטקסט, יוצרים מאפיין resource_selector ומציינים סוג משאב אחד עד חמישה סוגי משאבים שהמודול המותאם אישית יסרוק. אי אפשר לציין סוג משאב יותר מפעם אחת בהגדרה של מודול בהתאמה אישית. לדוגמה:
```
resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey
```
סוגי המשאבים שאתם מציינים צריכים להיות נתמכים על ידי Security Command Center. רשימה של סוגי המשאבים הנתמכים זמינה במאמר סוגי משאבים נתמכים.
יוצרים מאפיין predicate ומציינים ביטוי CEL אחד או יותר שבודקים מאפיינים של סוגי המשאבים שרוצים לסרוק. כל המאפיינים שמפנים אליהם בביטויי ה-CEL צריכים להופיע בהגדרת ה-API של כל סוג משאב שמציינים בקטע resource_selector.Google Cloud כדי להפעיל ממצא, הביטוי צריך להחזיר את הערך TRUE. לדוגמה, בביטוי הבא, רק ערכי rotationPeriod שגדולים מ-2592000s מפעילים ממצא.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
כדי לקבל עזרה בכתיבת ביטויי CEL, אפשר לעיין במקורות המידע הבאים:
- סוגי המשאבים שנתמכים. לוחצים על כל משאב כדי לראות את המאפיינים שאפשר להשתמש בהם בביטויי CEL.
- כתיבת ביטויי CEL
- הפניה למאפייני משאבים ומדיניות במודולים מותאמים אישית.
יוצרים description מאפיין שמסביר את נקודת החולשה או את ההגדרה השגויה שהמודול המותאם אישית מזהה. ההסבר הזה מופיע בכל מופע של ממצא כדי לעזור לחוקרים להבין את הבעיה שזוהתה. הטקסט צריך להיות מוקף במירכאות. לדוגמה:
```
description: "The rotation period of
 the identified cryptokey resource exceeds 30 days, the
 maximum rotation period that our security guidelines allow."
```
ליצור נכס recommendation שמסביר איך לפתור את הבעיה שזוהתה. ב-CLI של gcloud צריך להוסיף תו בריחה לפני תווים מסוימים, כמו מרכאות. בדוגמה הבאה מוצג שימוש בלוכסן הפוך כדי לסמן בתו בריחה (escape) כל קבוצת גרשיים:
```
recommendation: "To fix this issue go to
  https://console.cloud.google.com/security/kms. Click the key-ring that
  contains the key. Click the key. Click \"Edit rotation period\". Then
  set the rotation period to at most 30 days."
```
אם יוצרים או מעדכנים מודול מותאם אישית באמצעותGoogle Cloud המסוף, לא צריך להשתמש בתווי escape.
יוצרים נכס severity ומציינים את חומרת ברירת המחדל של הממצאים שנוצרים על ידי המודול הזה. הערכים הנפוצים במאפיין severity הם LOW,‏ MEDIUM,‏ HIGH ו-CRITICAL. לדוגמה,
```
severity: MEDIUM
```
אפשר גם ליצור מאפיין custom_output ולציין פרטים נוספים שיוחזרו עם כל ממצא. מציינים את המידע שרוצים להחזיר כצמד אחד או יותר של שם-ערך. אפשר להחזיר את הערך של מאפיין של המשאב שנסרק או מחרוזת מילולית. צריך לציין את המאפיינים בתור resource.PROPERTY_NAME. מחרוזות ליטרליות צריכות להיות מוקפות במירכאות. בדוגמה הבאה מוצגת הגדרה של custom_output שמחזירה גם ערך מאפיין, הערך של rotationPeriod במשאב CryptoKey שנסרק, וגם מחרוזת טקסט, "Excessive rotation period for CryptoKey":
```
 custom_output:
   properties:
     - name: duration
       value_expression:
         expression: resource.rotationPeriod
     - name: note
       value_expression:
         expression: "'Excessive rotation period for CryptoKey'"
```
שומרים את הקובץ במיקום שאפשר לגשת אליו באמצעות ה-CLI של gcloud.
מעלים את ההגדרה ל-Security Health Analytics באמצעות הפקודה הבאה:
```
 gcloud scc custom-modules sha create \
     --organization=organizations/ORGANIZATION_ID \
     --display-name="MODULE_DISPLAY_NAME" \
     --enablement-state="ENABLED" \
     --custom-config-from-file=DEFINITION_FILE_NAME.yaml
```
מחליפים את הערכים הבאים:
- ORGANIZATION_ID במזהה של הארגון ברמה העליונה של המודול המותאם אישית, או מחליפים את הדגל --organization באחד מהערכים --folders או --project ומציינים את המזהה של התיקייה או הפרויקט ברמה העליונה.
- MODULE_DISPLAY_NAME עם שם שיוצג כקטגוריית הממצאים כשהמודול המותאם אישית מחזיר ממצאים. השם צריך להיות באורך של 1 עד 128 תווים, להתחיל באות קטנה ולהכיל רק תווים אלפאנומריים או קווים תחתונים.
- ‫DEFINITION_FILE_NAME מחליפים בנתיב ובשם הקובץ של קובץ ה-YAML שמכיל את ההגדרה של המודול בהתאמה אישית.
מידע נוסף על עבודה עם מודולים מותאמים אישית של Security Health Analytics זמין במאמר שימוש במודולים מותאמים אישית של Security Health Analytics.

סריקת זמני האחזור של מודולים חדשים בהתאמה אישית

יצירת מודול בהתאמה אישית לא מפעילה סריקה חדשה.

הכלי Security Health Analytics לא מתחיל להשתמש במודול חדש בהתאמה אישית עד שאחד מהתנאים הבאים מתקיים:

הסריקה הראשונה של קבוצת קבצים אחרי שיוצרים את המודול בהתאמה אישית. בהתאם למועד שבו יוצרים מודול מותאם אישית בלוח הזמנים של סריקת האצווה, יכול להיות שתצטרכו להמתין עד 24 שעות לפני שמערכת Security Health Analytics תתחיל להשתמש במודול המותאם אישית.
שינוי במשאב יעד מפעיל סריקה בזמן אמת.

דוגמה להגדרה של מודול בהתאמה אישית

בדוגמה הבאה מוצגת הגדרה מלאה של מודול בהתאמה אישית שמפעיל ממצא אם הערך של המאפיין rotationPeriod של משאב cloudkms.googleapis.com/CryptoKey גדול מ-2,592,000 שניות (30 ימים). בדוגמה מוחזרים שני ערכים אופציונליים בקטע custom_output: הערך של resource.rotationPeriod והערה כמחרוזת טקסט.

בדוגמה, שימו לב לרכיבים הבאים:

סוג הנכס או המשאב שרוצים לבדוק מפורט בקטע resource_selector שבקטע resource_types.
הבדיקה שהמודול מבצע במשאבים, לוגיקת הזיהוי שלו, מוגדרת בקטע predicate שלפניו מופיע expression.
שני מאפייני מקור מותאמים אישית, duration ו-violation, מוגדרים בקטע custom_output.
ההסבר על הבעיה שזוהתה מצוין במאפיין description.
ההנחיות לפתרון הבעיה שזוהתה מפורטות במאפיין recommendation. מכיוון שגרשיים מופיעים בהנחיות, צריך להוסיף לפני כל גרשיים תו בריחה של קו נטוי הפוך.

severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."
recommendation: "To fix this issue go to
https://console.cloud.google.com/security/kms. Click the key-ring that
contains the key. Click the key. Click \"Edit rotation period\". Then
set the rotation period to at most 30 days."
resource_selector:
  resource_types:
  - cloudkms.googleapis.com/CryptoKey
predicate:
  expression: resource.rotationPeriod > duration("2592000s")
custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.rotationPeriod
    - name: violation
      value_expression:
        expression:
          "'Excessive rotation period for CryptoKey'"

הפניה למאפייני משאבים ומדיניות במודולים בהתאמה אישית

לא משנה באיזו שיטה תשתמשו כדי ליצור מודול מותאם אישית – באמצעות Google Cloud המסוף או באמצעות כתיבת ההגדרה בעצמכם – תצטרכו להיות מסוגלים לחפש את המאפיינים שאפשר להעריך במודול המותאם אישית. בנוסף, צריך לדעת איך להפנות למאפיינים האלה בהגדרת מודול בהתאמה אישית.

איך מוצאים את המאפיינים של משאב או מדיניות

המאפיינים של משאב Google Cloud מוגדרים בהגדרת ה-API של המשאב. אפשר למצוא את ההגדרה הזו בלחיצה על שם המשאב בסוגי המשאבים שנתמכים.

אפשר למצוא את המאפיינים של מדיניות במאמרי העזרה של ה-API של IAM. למידע על מאפיינים של מדיניות, אפשר לעיין במאמר בנושא מדיניות.

הפניה למאפיין משאב בהגדרה של מודול בהתאמה אישית

כשיוצרים מודול בהתאמה אישית, כל ההפניות הישירות למאפיין של משאב שנסרק חייבות להתחיל ב-resource, ואחריו כל מאפייני ההורה ולבסוף מאפיין היעד. המאפיינים מופרדים באמצעות נקודה, בסימון נקודות בסגנון JSON.

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

‫resourceName: מאחסן את השם המלא של משאב במאגר משאבי הענן, לדוגמה, //cloudresourcemanager.googleapis.com/projects/296605646631.
resource.rotationPeriod: כאשר rotationPeriod הוא מאפיין של resource.
‫resource.metadata.name: כאשר name הוא נכס משנה של metadata, שהוא נכס משנה של resource.

הפניה למאפייני מדיניות IAM

אפשר ליצור ביטויי CEL שמעריכים את מדיניות IAM של משאב על ידי הפניה למאפייני מדיניות IAM של המשאב. המאפיינים היחידים שזמינים הם קישורים ותפקידים בתוך קישורים.

כשמפנים למאפיינים של מדיניות IAM, ‏ policy הוא המאפיין ברמה העליונה.

אלה דוגמאות למאפיינים של מדיניות IAM ולאופן שבו אפשר לאחזר אותם:

‫policy.bindings, כאשר bindings הוא מאפיין של policy.
‫policy.version, כאשר version הוא מאפיין של policy.

דוגמאות נוספות זמינות במאמר דוגמאות לביטויי CEL.

מידע על המאפיינים של מדיניות

כתיבת ביטויי CEL

כשיוצרים מודול בהתאמה אישית, משתמשים בביטויי CEL כדי להעריך את המאפיינים של המשאב שנסרק. אופציונלי: אפשר גם להשתמש בביטויי CEL כדי להגדיר זוגות מותאמים אישית של name-value שמחזירים מידע נוסף עם הממצאים.

לא משנה אם אתם יוצרים מודול בהתאמה אישית במסוף Google Cloud או כותבים בעצמכם את ההגדרה של המודול בהתאמה אישית בקובץ YAML, ביטויי ה-CEL שאתם מגדירים הם זהים.

ביטויי CEL ללוגיקת זיהוי

אתם מקודדים את לוגיקת הזיהוי של מודול בהתאמה אישית באמצעות ביטויי CEL עם אופרטורים רגילים של CEL כדי להעריך את המאפיינים של המשאבים שנסרקו.

הביטויים יכולים להיות בדיקות פשוטות של ערך יחיד, או ביטויים מורכבים יותר שבודקים כמה ערכים או תנאים. בכל מקרה, הביטוי צריך להחזיר ערך בוליאני true כדי להפעיל את הממצא.

אם יוצרים מודול בהתאמה אישית במסוף Google Cloud , צריך לכתוב את הביטויים האלה בכלי לעריכת ביטויים בדף הגדרת מודול.

אם אתם מקודדים מודול בהתאמה אישית בקובץ YAML, אתם מוסיפים את הביטויים האלה במאפיין predicate.

בין אם משתמשים במסוף Google Cloud או בקובץ YAML, ביטויי CEL שמעריכים מאפייני משאבים צריכים לעמוד בכללים הבאים:

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

לדוגמה, אם מגדירים מודול מותאם אישית בשם invalid_cryptokey שבודק שני סוגי משאבים: cloudkms.googleapis.com/CryptoKey ו-cloudkms.googleapis.com/CryptoKeyVersion, אפשר לכתוב את הביטוי הבא, כי שני סוגי המשאבים CryptoKey ו-CryptoKeyVersion כוללים את המאפיין name:
```
predicate:
resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")
```
עם זאת, אי אפשר לציין את הביטוי הבא במודול המותאם אישית invalid_cryptokey כי המאפיינים importTime ו-rotationPeriod שהביטוי מעריך לא משותפים לשני סוגי המשאבים:
```
predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
```
כל הערכים מסוג enum בביטוי CEL צריכים להיות מיוצגים כמחרוזות. לדוגמה, הביטוי הבא הוא ביטוי תקין עבור סוג המשאב cloudkms.googleapis.com/CryptoKeyVersion:
```
resource.state = "PENDING_GENERATION"
```
התוצאה של ביטויי ה-CEL שאתם מגדירים במאפיין predicate חייבת להיות בוליאנית. ממצא מופעל רק אם התוצאה היא true.

מידע נוסף על CEL זמין במאמרים הבאים:

דוגמאות לביטויי CEL

בטבלה הבאה מפורטות כמה ביטויי CEL שאפשר להשתמש בהם כדי להעריך מאפייני משאבים. אפשר להשתמש בשניהם בGoogle Cloud מסוף ובקבצים של הגדרות מודולים מותאמים אישית בפורמט YAML.

סוג המשאב	הסבר	ביטוי CEL
כל משאב עם מדיניות IAM	בדיקת מדיניות IAM כדי לזהות חברים מדומיין חיצוני	`!policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))`
`cloudkms.googleapis.com/CryptoKey`	בדיקה של תקופת רוטציית מפתחות ב-Cloud KMS	`has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')`
מספר סוגי משאבים עם מדיניות אחת	בודקת אם שם המשאב מתחיל ב-`dev` או ב-`devAccess` בהתאם לסוג המשאב	`(resource.type == 'compute.googleapis.com/Disk' && resource.name.startsWith('projects/PROJECT_ID/regions/ REGION/disks/devAccess')) \|\| (resource.type == 'compute.googleapis.com/Instance ' && resource.name.startsWith('projects/PROJECT_ID/zones/REGION/instances/dev-'))`
`compute.googleapis.com/Network`	כלל קישור בין רשתות שכנות בענן וירטואלי פרטי (VPC) להתאמה של רשתות שכנות	`resource.selfLink.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default') \|\| resource.peerings.exists(p, p.network.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/shared$'))`
`cloudfunctions.googleapis.com/CloudFunction`	מתן אפשרות רק לתעבורת נתונים נכנסת פנימית לפונקציית Cloud Run	`has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')`
`compute.googleapis.com/Instance`	שם המשאב תואם לתבנית	`resource.name.matches('^gcp-vm-(linux\|windows)-v\\d+$')`
`serviceusage.googleapis.com/Service`	אפשר להפעיל רק ממשקי API שקשורים לאחסון	`resource.state == 'ENABLED' && !( resource.name.matches('storage-api.googleapis.com') \|\| resource.name.matches('bigquery-json.googleapis.com') \|\| resource.name.matches('bigquery.googleapis.com') \|\| resource.name.matches('sql-component.googleapis.com') \|\| resource.name.matches('spanner.googleapis.com'))`
`sqladmin.googleapis.com/Instance`	מותרות רק כתובות IP ציבוריות שמופיעות ברשימת ההיתרים	`(resource.instanceType == 'CLOUD_SQL_INSTANCE' && resource.backendType == 'SECOND_GEN' && resource.settings.ipConfiguration.ipv4Enabled ) && !(resource.ipAddresses.all(ip, ip.type != 'PRIMARY' \|\| ip.ipAddress.matches('IP_ADDRESS'))))`
`dataproc.googleapis.com/Cluster`	בודקים אם מזהי הפרויקטים באשכול Dataproc מכילים את מחרוזות המשנה testing או development	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

ביטויי CEL למאפיינים מותאמים אישית של ממצאים

אם רוצים להחזיר מידע נוסף עם כל ממצא שאפשר להשתמש בו בשאילתות חיפוש, אפשר להגדיר עד עשרה מאפיינים מותאמים אישית שיוחזרו עם הממצאים שנוצרו על ידי המודולים המותאמים אישית.

המאפיינים המותאמים אישית מופיעים במאפייני המקור של הממצא בקובץ ה-JSON שלו ובכרטיסייה מאפייני המקור של פרטי הממצא במסוףGoogle Cloud .

אתם מגדירים מאפיינים מותאמים אישית כצמדים של name-value.

אם יוצרים מודול מותאם אישית ב Google Cloud מסוף, מגדירים את זוגות name-value בקטע Custom finding properties בדף Define finding details.

אם אתם מקודדים מודול בהתאמה אישית בקובץ YAML, אתם מציינים את זוגות name-value כ-properties במאפיין custom_output.

לא משנה אם אתם משתמשים במסוף Google Cloud או בקובץ YAML, הכללים הבאים חלים:

מציינים name כמחרוזת טקסט ללא מירכאות.
מציינים את value כאחת מהאפשרויות הבאות:
- כדי להחזיר את הערך של מאפיין, מציינים את המאפיין בפורמט הבא:
  
  RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
בדוגמה:
- הערך של RESOURCE_TYPE יכול להיות resource או policy.
- PROPERTY נכס הורה אחד או יותר של הנכס שמכיל את הערך שרוצים להחזיר.
- ‫PROPERTY_TO_RETURN הוא הנכס שמכיל את הערך שרוצים להחזיר.
- כדי להחזיר מחרוזת טקסט, מקיפים את המחרוזת במירכאות.

בדוגמה הבאה מוצגים שני זוגות של name-value שהוגדרו בצורה נכונה בקובץ YAML מתחת ל-custom_output:

custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.name
    - name: property_with_text
      value_expression:
        expression: "'Note content'"

המאמרים הבאים

כדי לבדוק, לשלוח, לראות ולעדכן מודולים בהתאמה אישית, אפשר לעיין בדפים הבאים:

כדי לבדוק מודולים מותאמים אישית, אפשר לעיין במאמר בדיקת מודולים מותאמים אישית ב-Security Health Analytics.
במאמר יצירה וניהול של מודולים בהתאמה אישית ב-Security Health Analytics מוסבר איך מעלים, מציגים ומעדכנים מודולים בהתאמה אישית.