Package google.security.safebrowsing.v4

אינדקס

SafeBrowsing

ממשקי ה-API של הגלישה הבטוחה מאפשרים ללקוחות לבדוק משאבי אינטרנט (בדרך כלל כתובות אתרים) מול רשימות ש-Google עורכת ומעדכנת באופן קבוע, של משאבי אינטרנט לא בטוחים. ממשקי API לגלישה בטוחה (v4) כוללים את Update API ואת Lookup API.

ממשק ה-API של העדכון מיועד ללקוחות הגדולים שלנו וכולל את השיטות FindFullHashes ו-FetchThreatListUpdates . ב-Update API, הלקוחות נדרשים לנהל את רשימות האיומים שהורדתם במסד נתונים מקומי.

ראשית, הלקוחות מבצעים התאמה עם הרשימות המקומיות שלהם כדי לקבוע את המצב (בטוח או לא בטוח) של משאב אינטרנט נתון. בדרך כלל רשימות מורכבות מקידומות hash של ביטויי כתובות URL שנכללים ברשימת החסימות. כדי לבדוק כתובת אתר, לקוחות יוצרים את הגיבובים של כתובת אתר נתונה ובודקים אם יש התנגשויות בין תחילית ברשימות המקומיות שלהם. אם נמצאה התאמת קידומת, הלקוח מקבל את הגיבובים המלאים שמשויכים לקידומת הגיבוב שהותאמה באמצעות שיטת FindFullHashes . לאחר מכן הלקוח משווה בין הגיבוב המקומי המלא לבין הגיבובים המלאים שהוחזרו. התאמה מציינת שכתובת ה-URL אינה בטוחה.

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

Lookup API מיועד ללקוחות הקטנים יותר שלנו ומאפשר להם להתאים משאבים ישירות לרשימות האיום של הגלישה הבטוחה באמצעות שיטת FindThreatMatches.

לקוחות שמשתמשים ב-Update API או ב-Lookup API יכולים לקבל רשימה של רשימות האיומים של גלישה בטוחה שזמינות להורדה בשיטת ListThreatLists.

{-- TRUSTED_THREAT_REPORTER: לקוחות מהימנים של איומים יכולים להגיש דוחות ל-Google לניתוח באמצעות שיטת SubmitThreatReport. --}

FetchThreatListUpdates

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

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

FindFullHashes

rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)

מחפש את הגיבובים המלאים שתואמים לתחיליות הגיבוב המבוקשות.

FindThreatMatches

rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)

מאתרים את רשומות האיומים שתואמות לרשימות של הגלישה הבטוחה.

ListThreatLists

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

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

סכום כולל

המצב הצפוי של מסד הנתונים המקומי של לקוח.

שדות
sha256

bytes

גיבוב SHA256 של מצב הלקוח, כלומר, של הרשימה הממוינת של כל הגיבובים שנמצאים במסד הנתונים.

ClientInfo

המטא-נתונים של הלקוח שמשויכים לבקשות ה-API של הגלישה הבטוחה.

שדות
client_id

string

מזהה לקוח שמזהה (יש לקוות) באופן ייחודי את יישום הלקוח של ממשק ה-API של הגלישה הבטוחה.

client_version

string

הגרסה של הטמעת הלקוח.

CompressionType

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

טיפוסים בני מנייה (enums)
COMPRESSION_TYPE_UNSPECIFIED לא ידוע.
RAW נתונים גולמיים ולא דחוסים.
RICE נתונים בקידוד אורז-גולומב.

FetchThreatListUpdatesRequest

מתוארת בקשת עדכון של ה-API לגלישה בטוחה. לקוחות יכולים לבקש עדכונים למספר רשימות בבקשה אחת. ייתכן שהשרת לא יגיב לכל הבקשות אם אין לשרת עדכונים לרשימה הזו. הערה: אינדקס 2 של השדה אינו בשימוש. הבא: 5

שדות
client

ClientInfo

