שימוש ב-Submission API

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

שינויים חשובים ב-Web Risk Submission API

  • הזמנות חדשות והרחבות נסגרו: אנחנו כבר לא מקבלים חוזים חדשים או הרחבות ל-Web Risk Submission API.
  • הקפאת תכונות בתוקף: ממשק ה-API נמצא בהקפאת תכונות רשמית. אנחנו לא משיקים יותר תכונות או שיפורים חדשים.
  • חידושים אחרונים: התאריך האחרון לחידוש חוזים קיימים הוא 31 בדצמבר 2026. כל החידושים מוגבלים לתקופה של שנה אחת לכל היותר.
  • זמינות השירות: שירותים קיימים ימשיכו לפעול עם תיקוני באגים קריטיים, עדכוני אבטחה ותמיכה רגילה עד סוף החוזה הפעיל. הוצאה מלאה משימוש תתרחש עד 31 בדצמבר 2027.

שיטות מומלצות

קריאת המדיניות בנושא גלישה בטוחה

‫Web Risk Submission API מאמת שכתובות ה-URL שנשלחו מציגות תוכן שמפר את המדיניות של גלישה בטוחה. מפתחי API צריכים לוודא שיש הוכחות ברורות לכך שכתובות ה-URL שנשלחות מפרות את המדיניות הזו. בדוגמאות הבאות מוצגות הוכחות להפרת מדיניות:

  • תוכן של הנדסה חברתית שמחקה מותג לגיטימי באינטרנט (שם המותג, הלוגו, המראה והתחושה), התראות מערכת, משתמש בכתובות URL מטעות או מבקש מהמשתמשים להזין פרטי כניסה רגישים כמו שם משתמש או סיסמה.
  • אתר שמארח קובץ הפעלה של תוכנה זדונית ידועה.

אל תשלחו את סוגי כתובות ה-URL הבאים כי סביר להניח שהן לא יתווספו לרשימת החסימה של הגלישה הבטוחה:

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

שיפור הזיהוי

מומלץ להשתמש בשדות ThreatInfo וThreatDiscovery כדי לספק מידע נוסף על השליחות. יכול להיות שזה ישפר את הזיהוי. מידע נוסף זמין במאמר שיטות מומלצות לשימוש ב-Submission API.

טקסונומיה וטירגוט לפי מותג

כדי לספק דוחות מדויקים ומפורטים יותר על התנהלות פוגעת, אפשר להשתמש ברכיבים האופציונליים הבאים באובייקט ThreatInfo: abuseSubtype ו-targetedBrand. השדות האלה עוזרים ל-Web Risk לנתח בצורה מדויקת יותר את הישויות הממוקדות ולשפר את מודלי הזיהוי.

abuseSubtype

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

הערכים הנתמכים של abuseSubtype כוללים את האפשרויות הבאות:

  • ‫BANK_PHISHING: פישינג שמתחזה לבנק או למוסד פיננסי מהימן.
  • ‫CRYPTO_EXCHANGE_PHISHING: פישינג שמתחזה לפלטפורמת מסחר במטבעות וירטואליים.
  • ‫SOCIAL_MEDIA_PLATFORM_PHISHING: פישינג שמתחזה לפלטפורמה של מדיה חברתית.
  • ‫RETAIL_PHISHING: פישינג שמתחזה לפלטפורמה קמעונאית מוכרת.
  • EMAIL_PROVIDER_PHISHING: פישינג שמתחזה לשירות אימייל.
  • ‫ENTERTAINMENT_PHISHING: פישינג שמתחזה לשירות בידור.
  • ‫GOVERNMENT_AGENCY_PHISHING: פישינג שמתחזה לסוכנות ממשלתית כדי להשיג פרטים אישיים מזהים (PII), כמו מספר תעודת זהות או מספר זיהוי לצורכי מס.
  • ‫PACKAGE_TRACKING_SCAM: חיקוי של שירות משלוחים כדי להשיג פרטים אישיים מזהים או פרטי תשלום.
  • ‫FAKE_SUPPORT_SCAM: אתרים מטעים שטוענים שיש בעיות במכשיר כדי לגרום למשתמשים לשתף פרטים אישיים מזהים או ליצור קשר עם נוכלים.
  • ‫GOVERNMENT_FINE_SCAM: תוכן מטעה שבו נטען שיש לשלם קנס אזרחי שלא שולם.
  • ‫FAKE_PRIZE_SCAM: דפים מטעים שמציעים פרסים או תגמולים לא מציאותיים.
  • ‫OTHER_PHISHING / OTHER_SCAM: מתקפות הנדסה חברתית שלא שייכות לקטגוריות האחרות שצוינו כאן.

targetedBrand

אובייקט targetedBrand מזהה את הישות שממוקדת בקמפיינים של פישינג והנדסה חברתית.

  • ‫brandName: השם המוכר של המותג או החברה שמתחזים אליהם (לדוגמה, Altostrat).
  • ‫domain: הדומיין הלגיטימי של המותג שמבצעים לגביו התחזות (לדוגמה, altostrat.com).

הערות חשובות למשתתפים בגרסת הטרום-השקה

  • עקביות בטקסונומיה: פישינג עדיין מסווג בקטגוריה של SOCIAL_ENGINEERING סוג האיום (ולא כסוג הורה נפרד PHISHING) כדי להבטיח עקביות בחבילת Web Risk ו-Safe Browsing API.
  • קטגוריות מוחרגות: קטגוריות המשנה של MALWARE ושל UNWANTED_SOFTWARE מוחרגות מהגרסה הזו.
  • טיפול באיומים שלא מופיעים ברשימה: אם השליחה שלכם לא תואמת לסוג משנה ספציפי, השתמשו ב-OTHER_PHISHING או ב-OTHER_SCAM. מומלץ להשתמש בשדה comments ב-ThreatJustification כדי לתאר את המתקפה.
  • אופציונלי, אבל מומלץ: מילוי השדות האלה עוזר ל-Web Risk לתת עדיפות למודלים המשויכים של מודיעין איומי סייבר ולשפר אותם.
  • שלב התצוגה המקדימה: ערכי ה-Enum וההתנהגות של התכונה הזו עשויים להשתנות.

שליחת כתובות URL

כדי לשלוח כתובת URL, שולחים בקשת HTTP POST לשיטה projects.uris.submit.

  • ‫Submission API תומך בכתובת URL אחת לכל בקשה. כדי לבדוק כמה כתובות URL, צריך לשלוח בקשה נפרדת לכל כתובת URL.

  • כתובת ה-URL חייבת להיות תקינה, אבל לא צריך להגדיר אותה כקנונית. מידע נוסף זמין ב-RFC 2396.

  • תגובת ה-HTTP‏ POST מחזירה long-running operation. מידע נוסף על אחזור תוצאת השליחה ובדיקת הסטטוס של השליחה זמין במאמר בנושא פעולות ממושכות.

דוגמה

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit

גוף בקשת JSON: 

{
  "submission": {
    "uri": "https://www.example.com/login.html"
  }
}

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

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

{
  "name": "projects/project-number/operations/operation-id",
}

בדיקת סטטוס השליחה

משתמשים בערכים project-number ו-operation-id מהתשובה כדי לבדוק את סטטוס השליחה. הסטטוס נמצא בשדה metadata.state של הפעולה שהוחזרה.

המצבים האפשריים כוללים את RUNNING,‏ SUCCEEDED וCLOSED. מידע נוסף על הסטטוסים האלה זמין במאמר הסבר על סטטוס הפעולה במדריך בנושא פעולות ממושכות.