איסוף יומני הקשר של ישויות ב-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

  1. נכנסים אל Duo Admin Panel.
  2. עוברים אל Applications > Protect an Application.
  3. מחפשים את Admin API ולוחצים על Protect (הגנה).
  4. רושמים את הערכים הבאים:
    • מפתח שילוב (ikey)
    • מפתח סודי (skey)
    • שם המארח של ה-API (לדוגמה, api-XXXXXXXX.duosecurity.com)
  5. בקטע Permissions, מפעילים את ההגדרה Grant resource - Read (כדי לקרוא משתמשים, קבוצות, טלפונים, נקודות קצה, אסימונים ואישורים של WebAuthn).
  6. לוחצים על Save.

יצירת קטגוריה של Google Cloud Storage

  1. נכנסים אל מסוף Google Cloud.
  2. בוחרים פרויקט או יוצרים פרויקט חדש.
  3. בתפריט הניווט, עוברים אל Cloud Storage > Buckets.
  4. לוחצים על Create bucket.
  5. מספקים את פרטי ההגדרה הבאים:

    הגדרה ערך
    Name your bucket (שם הקטגוריה) מזינים שם ייחודי גלובלית (לדוגמה, duo-context)
    סוג המיקום בוחרים לפי הצרכים (אזור, שני אזורים, מספר אזורים)
    Location בוחרים את המיקום (לדוגמה, us-central1).
    סוג אחסון (storage class) רגיל (מומלץ ליומנים שמתבצעת אליהם גישה לעיתים קרובות)
    בקרת גישה אחיד (מומלץ)
    כלים להגנה אופציונלי: הפעלת ניהול גרסאות של אובייקטים או מדיניות שמירת נתונים
  6. לוחצים על יצירה.

  7. שומרים את שם הקטגוריה והאזור לעיון בעתיד.

יצירת חשבון שירות לפונקציית Cloud Run

פונקציית Cloud Run צריכה חשבון שירות עם הרשאות כתיבה לקטגוריה של GCS והרשאה להפעלה על ידי Pub/Sub.

יצירת חשבון שירות

  1. במסוף GCP, עוברים אל IAM & Admin > Service Accounts.
  2. לוחצים על יצירת חשבון שירות.
  3. מספקים את פרטי ההגדרה הבאים:
    • שם חשבון השירות: מזינים duo-entity-context-sa.
    • תיאור חשבון השירות: מזינים Service account for Cloud Run function to collect Duo entity context data.
  4. לוחצים על יצירה והמשך.
  5. בקטע Grant this service account access to project (מתן גישה של חשבון השירות הזה לפרויקט), מוסיפים את התפקידים הבאים:
    1. לוחצים על בחירת תפקיד.
    2. מחפשים את Storage Object Admin ולוחצים עליו.
    3. לוחצים על + הוספת תפקיד נוסף.
    4. מחפשים את האפשרות Cloud Run Invoker (הפעלת שירותים ב-Cloud Run) ולוחצים עליה.
    5. לוחצים על + הוספת תפקיד נוסף.
    6. מחפשים את האפשרות Cloud Functions Invoker (הפעלת פונקציות של Cloud Functions) ולוחצים עליה.
  6. לוחצים על Continue.
  7. לוחצים על סיום.

התפקידים האלה נדרשים כדי:

  • אדמין של אובייקט אחסון: כתיבת יומנים לקטגוריית GCS
  • ‫Cloud Run Invoker: מתן הרשאה ל-Pub/Sub להפעיל את הפונקציה
  • Cloud Functions Invoker: מאפשר הפעלה של פונקציות

מתן הרשאות IAM בקטגוריית GCS

נותנים לחשבון השירות הרשאות כתיבה בקטגוריית GCS:

  1. עוברים אל Cloud Storage > Buckets (קטגוריות).
  2. לוחצים על שם הקטגוריה.
  3. עוברים לכרטיסייה Permissions.
  4. לוחצים על הענקת גישה.
  5. מספקים את פרטי ההגדרה הבאים:
    • Add principals (הוספת ישויות מורשות): מזינים את כתובת האימייל בחשבון השירות (לדוגמה, duo-entity-context-sa@PROJECT_ID.iam.gserviceaccount.com).
    • הקצאת תפקידים: בוחרים באפשרות אדמין של אובייקטים באחסון.
  6. לוחצים על Save.

יצירת נושא Pub/Sub

יוצרים נושא Pub/Sub ש-Cloud Scheduler יפרסם בו ופונקציית Cloud Run תירשם אליו.

  1. במסוף GCP, עוברים אל Pub/Sub > Topics.
  2. לוחצים על יצירת נושא.
  3. מספקים את פרטי ההגדרה הבאים:
    • מזהה הנושא: מזינים duo-entity-context-trigger.
    • משאירים את שאר ההגדרות כברירת מחדל.
  4. לוחצים על יצירה.