המטא-נתונים של הלקוח.

list_update_requests[]

ListUpdateRequest

העדכונים המבוקשים של רשימת האיומים.

ListUpdateRequest

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

שדות
threat_type

ThreatType

סוג האיום שנוצר על ידי הרשומות ברשימה.

platform_type

PlatformType

סוג הפלטפורמה בסיכון שנובעת מהרשומות ברשימה.

threat_entry_type

ThreatEntryType

סוגי הרשומות שמוצגים ברשימה.

state

bytes

המצב הנוכחי של הלקוח עבור הרשימה המבוקשת (מצב הלקוח המוצפן שהתקבל מהעדכון המוצלח האחרון של הרשימה).

constraints

Constraints

האילוצים שמשויכים לבקשה הזו.

מגבלות

המגבלות שחלות על העדכון הזה.

שדות
max_update_entries

int32

הגודל המרבי של מספר הערכים. העדכון לא יכלול יותר רשומות מהערך הזה. הוא צריך להיות חזקה של 2 בין 2**10 ל-2**20. אם הערך הוא אפס, לא מוגדרת מגבלת גודל לעדכון.

max_database_entries

int32

מגדיר את המספר המקסימלי של הערכים שהלקוח מוכן לכלול במסד הנתונים המקומי עבור הרשימה שצוינה. הוא צריך להיות חזקה של 2 בין 2**10 ל-2**20. אם הערך הוא אפס, לא מוגדרת מגבלה לגודל של מסד הנתונים.

region

string

המערכת מבקשת את הרשימה למיקום גיאוגרפי ספציפי. אם המדיניות לא מוגדרת, השרת עשוי לבחור את הערך הזה בהתאם לכתובת ה-IP של המשתמש. נדרש פורמט ISO 3166-1 alpha-2.

supported_compressions[]

CompressionType

סוגי הדחיסה שבהם הלקוח תומך.

language

string

הפונקציה מבקשת את הרשימות לשפה מסוימת. נדרש פורמט ISO 639 alpha-2.

device_location

string

המיקום הפיזי של הלקוח, מבוטא כקוד אזור לפי תקן ISO 31166-1 alpha-2.

FetchThreatListUpdatesResponse

שדות
list_update_responses[]

ListUpdateResponse

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

minimum_wait_duration

Duration

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

ListUpdateResponse

עדכון לרשימה בודדת.

שדות
threat_type

ThreatType

סוג האיום שעבורו מוחזרים נתונים.

threat_entry_type

ThreatEntryType

הפורמט של האיומים.

platform_type

PlatformType

סוג הפלטפורמה שעבורה מוחזרים הנתונים.

response_type

ResponseType

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

additions[]

ThreatEntrySet

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

removals[]

ThreatEntrySet

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

new_client_state

bytes

מצב הלקוח החדש, בפורמט מוצפן. אטומים ללקוחות.

checksum

Checksum

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

ResponseType

סוג התגובה שנשלחה ללקוח.

טיפוסים בני מנייה (enums)
RESPONSE_TYPE_UNSPECIFIED לא ידוע.
PARTIAL_UPDATE עדכונים חלקיים מיושמים במסד הנתונים המקומי הקיים של הלקוח.
FULL_UPDATE עדכונים מלאים מחליפים את כל מסד הנתונים המקומי של הלקוח. המשמעות היא שהלקוח היה לא עדכני בצורה חמורה או שקיים חשד שהלקוח פגום.

FindFullHashesRequest

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

שדות
client

ClientInfo

המטא-נתונים של הלקוח.

client_states[]

bytes

מצב הלקוח הנוכחי עבור כל אחת מרשימות האיומים המקומיים של הלקוח.

threat_info

ThreatInfo

הרשימות והגיבובים שיש לבדוק.

api_client

ClientInfo

מטא-נתונים של לקוחות שמשויכים לקריאות לממשקי API ברמה גבוהה יותר, שמבוססים על ההטמעה של הלקוח.

