Package google.security.safebrowsing.v4

אינדקס

• SafeBrowsing (ממשק)
• Checksum (הודעה)
• ClientInfo (הודעה)
• CompressionType (enum)
• FetchThreatListUpdatesRequest (הודעה)
• FetchThreatListUpdatesRequest.ListUpdateRequest (הודעה)
• FetchThreatListUpdatesRequest.ListUpdateRequest.Constraints (הודעה)
• FetchThreatListUpdatesResponse (הודעה)
• FetchThreatListUpdatesResponse.ListUpdateResponse (הודעה)
• FetchThreatListUpdatesResponse.ListUpdateResponse.ResponseType (enum)
• FindFullHashesRequest (הודעה)
• FindFullHashesResponse (הודעה)
• FindThreatMatchesRequest (הודעה)
• FindThreatMatchesResponse (הודעה)
• ListThreatListsResponse (הודעה)
• PlatformType (enum)
• RawHashes (הודעה)
• RawIndices (הודעה)
• RiceDeltaEncoding (הודעה)
• ThreatEntry (הודעה)
• ThreatEntryMetadata (הודעה)
• ThreatEntryMetadata.MetadataEntry (הודעה)
• ThreatEntrySet (הודעה)
• ThreatEntryType (enum)
• ThreatInfo (הודעה)
• ThreatListDescriptor (הודעה)
• ThreatMatch (הודעה)
• ThreatType (enum)

SafeBrowsing

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

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

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

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

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

לקוחות שמשתמשים ב-Update API או ב-Lookup API יכולים לקבל רשימה של רשימות האיומים של Safe Browsing שזמינות להורדה באמצעות השיטה 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 מזהה לקוח שמזהה באופן ייחודי (בתקווה) את הטמעת הלקוח של Safe Browsing API.
client_version	string הגרסה של הטמעת הלקוח.

CompressionType

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

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

FetchThreatListUpdatesRequest

תיאור של בקשת עדכון ל-Safe Browsing 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 הגיבוב (hash) של SHA256 הצפוי של מצב הלקוח, כלומר של הרשימה הממויינת של כל הגיבובים שנמצאים במסד הנתונים אחרי החלת העדכון שסופק. אם מצב הלקוח לא תואם למצב הצפוי, הלקוח צריך להתעלם מהעדכון הזה ולנסות שוב מאוחר יותר.

ResponseType

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

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

FindFullHashesRequest

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

שדות
client	ClientInfo המטא-נתונים של הלקוח.
client_states[]	bytes מצבי הלקוח הנוכחיים בכל אחת מרשימות האיומים המקומיות של הלקוח.
threat_info	ThreatInfo הרשימות והגיבוב (hash) שצריך לבדוק.
api_client	ClientInfo מטא-נתונים של לקוח שמשויכים למבצעי קריאה של ממשקי API ברמה גבוהה יותר שנבנו מעל ההטמעה של הלקוח.

FindFullHashesResponse

שדות
matches[]	ThreatMatch הגיבוב המלא שתואם לתחיליות המבוקשות.
minimum_wait_duration	Duration משך הזמן המינימלי שהלקוח צריך להמתין לפני שהוא יכול לשלוח בקשה לחיפוש גיבוב. אם השדה הזה לא מוגדר, לקוחות יכולים לשלוח בקשה מתי שהם רוצים.
negative_cache_duration	Duration למשך כמה זמן לשמור במטמון את התגובה לגבי ישויות שנשלחה אליהן בקשה ולא התאימו לרשימת האיומים.

FindThreatMatchesRequest

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

שדות
client	ClientInfo המטא-נתונים של הלקוח.
threat_info	ThreatInfo הרשימות והרשומות שצריך לבדוק אם יש בהן התאמות.

FindThreatMatchesResponse

שדות
matches[]	ThreatMatch רשימת האיומים תואמת.

ListThreatListsResponse

שדות
threat_lists[]	ThreatListDescriptor הרשימות שזמינות להורדה על ידי הלקוח.

PlatformType

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

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

RawHashes

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

משמש לשליחת ThreatEntrySet ללקוחות שלא תומכים בקיצור, או כששולחים גיבוב שאינו באורך 4 בייטים ללקוחות שתומכים בקיצור.

שדות
prefix_size	int32 מספר הבייטים של כל קידומת שמקודדת בהמשך. השדה הזה יכול להכיל בין 4 (התחילית הקצרה ביותר) ל-32 תווים (גיבוב SHA256 מלא).
raw_hashes	bytes הגיבובים, בפורמט בינארי, מחוברים למחרוזת ארוכה אחת. הגיבובים ממוינים בסדר לקסיקלי. לגבי משתמשי JSON API, הגיבובים מקודדים ב-base64.

RawIndices

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

שדות
indices[]	int32 האינדקסים להסרה מרשימת מקומית שממוינים לפי האלפבית.

RiceDeltaEncoding

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

שדות
first_value	int64 ההיסט של הרשומה הראשונה בנתונים הקודדים, או אם רק מספר שלם אחד קודד, הערך של אותו מספר שלם יחיד. אם השדה ריק או חסר, נניח שהוא מכיל אפס.
rice_parameter	int32 הפרמטר Golomb-Rice, שהוא מספר בין 2 ל-28. השדה הזה חסר (כלומר, אפס) אם הערך של num_entries הוא אפס.
num_entries	int32 מספר הרשומות שמקודדות ב-delta בנתונים המקודדים. אם רק מספר שלם אחד הועתק, הערך הזה יהיה אפס והערך היחיד יישמר ב-first_value.
encoded_data	bytes ההפרשים המקודדים שמקודדים באמצעות מקודד Golomb-Rice.

ThreatEntry

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

שדות
hash	bytes תחילית גיבוב (hash) שמכילה את 4 עד 32 הבייטים המשמעותיים ביותר של גיבוב SHA256. השדה הזה בפורמט בינארי. בבקשות JSON, הגיבובים בקידוד base64.
url	string כתובת URL.
digest	bytes התמצית של קובץ הפעלה בפורמט SHA256. ה-API תומך גם ב-digests בינאריים וגם ב-digests ב-hex. בבקשות 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, ממוינים בסדר עולה, ולאחר מכן מקודדים ב-delta ונשמרים בתור encoded_data.
rice_indices	RiceDeltaEncoding מדדי הרשימות המקומיים המקודדים, שממוינים לפי סדר אלפביתי באמצעות קידוד Golomb-Rice. היא משמשת לשליחת אינדקסים דחוסים של הסרות. מדדי ההסרה (uint32) ממוינים בסדר עולה, ולאחר מכן מקודדים ב-delta ונשמרים כ-encoded_data.

ThreatEntryType

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

טיפוסים בני מנייה (enum)
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

סוגי האיומים.

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