איסוף יומני הקשר של ישויות ב-Duo
גרסת כלי הניתוח: 2.0
במאמר הזה מוסבר איך להטמיע נתוני הקשר של ישויות Duo ב-Google Security Operations באמצעות Google Cloud Storage. הכלי לניתוח הנתונים משנה את יומני ה-JSON למודל נתונים מאוחד (UDM) על ידי חילוץ שדות מ-JSON גולמי, ואז מיפוי השדות האלה למאפייני UDM. הוא מטפל בתרחישי נתונים שונים, כולל מידע על משתמשים ונכסים, פרטי תוכנה ותוויות אבטחה, כדי להבטיח ייצוג מקיף בסכימת ה-UDM.
לפני שמתחילים
חשוב לוודא שמתקיימות דרישות הסף הבאות:
- מופע של Google SecOps
- גישה עם הרשאות לטנאנט Duo (אפליקציית Admin API עם הרשאות אדמין מספיקות לניהול אפליקציות)
- פרויקט ב-GCP עם Cloud Storage API מופעל
- הרשאות ליצירה ולניהול של מאגרי GCS
- הרשאות לניהול מדיניות IAM בקטגוריות GCS
- הרשאות ליצירת שירותי Cloud Run, נושאי Pub/Sub ומשימות Cloud Scheduler
הגדרת אפליקציית Duo Admin API
- נכנסים אל Duo Admin Panel.
- עוברים אל Applications > Protect an Application.
- מחפשים את Admin API ולוחצים על Protect (הגנה).
- רושמים את הערכים הבאים:
- מפתח שילוב (ikey)
- מפתח סודי (skey)
- שם המארח של ה-API (לדוגמה,
api-XXXXXXXX.duosecurity.com)
- בקטע Permissions, מפעילים את ההגדרה Grant resource - Read (כדי לקרוא משתמשים, קבוצות, טלפונים, נקודות קצה, אסימונים ואישורים של WebAuthn).
לוחצים על Save.
יצירת קטגוריה של Google Cloud Storage
- נכנסים אל מסוף Google Cloud.
- בוחרים פרויקט או יוצרים פרויקט חדש.
- בתפריט הניווט, עוברים אל Cloud Storage > Buckets.
- לוחצים על Create bucket.
מספקים את פרטי ההגדרה הבאים:
הגדרה ערך Name your bucket (שם הקטגוריה) מזינים שם ייחודי גלובלית (לדוגמה, duo-context)סוג המיקום בוחרים לפי הצרכים (אזור, שני אזורים, מספר אזורים) Location בוחרים את המיקום (לדוגמה, us-central1).סוג אחסון (storage class) רגיל (מומלץ ליומנים שמתבצעת אליהם גישה לעיתים קרובות) בקרת גישה אחיד (מומלץ) כלים להגנה אופציונלי: הפעלת ניהול גרסאות של אובייקטים או מדיניות שמירת נתונים לוחצים על יצירה.
שומרים את שם הקטגוריה והאזור לעיון בעתיד.
יצירת חשבון שירות לפונקציית Cloud Run
פונקציית Cloud Run צריכה חשבון שירות עם הרשאות כתיבה לקטגוריה של GCS והרשאה להפעלה על ידי Pub/Sub.
יצירת חשבון שירות
- במסוף GCP, עוברים אל IAM & Admin > Service Accounts.
- לוחצים על יצירת חשבון שירות.
- מספקים את פרטי ההגדרה הבאים:
- שם חשבון השירות: מזינים
duo-entity-context-sa. - תיאור חשבון השירות: מזינים
Service account for Cloud Run function to collect Duo entity context data.
- שם חשבון השירות: מזינים
- לוחצים על יצירה והמשך.
- בקטע Grant this service account access to project (מתן גישה של חשבון השירות הזה לפרויקט), מוסיפים את התפקידים הבאים:
- לוחצים על בחירת תפקיד.
- מחפשים את Storage Object Admin ולוחצים עליו.
- לוחצים על + הוספת תפקיד נוסף.
- מחפשים את האפשרות Cloud Run Invoker (הפעלת שירותים ב-Cloud Run) ולוחצים עליה.
- לוחצים על + הוספת תפקיד נוסף.
- מחפשים את האפשרות Cloud Functions Invoker (הפעלת פונקציות של Cloud Functions) ולוחצים עליה.
- לוחצים על Continue.
- לוחצים על סיום.
התפקידים האלה נדרשים כדי:
- אדמין של אובייקט אחסון: כתיבת יומנים לקטגוריית GCS
- Cloud Run Invoker: מתן הרשאה ל-Pub/Sub להפעיל את הפונקציה
- Cloud Functions Invoker: מאפשר הפעלה של פונקציות
מתן הרשאות IAM בקטגוריית GCS
נותנים לחשבון השירות הרשאות כתיבה בקטגוריית GCS:
- עוברים אל Cloud Storage > Buckets (קטגוריות).
- לוחצים על שם הקטגוריה.
- עוברים לכרטיסייה Permissions.
- לוחצים על הענקת גישה.
- מספקים את פרטי ההגדרה הבאים:
- Add principals (הוספת ישויות מורשות): מזינים את כתובת האימייל בחשבון השירות (לדוגמה,
duo-entity-context-sa@PROJECT_ID.iam.gserviceaccount.com). - הקצאת תפקידים: בוחרים באפשרות אדמין של אובייקטים באחסון.
- Add principals (הוספת ישויות מורשות): מזינים את כתובת האימייל בחשבון השירות (לדוגמה,
- לוחצים על Save.
יצירת נושא Pub/Sub
יוצרים נושא Pub/Sub ש-Cloud Scheduler יפרסם בו ופונקציית Cloud Run תירשם אליו.
- במסוף GCP, עוברים אל Pub/Sub > Topics.
- לוחצים על יצירת נושא.
- מספקים את פרטי ההגדרה הבאים:
- מזהה הנושא: מזינים
duo-entity-context-trigger. - משאירים את שאר ההגדרות כברירת מחדל.
- מזהה הנושא: מזינים
- לוחצים על יצירה.
יצירת פונקציית Cloud Run לאיסוף נתוני הקשר של ישויות
הפונקציה Cloud Run מופעלת על ידי הודעות Pub/Sub מ-Cloud Scheduler כדי לאחזר נתוני הקשר של ישויות מ-Duo Admin API ולכתוב אותם ל-GCS.
- במסוף GCP, עוברים אל Cloud Run.
- לוחצים על יצירת שירות.
- בוחרים באפשרות Function (שימוש בעורך ישיר ליצירת פונקציה).
בקטע Configure (הגדרה), מזינים את פרטי ההגדרה הבאים:
הגדרה ערך שם השירות duo-entity-context-collectorאזור בוחרים אזור שתואם ל-GCS Bucket (לדוגמה, us-central1)זמן ריצה בוחרים באפשרות Python 3.12 ואילך. בקטע טריגר (אופציונלי):
- לוחצים על + הוספת טריגר.
- בוחרים באפשרות Cloud Pub/Sub.
- בקטע Select a Cloud Pub/Sub topic, בוחרים את הנושא ב-Pub/Sub (
duo-entity-context-trigger). - לוחצים על Save.
בקטע Authentication:
- בוחרים באפשרות דרישת אימות.
- בודקים את ניהול זהויות והרשאות גישה (IAM).
גוללים למטה ומרחיבים את Containers, Networking, Security (מאגרי תגים, רשתות, אבטחה).
עוברים לכרטיסייה אבטחה:
- חשבון שירות: בוחרים את חשבון השירות (
duo-entity-context-sa).
- חשבון שירות: בוחרים את חשבון השירות (
עוברים לכרטיסייה מאגרי תגים:
- לוחצים על Variables & Secrets (משתנים וסודות).
- לוחצים על + הוספת משתנה לכל משתנה סביבתי:
שם המשתנה ערך לדוגמה GCS_BUCKETduo-contextGCS_PREFIXduo/context/DUO_IKEYDIXYZ...DUO_SKEY****************DUO_API_HOSTNAMEapi-XXXXXXXX.duosecurity.comLIMIT100RESOURCESusers,groups,phones,endpoints,tokens,webauthncredentialsבקטע Variables & Secrets (משתנים וסודות), גוללים אל Requests (בקשות):
- זמן קצוב לתפוגת בקשה: מזינים
600שניות (10 דקות).
- זמן קצוב לתפוגת בקשה: מזינים
עוברים לכרטיסייה הגדרות במאגרי תגים:
- בקטע Resources (מקורות מידע):
- זיכרון: בוחרים באפשרות 512 MiB או יותר.
- מעבד: בוחרים באפשרות 1.
- לוחצים על סיום.
- בקטע Resources (מקורות מידע):
גוללים אל סביבת הפעלה:
- בוחרים באפשרות ברירת מחדל (מומלץ).
בקטע שינוי קנה מידה של העריכה:
- מספר המינימום של מופעים: מזינים
0. - מספר מקסימלי של מופעים: מזינים
100(או משנים בהתאם לעומס הצפוי).
- מספר המינימום של מופעים: מזינים
לוחצים על יצירה.
ממתינים ליצירת השירות (1-2 דקות).
אחרי שיוצרים את השירות, עורך הקוד המוטבע נפתח באופן אוטומטי.
הוספת קוד פונקציה
- מזינים main בFunction entry point
בעורך הקוד המוטבע, יוצרים שני קבצים:
- הקובץ הראשון: main.py:
import functions_framework from google.cloud import storage import json import os import time import hmac import hashlib import base64 import email.utils import urllib.parse from urllib.request import Request, urlopen # Environment variables DUO_IKEY = os.environ["DUO_IKEY"] DUO_SKEY = os.environ["DUO_SKEY"] DUO_API_HOSTNAME = os.environ["DUO_API_HOSTNAME"].strip() GCS_BUCKET = os.environ["GCS_BUCKET"] GCS_PREFIX = os.environ.get("GCS_PREFIX", "duo/context/") # Default resources can be adjusted via ENV RESOURCES = [r.strip() for r in os.environ.get("RESOURCES", "users,groups,phones,endpoints,tokens,webauthncredentials,desktop_authenticators").split(",") if r.strip()] # Duo paging: default 100; max varies by endpoint LIMIT = int(os.environ.get("LIMIT", "100")) # Initialize Storage client storage_client = storage.Client() def _canon_params(params: dict) -> str: """RFC 3986 encoding with '~' unescaped, keys sorted lexicographically.""" if not params: return "" parts = [] for k in sorted(params.keys()): v = params[k] if v is None: continue ks = urllib.parse.quote(str(k), safe="~") vs = urllib.parse.quote(str(v), safe="~") parts.append(f"{ks}={vs}") return "&".join(parts) def _sign(method: str, host: str, path: str, params: dict) -> dict: """Construct Duo Admin API Authorization + Date headers (HMAC-SHA1).""" now = email.utils.formatdate() canon = "\n".join([ now, method.upper(), host.lower(), path, _canon_params(params) ]) sig = hmac.new( DUO_SKEY.encode("utf-8"), canon.encode("utf-8"), hashlib.sha1 ).hexdigest() auth = base64.b64encode(f"{DUO_IKEY}:{sig}".encode("utf-8")).decode("utf-8") return { "Date": now, "Authorization": f"Basic {auth}" } def _call(method: str, path: str, params: dict) -> dict: host = DUO_API_HOSTNAME assert host.startswith("api-") and host.endswith(".duosecurity.com"), \ "DUO_API_HOSTNAME must be e.g. api-XXXXXXXX.duosecurity.com" qs = _canon_params(params) url = f"https://{host}{path}" + (f"?{qs}" if method.upper() == "GET" and qs else "") req = Request(url, method=method.upper()) for k, v in _sign(method, host, path, params).items(): req.add_header(k, v) with urlopen(req, timeout=60) as r: return json.loads(r.read().decode("utf-8")) def _write_json(obj: dict, when: float, resource: str, page: int) -> str: bucket = storage_client.bucket(GCS_BUCKET) prefix = GCS_PREFIX.strip("/") + "/" if GCS_PREFIX else "" key = f"{prefix}{time.strftime('%Y/%m/%d', time.gmtime(when))}/duo-{resource}-{page:05d}.json" blob = bucket.blob(key) blob.upload_from_string( json.dumps(obj, separators=(",", ":")), content_type="application/json" ) return key def _fetch_resource(resource: str) -> dict: """Fetch all pages for a list endpoint using limit/offset + metadata.next_offset.""" path = f"/admin/v1/{resource}" offset = 0 page = 0 now = time.time() total_items = 0 while True: params = {"limit": LIMIT, "offset": offset} data = _call("GET", path, params) _write_json(data, now, resource, page) page += 1 resp = data.get("response") # most endpoints return a list; if not a list, count as 1 object page if isinstance(resp, list): total_items += len(resp) elif resp is not None: total_items += 1 meta = data.get("metadata") or {} next_offset = meta.get("next_offset") if next_offset is None: break # Duo returns next_offset as int try: offset = int(next_offset) except Exception: break return { "resource": resource, "pages": page, "objects": total_items } @functions_framework.cloud_event def main(cloud_event): """ Cloud Run function triggered by Pub/Sub to fetch Duo entity context data and write to GCS. Args: cloud_event: CloudEvent object containing Pub/Sub message """ results = [] for res in RESOURCES: print(f"Fetching resource: {res}") result = _fetch_resource(res) results.append(result) print(f"Completed {res}: {result['pages']} pages, {result['objects']} objects") print(f"All resources fetched successfully: {results}")- הקובץ השני: requirements.txt:
functions-framework==3.* google-cloud-storage==2.*לוחצים על Deploy כדי לשמור ולפרוס את הפונקציה.
ממתינים לסיום הפריסה (2-3 דקות).
יצירת משימה ב-Cloud Scheduler
Cloud Scheduler מפרסם הודעות בנושא Pub/Sub במרווחי זמן קבועים, וכך מפעיל את הפונקציה של Cloud Run.
- במסוף GCP, עוברים אל Cloud Scheduler.
- לוחצים על Create Job (יצירת משימה).
מספקים את פרטי ההגדרה הבאים:
הגדרה ערך שם duo-entity-context-hourlyאזור בחירה באותו אזור כמו פונקציית Cloud Run תדירות 0 * * * *(כל שעה, בדיוק בשעה)אזור זמן בחירת אזור זמן (מומלץ לבחור UTC) סוג הטירגוט Pub/Sub נושא בוחרים את נושא Pub/Sub ( duo-entity-context-trigger).גוף ההודעה {}(אובייקט JSON ריק)לוחצים על יצירה.
אפשרויות לתדירות התזמון
בוחרים את התדירות בהתאם לדרישות לגבי עדכניות הנתונים:
תדירות ביטוי Cron תרחיש לדוגמה כל שעה 0 * * * *רגיל (מומלץ) כל שעתיים 0 */2 * * *עדכניות בינונית כל 6 שעות 0 */6 * * *עדכונים בתדירות נמוכה יומי 0 0 * * *עדכונים מינימליים
בדיקת משימת המתזמן
- במסוף Cloud Scheduler, מאתרים את המשימה (
duo-entity-context-hourly). - כדי להפעיל את הטריגר באופן ידני, לוחצים על הפעלה מאולצת.
- מחכים כמה שניות ועוברים אל Cloud Run > Services > duo-entity-context-collector > Logs.
- מוודאים שהפונקציה בוצעה בהצלחה.
- בודקים את קטגוריית GCS כדי לוודא שנתוני ההקשר של הישות נכתבו.
אחזור חשבון השירות של Google SecOps
Google SecOps משתמש בחשבון שירות ייחודי כדי לקרוא נתונים מהקטגוריה של GCS. צריך להעניק לחשבון השירות הזה גישה לדלי.
קבלת כתובת האימייל בחשבון השירות
- עוברים אל SIEM Settings > Feeds (הגדרות SIEM > פידים).
- לוחצים על הוספת פיד חדש.
- לוחצים על Configure a single feed (הגדרת פיד יחיד).
- בשדה שם הפיד, מזינים שם לפיד (לדוגמה,
Duo Entity Context). - בוחרים באפשרות Google Cloud Storage V2 בתור סוג המקור.
- בוחרים באפשרות נתוני הקשר של ישות Duo בתור סוג היומן.
לוחצים על קבלת חשבון שירות. מוצגת כתובת אימייל ייחודית של חשבון השירות, לדוגמה:
chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.comמעתיקים את כתובת האימייל הזו לשימוש בשלב הבא.
הענקת הרשאות IAM לחשבון השירות של Google SecOps
לחשבון השירות של Google SecOps צריך להיות התפקיד צפייה באובייקט אחסון בקטגוריה של GCS.
- עוברים אל Cloud Storage > Buckets (קטגוריות).
- לוחצים על שם הקטגוריה.
- עוברים לכרטיסייה Permissions.
- לוחצים על הענקת גישה.
- מספקים את פרטי ההגדרה הבאים:
- Add principals (הוספת ישויות מורשות): מדביקים את כתובת האימייל בחשבון של חשבון השירות של Google SecOps.
- הקצאת תפקידים: בוחרים באפשרות צפייה באובייקט אחסון.
לוחצים על Save.
הגדרת פיד ב-Google SecOps להטמעה של נתוני הקשר של ישויות ב-Duo
- עוברים אל SIEM Settings > Feeds (הגדרות SIEM > פידים).
- לוחצים על הוספת פיד חדש.
- לוחצים על Configure a single feed (הגדרת פיד יחיד).
- בשדה שם הפיד, מזינים שם לפיד (לדוגמה,
Duo Entity Context). - בוחרים באפשרות Google Cloud Storage V2 בתור סוג המקור.
- בוחרים באפשרות נתוני הקשר של ישות Duo בתור סוג היומן.
- לוחצים על הבא.
מציינים ערכים לפרמטרים הבאים של הקלט:
כתובת ה-URL של קטגוריית האחסון: מזינים את ה-URI של קטגוריית GCS עם נתיב הקידומת:
gs://duo-context/duo/context/מחליפים את:
-
duo-context: השם של קטגוריית GCS. -
duo/context/: קידומת או נתיב התיקייה שבהם נשמרים היומנים (צריכים להיות זהים למשתנה הסביבהGCS_PREFIX).
-
אפשרות למחיקת המקור: בוחרים את אפשרות המחיקה לפי ההעדפה שלכם:
- אף פעם: לא נמחקים קבצים אחרי ההעברה (מומלץ לבדיקות).
- מחיקת קבצים שהועברו: הקבצים נמחקים אחרי שההעברה מסתיימת.
מחיקת קבצים שהועברו וספריות ריקות: מחיקת קבצים וספריות ריקות אחרי שההעברה מסתיימת בהצלחה.
הגיל המקסימלי של הקובץ: כולל קבצים שעברו שינוי במספר הימים האחרון. ברירת המחדל היא 180 ימים.
מרחב השמות של הנכס: מרחב השמות של הנכס.
תוויות להוספה: התווית שתתווסף לאירועים מהפיד הזה.
לוחצים על הבא.
בודקים את ההגדרות של הפיד החדש במסך סיום ולוחצים על שליחה.
טבלת מיפוי UDM
| שדה ביומן | מיפוי UDM | היגיון |
|---|---|---|
| הופעל | entity.asset.deployment_status | אם הערך של activated הוא false, הערך שמוגדר הוא DECOMISSIONED, אחרת הערך הוא ACTIVE. |
| browsers.browser_family | entity.asset.software.name | הערך חולץ ממערך 'הדפדפנים' ביומן הגולמי. |
| browsers.browser_version | entity.asset.software.version | הערך חולץ ממערך 'הדפדפנים' ביומן הגולמי. |
| device_name | entity.asset.hostname | ממופה ישירות מהיומן הגולמי. |
| disk_encryption_status | entity.asset.attribute.labels.key: "disk_encryption_status", entity.asset.attribute.labels.value | מופה ישירות מיומן הגולמי, הומר לאותיות קטנות. |
| אימייל | entity.user.email_addresses | ממופה ישירות מיומן הגולמי אם הוא מכיל '@', אחרת נעשה שימוש ב 'שם משתמש' או ב 'שם משתמש1' אם הם מכילים '@'. |
| מוצפן | entity.asset.attribute.labels.key: "Encrypted", entity.asset.attribute.labels.value | מופה ישירות מיומן הגולמי, הומר לאותיות קטנות. |
| epkey | entity.asset.product_object_id | הערך הזה משמש כ-'product_object_id' אם הוא קיים, אחרת המערכת משתמשת ב-'phone_id' או ב-'token_id'. |
| טביעת אצבע | entity.asset.attribute.labels.key: "Finger Print", entity.asset.attribute.labels.value | מופה ישירות מיומן הגולמי, הומר לאותיות קטנות. |
| firewall_status | entity.asset.attribute.labels.key: "firewall_status", entity.asset.attribute.labels.value | מופה ישירות מיומן הגולמי, הומר לאותיות קטנות. |
| hardware_uuid | entity.asset.asset_id | הערך הזה משמש כ-asset_id אם הוא קיים, אחרת הוא משמש כ-user_id. |
| last_seen | entity.asset.last_discover_time | הערך מנותח כחותמת זמן בפורמט ISO8601 וממופה. |
| מודל | entity.asset.hardware.model | ממופה ישירות מהיומן הגולמי. |
| מספר | entity.user.phone_numbers | ממופה ישירות מהיומן הגולמי. |
| os_family | entity.asset.platform_software.platform | הערך ממופה ל-WINDOWS, LINUX או MAC, ללא הבחנה בין אותיות רישיות לאותיות קטנות. |
| os_version | entity.asset.platform_software.platform_version | ממופה ישירות מהיומן הגולמי. |
| password_status | entity.asset.attribute.labels.key: "password_status", entity.asset.attribute.labels.value | מופה ישירות מיומן הגולמי, הומר לאותיות קטנות. |
| phone_id | entity.asset.product_object_id | הערך הזה משמש כ-'product_object_id' אם לא מופיע 'epkey', אחרת המערכת משתמשת ב-'token_id'. |
| security_agents.security_agent | entity.asset.software.name | המידע חולץ מהמערך security_agents ביומן הגולמי. |
| security_agents.version | entity.asset.software.version | המידע חולץ מהמערך security_agents ביומן הגולמי. |
| חותמת זמן | entity.metadata.collected_timestamp | מאכלס את השדה collected_timestamp באובייקט metadata. |
| token_id | entity.asset.product_object_id | הערך הזה משמש כ-'product_object_id' אם לא צוינו הערכים 'epkey' ו-'phone_id'. |
| trusted_endpoint | entity.asset.attribute.labels.key: "trusted_endpoint", entity.asset.attribute.labels.value | מופה ישירות מיומן הגולמי, הומר לאותיות קטנות. |
| סוג | entity.asset.type | אם הערך 'type' ביומן הגולמי מכיל את הערך mobile (לא תלוי אותיות רישיות), הערך יהיה MOBILE, אחרת הערך יהיה LAPTOP. |
| user_id | entity.asset.asset_id | הערך הזה משמש כ-'asset_id' אם לא מופיע 'hardware_uuid'. |
| users.email | entity.user.email_addresses | הערך הזה משמש כ-'email_addresses' אם זו נקודת הצירוף של המשתמש במערך 'users' והוא מכיל את התו '@'. |
| users.username | entity.user.userid | שם המשתמש שמופק לפני הסמל '@' ומשמש כ-'userid' אם זו נקודת הצירוף של המשתמש במערך 'users'. |
| entity.metadata.vendor_name | "Duo" | |
| entity.metadata.product_name | "Duo Entity Context Data" (נתוני הקשר של ישות ב-Duo) | |
| entity.metadata.entity_type | נכס | |
| entity.relations.entity_type | משתמש | |
| entity.relations.relationship | OWNS |
הבעיה עדיין לא נפתרה? קבלת תשובות מחברי הקהילה וממומחי Google SecOps.