FindFullHashesResponse

שדות
matches[]

ThreatMatch

הגיבובים המלאים שתאמו לקידומות המבוקשות.

minimum_wait_duration

Duration

משך הזמן המינימלי שהלקוח צריך להמתין לפני שליחת בקשת גיבוב (hash) לחיפוש. אם לא מגדירים את השדה הזה, הלקוחות יכולים לשלוח בקשה בהקדם האפשרי.

negative_cache_duration

Duration

לישויות המבוקשות שלא תאמו לרשימת האיומים, מהו משך הזמן לשמירת התגובה במטמון.

FindThreatMatchesRequest

בקשה לבדיקת רשומות מול רשימות.

שדות
client

ClientInfo

המטא-נתונים של הלקוח.

threat_info

ThreatInfo

הרשימות והערכים שיש לבדוק אם יש בהם התאמות.

FindThreatMatchesResponse

שדות
matches[]

ThreatMatch

רשימת האיומים תואמת.

ListThreatListsResponse

שדות
threat_lists[]

ThreatListDescriptor

הרשימות שזמינות להורדה על ידי הלקוח.

PlatformType

סוגי פלטפורמות.

טיפוסים בני מנייה (enums)
PLATFORM_TYPE_UNSPECIFIED פלטפורמה לא ידועה.
WINDOWS איום על Windows
LINUX איום על Linux.
ANDROID איום על Android
OSX איום על OS X
IOS איום על iOS.
ANY_PLATFORM איום על אחת מהפלטפורמות המוגדרות לפחות.
ALL_PLATFORMS איום מאיים על כל הפלטפורמות המוגדרות.
CHROME איום על Chrome.

RawHashes

רשומות האיומים הלא דחוסות בפורמט גיבוב (hash) באורך קידומת מסוים. גודל הגיבוב יכול להיות בין 4 ל-32 בייטים. רובם הם באורך של 4 בייטים, אבל חלק מגיבובים (hash) עשויים לתארך אם הם מתנגשים עם הגיבוב של כתובת URL פופולרית.

משמש לשליחת ThreatEntrySet ללקוחות שלא תומכים בדחיסה, או בעת שליחת גיבובים שאינם בגודל 4 בייטים ללקוחות שתומכים בדחיסה.

שדות
prefix_size

int32

מספר הבייטים לכל קידומת שמקודדת למטה. השדה הזה יכול להיות בין 4 (הקידומת הקצרה ביותר) ל-32 (גיבוב SHA256 מלא).

raw_hashes

bytes

הגיבובים, בפורמט בינארי, משורשרים למחרוזת ארוכה אחת. הגיבובים ממוינים בסדר לקסיקוגרפי. למשתמשי JSON API, הגיבובים הם בקידוד base64.

RawIndices

קבוצת מדדים גולמיים להסרה מרשימה מקומית.

שדות
indices[]

int32

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

RiceDeltaEncoding

הנתונים המקודדים של Rice-Golomb. משמש לשליחת גיבובים (hash) בגודל 4 בייטים דחוסים או אינדקסים של הסרה דחוסה.

שדות
first_value

int64

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

rice_parameter

int32

הפרמטר Golomb-Rice, שהוא מספר בין 2 ל-28. השדה הזה חסר (כלומר, אפס) אם הערך של num_entries הוא אפס.

num_entries

int32

מספר הערכים המקודדים כדלתא בנתונים המקודדים. אם קודדו מספר שלם אחד בלבד, הוא יהיה אפס והערך היחיד יאוחסן ב-first_value.

encoded_data

bytes

הדלתא המקודדת המקודדת באמצעות המקודד גולומב-אורז.

ThreatEntry

איום ספציפי. לדוגמה, כתובת URL זדונית או ייצוג הגיבוב (hash) שלו. צריך להגדיר רק אחד מהשדות האלה.

שדות
hash

bytes