יצירת פונקציית Cloud Run לאיסוף נתוני הקשר של ישויות

הפונקציה Cloud Run מופעלת על ידי הודעות Pub/Sub מ-Cloud Scheduler כדי לאחזר נתוני הקשר של ישויות מ-Duo Admin API ולכתוב אותם ל-GCS.

  1. במסוף GCP, עוברים אל Cloud Run.
  2. לוחצים על יצירת שירות.
  3. בוחרים באפשרות Function (שימוש בעורך ישיר ליצירת פונקציה).
  4. בקטע Configure (הגדרה), מזינים את פרטי ההגדרה הבאים:

    הגדרה ערך
    שם השירות duo-entity-context-collector
    אזור בוחרים אזור שתואם ל-GCS Bucket (לדוגמה, us-central1)
    זמן ריצה בוחרים באפשרות Python 3.12 ואילך.
  5. בקטע טריגר (אופציונלי):

    1. לוחצים על + הוספת טריגר.
    2. בוחרים באפשרות Cloud Pub/Sub.
    3. בקטע Select a Cloud Pub/Sub topic, בוחרים את הנושא ב-Pub/Sub ‏ (duo-entity-context-trigger).
    4. לוחצים על Save.
  6. בקטע Authentication:

    1. בוחרים באפשרות דרישת אימות.
    2. בודקים את ניהול זהויות והרשאות גישה (IAM).
  7. גוללים למטה ומרחיבים את Containers, Networking, Security (מאגרי תגים, רשתות, אבטחה).

  8. עוברים לכרטיסייה אבטחה:

    • חשבון שירות: בוחרים את חשבון השירות (duo-entity-context-sa).
  9. עוברים לכרטיסייה מאגרי תגים:

    1. לוחצים על Variables & Secrets (משתנים וסודות).
    2. לוחצים על + הוספת משתנה לכל משתנה סביבתי:
    שם המשתנה ערך לדוגמה
    GCS_BUCKET duo-context
    GCS_PREFIX duo/context/
    DUO_IKEY DIXYZ...
    DUO_SKEY ****************
    DUO_API_HOSTNAME api-XXXXXXXX.duosecurity.com
    LIMIT 100
    RESOURCES users,groups,phones,endpoints,tokens,webauthncredentials
  10. בקטע Variables & Secrets (משתנים וסודות), גוללים אל Requests (בקשות):

    • זמן קצוב לתפוגת בקשה: מזינים 600 שניות (10 דקות).
  11. עוברים לכרטיסייה הגדרות במאגרי תגים:

    • בקטע Resources (מקורות מידע):
      • זיכרון: בוחרים באפשרות ‎512 MiB או יותר.
      • מעבד: בוחרים באפשרות 1.
    • לוחצים על סיום.
  12. גוללים אל סביבת הפעלה:

    • בוחרים באפשרות ברירת מחדל (מומלץ).
  13. בקטע שינוי קנה מידה של העריכה:

    • מספר המינימום של מופעים: מזינים 0.
    • מספר מקסימלי של מופעים: מזינים 100 (או משנים בהתאם לעומס הצפוי).
  14. לוחצים על יצירה.

  15. ממתינים ליצירת השירות (1-2 דקות).

  16. אחרי שיוצרים את השירות, עורך הקוד המוטבע נפתח באופן אוטומטי.

הוספת קוד פונקציה

  1. מזינים main בFunction entry point
  2. בעורך הקוד המוטבע, יוצרים שני קבצים:

    • הקובץ הראשון: 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.*
    
  3. לוחצים על Deploy כדי לשמור ולפרוס את הפונקציה.

  4. ממתינים לסיום הפריסה (2-3 דקות).

יצירת משימה ב-Cloud Scheduler

‫Cloud Scheduler מפרסם הודעות בנושא Pub/Sub במרווחי זמן קבועים, וכך מפעיל את הפונקציה של Cloud Run.

  1. במסוף GCP, עוברים אל Cloud Scheduler.
  2. לוחצים על Create Job (יצירת משימה).
  3. מספקים את פרטי ההגדרה הבאים:

    הגדרה ערך
    שם duo-entity-context-hourly
    אזור בחירה באותו אזור כמו פונקציית Cloud Run
    תדירות ‫0 * * * * (כל שעה, בדיוק בשעה)
    אזור זמן בחירת אזור זמן (מומלץ לבחור UTC)
    סוג הטירגוט Pub/Sub
    נושא בוחרים את נושא Pub/Sub (duo-entity-context-trigger).
    גוף ההודעה ‫{} (אובייקט JSON ריק)
  4. לוחצים על יצירה.