קידומת גיבוב (hash) שמכילה את 4 עד 32 הבייטים המשמעותיים ביותר לגיבוב מסוג SHA256. השדה הזה הוא בפורמט בינארי. בבקשות JSON, הגיבובים הם בקידוד base64.

url

string

כתובת URL.

digest

bytes

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

ThreatEntryMetadata

המטא-נתונים המשויכים לרשומה ספציפית של איום. הלקוח מצופה לדעת את צמדי מפתח/ערך של מטא-נתונים המשויכים לכל סוג איום.

שדות
entries[]

MetadataEntry

רשומות המטא-נתונים.

MetadataEntry

רשומת מטא-נתונים אחת.

שדות
key

bytes

מפתח רשומת המטא נתונים. בבקשות JSON, המפתח הוא בקידוד base64.

value

bytes

ערך רשומת המטא נתונים. בבקשות JSON, הערך הוא בקידוד base64.

ThreatEntrySet

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

שדות
compression_type

CompressionType

סוג הדחיסה עבור הערכים בקבוצה הזו.

raw_hashes

RawHashes

הרשומות הגולמיות בפורמט SHA256.

raw_indices

RawIndices

אינדקסים גולמיים להסרה עבור רשימה מקומית.

rice_hashes

RiceDeltaEncoding

הקידומות המקודדות של 4 בייט לרשומות בפורמט SHA256, באמצעות קידוד Golomb-Rice. הגיבובים מומרים ל-uint32, ממוינים בסדר עולה ולאחר מכן מקודדים כדלתא ומאוחסנים כנתונים מקודדים.

rice_indices

RiceDeltaEncoding

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

ThreatEntryType

סוגי הרשומות שמהוות איומים. רשימות איומים הן אוספים של פריטים מסוג יחיד.

טיפוסים בני מנייה (enums)
THREAT_ENTRY_TYPE_UNSPECIFIED לא צוין.
URL כתובת URL.
EXECUTABLE קובץ הפעלה.

ThreatInfo

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

שדות
threat_types[]

ThreatType

סוגי האיומים שיש לבדוק.

platform_types[]

PlatformType

סוגי הפלטפורמות לבדיקה.

threat_entry_types[]

ThreatEntryType

סוגי הרשומות שיש לבדוק.

threat_entries[]

ThreatEntry

רשומות האיום שיש לבדוק.

ThreatListDescriptor

מתאר רשימת איומים של אנשים. רשימה מוגדרת לפי שלושה פרמטרים: סוג האיום, סוג הפלטפורמה שהאיום מטרגט וסוג הרשומות שברשימה.

שדות
threat_type

ThreatType

סוג האיום שנוצר ברשימה.

platform_type

PlatformType

סוג הפלטפורמה שמטורגטות הרשומות ברשימה.

threat_entry_type

ThreatEntryType

סוגי הרשומות שכלולים ברשימה.

ThreatMatch

התאמה כשבודקים רשומה של איומים ברשימות האיום של הגלישה הבטוחה.

שדות
threat_type

ThreatType

סוג האיום שתואם לאיום הזה.

platform_type

PlatformType

סוג הפלטפורמה שתואם לאיום הזה.

threat_entry_type

ThreatEntryType

סוג הרשומה של האיום שתואם לאיום הזה.

threat

ThreatEntry

האיום שתואם לאיום הזה.

threat_entry_metadata

ThreatEntryMetadata

מטא-נתונים אופציונליים שמשויכים לאיום הזה.

cache_duration

Duration

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

ThreatType

סוגי איומים.

טיפוסים בני מנייה (enums)
THREAT_TYPE_UNSPECIFIED לא ידוע.
MALWARE סוג האיום של תוכנה זדונית.
SOCIAL_ENGINEERING סוג האיום של הנדסה חברתית.
UNWANTED_SOFTWARE סוג האיום של תוכנה לא רצויה.
POTENTIALLY_HARMFUL_APPLICATION סוג האיום של אפליקציות שעלולות להזיק.