אפשרויות לתדירות התזמון

  • בוחרים את התדירות בהתאם לדרישות לגבי עדכניות הנתונים:

    תדירות ביטוי Cron תרחיש לדוגמה
    כל שעה 0 * * * * רגיל (מומלץ)
    כל שעתיים 0 */2 * * * עדכניות בינונית
    כל 6 שעות 0 */6 * * * עדכונים בתדירות נמוכה
    יומי 0 0 * * * עדכונים מינימליים

בדיקת משימת המתזמן

  1. במסוף Cloud Scheduler, מאתרים את המשימה (duo-entity-context-hourly).
  2. כדי להפעיל את הטריגר באופן ידני, לוחצים על הפעלה מאולצת.
  3. מחכים כמה שניות ועוברים אל Cloud Run > Services > duo-entity-context-collector > Logs.
  4. מוודאים שהפונקציה בוצעה בהצלחה.
  5. בודקים את קטגוריית GCS כדי לוודא שנתוני ההקשר של הישות נכתבו.

אחזור חשבון השירות של Google SecOps

‫Google SecOps משתמש בחשבון שירות ייחודי כדי לקרוא נתונים מהקטגוריה של GCS. צריך להעניק לחשבון השירות הזה גישה לדלי.

קבלת כתובת האימייל בחשבון השירות

  1. עוברים אל SIEM Settings > Feeds (הגדרות SIEM > פידים).
  2. לוחצים על הוספת פיד חדש.
  3. לוחצים על Configure a single feed (הגדרת פיד יחיד).
  4. בשדה שם הפיד, מזינים שם לפיד (לדוגמה, Duo Entity Context).
  5. בוחרים באפשרות Google Cloud Storage V2 בתור סוג המקור.
  6. בוחרים באפשרות נתוני הקשר של ישות Duo בתור סוג היומן.
  7. לוחצים על קבלת חשבון שירות. מוצגת כתובת אימייל ייחודית של חשבון השירות, לדוגמה:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com
    
  8. מעתיקים את כתובת האימייל הזו לשימוש בשלב הבא.

הענקת הרשאות IAM לחשבון השירות של Google SecOps

לחשבון השירות של Google SecOps צריך להיות התפקיד צפייה באובייקט אחסון בקטגוריה של GCS.

  1. עוברים אל Cloud Storage > Buckets (קטגוריות).
  2. לוחצים על שם הקטגוריה.
  3. עוברים לכרטיסייה Permissions.
  4. לוחצים על הענקת גישה.
  5. מספקים את פרטי ההגדרה הבאים:
    • Add principals (הוספת ישויות מורשות): מדביקים את כתובת האימייל בחשבון של חשבון השירות של Google SecOps.
    • הקצאת תפקידים: בוחרים באפשרות צפייה באובייקט אחסון.
  6. לוחצים על Save.

הגדרת פיד ב-Google SecOps להטמעה של נתוני הקשר של ישויות ב-Duo

  1. עוברים אל SIEM Settings > Feeds (הגדרות SIEM > פידים).
  2. לוחצים על הוספת פיד חדש.
  3. לוחצים על Configure a single feed (הגדרת פיד יחיד).
  4. בשדה שם הפיד, מזינים שם לפיד (לדוגמה, Duo Entity Context).
  5. בוחרים באפשרות Google Cloud Storage V2 בתור סוג המקור.
  6. בוחרים באפשרות נתוני הקשר של ישות Duo בתור סוג היומן.
  7. לוחצים על הבא.
  8. מציינים ערכים לפרמטרים הבאים של הקלט:

    • כתובת ה-URL של קטגוריית האחסון: מזינים את ה-URI של קטגוריית GCS עם נתיב הקידומת:

      gs://duo-context/duo/context/
      
      • מחליפים את:

        • ‫duo-context: השם של קטגוריית GCS.
        • ‫duo/context/: קידומת או נתיב התיקייה שבהם נשמרים היומנים (צריכים להיות זהים למשתנה הסביבה GCS_PREFIX).
    • אפשרות למחיקת המקור: בוחרים את אפשרות המחיקה לפי ההעדפה שלכם:

      • אף פעם: לא נמחקים קבצים אחרי ההעברה (מומלץ לבדיקות).
      • מחיקת קבצים שהועברו: הקבצים נמחקים אחרי שההעברה מסתיימת.
      • מחיקת קבצים שהועברו וספריות ריקות: מחיקת קבצים וספריות ריקות אחרי שההעברה מסתיימת בהצלחה.

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

    • מרחב השמות של הנכס: מרחב השמות של הנכס.

    • תוויות להוספה: התווית שתתווסף לאירועים מהפיד הזה.

  9. לוחצים על הבא.

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

טבלת מיפוי 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.