Package google.security.safebrowsing.v5alpha1

אינדקס

SafeBrowsing

ממשקי Safe Browsing API מאפשרים ללקוחות לבדוק משאבי אינטרנט (בדרך כלל כתובות URL) מול רשימות של Google שמתעדכנות באופן שוטף וכוללות משאבי אינטרנט לא בטוחים.

BatchGetHashLists

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

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

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

זו שיטת Get רגילה של קבוצת בקשות, כפי שמוגדרת בכתובת https://google.aip.dev/231, ושיטת ה-HTTP היא גם GET.
GetHashList

rpc GetHashList(GetHashListRequest) returns (HashList)

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

זו שיטת Get רגילה כפי שמוגדרת בכתובת https://google.aip.dev/131, ושיטת ה-HTTP היא גם GET.
ListHashLists

rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)

רשימת רשימות הגיבוב.

ב-V5 API, ‏ Google לעולם לא תסיר רשימת גיבוב שהוחזרה על ידי השיטה הזו. כך הלקוחות יכולים לדלג על השימוש בשיטה הזו ופשוט להטמיע קוד קשיח של כל רשימות הגיבוב שהם צריכים.

זוהי שיטת רשימה רגילה כפי שמוגדרת בכתובת https://google.aip.dev/132, ושיטת ה-HTTP היא GET.
SearchHashes

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

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

זוהי שיטה מותאמת אישית כפי שמוגדרת בכתובת https://google.aip.dev/136 (השיטה המותאמת אישית מתייחסת לכך שלשיטה הזו יש שם מותאם אישית במינוח הכללי של Google לפיתוח API. היא לא מתייחסת לשימוש בשיטת HTTP מותאמת אישית).
SearchUrls

rpc SearchUrls(SearchUrlsRequest) returns (SearchUrlsResponse)

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

BatchGetHashListsRequest

הבקשה לקבל מספר רשימות גיבוב בו-זמנית.

שדות
names[]

string

חובה. השמות של רשימות הגיבוב הספציפיות. הרשימה יכולה להיות רשימת איומים, או יכול להיות שהיא המטמון הגלובלי. השמות לא יכולים להיות כפולים. אם הם כפולים, הלקוח יקבל שגיאה.
version[]

bytes

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

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

הערה היסטורית: בגרסה 4 של ה-API, השם היה states. עכשיו השם הוא version, כדי שיהיה ברור יותר.
size_constraints

SizeConstraints

מגבלות הגודל של כל רשימה. אם לא מציינים הגבלות, אין הגבלות. הערה: הגדלים שמופיעים כאן הם לכל רשימה, ולא נתונים מצטברים של כל הרשימות.

BatchGetHashListsResponse

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

שדות
hash_lists[]

HashList

רשימות הגיבוב מופיעות באותו סדר שבו הן מופיעות בבקשה.

FullHash

הגיבוב המלא זוהה עם התאמה אחת או יותר.

שדות
full_hash

bytes

הגיבוב המלא התואם. זהו גיבוב SHA256. האורך יהיה 32 בייטים בדיוק.
full_hash_details[]

FullHashDetail

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

FullHashDetail

פרטים על גיבוב מלא תואם.

הערה חשובה לגבי תאימות קדימה: השרת יכול להוסיף בכל שלב סוגים חדשים של איומים ומאפייני איומים. התוספות האלה נחשבות לשינויים בגרסה המשנית. המדיניות של Google היא לא לחשוף מספרי גרסאות משניות בממשקי API (בכתובת https://cloud.google.com/apis/design/versioning אפשר לקרוא על מדיניות ניהול הגרסאות), ולכן הלקוחות צריכים להיות מוכנים לקבל הודעות FullHashDetail שמכילות ערכי enum‏ ThreatType או ערכי enum‏ ThreatAttribute שהלקוח מחשיב כלא תקינים. לכן, באחריות הלקוח לבדוק את התוקף של כל הערכים של ThreatType ו-ThreatAttribute enum. אם ערך כלשהו נחשב לא חוקי, הלקוח חייב להתעלם מההודעה FullHashDetail כולה.

שדות
threat_type

ThreatType

סוג האיום. השדה הזה אף פעם לא יהיה ריק.
attributes[]

ThreatAttribute

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

GetHashListRequest

בקשה לקבל רשימת גיבובים (hashes), שיכולה להיות רשימת איומים או רשימה של פריטים שלא מהווים איום, כמו המטמון הגלובלי.

מה חדש בגרסה 5: מה שנקרא בעבר states בגרסה 4 נקרא עכשיו version, כדי שהשם יהיה ברור יותר. הרשימות מקבלות שמות, וסוגי הפלטפורמות וסוגי רשומות האיומים מוסרים. מעכשיו אפשר להגדיר בכמה רשימות את אותו סוג איום, או להגדיר ברשימה אחת כמה סוגי איומים. בניגוד לקידומות הגיבוב באורך משתנה בגרסה 4, שגרמו לבעיות בהטמעות רבות של לקוחות, כל הגיבובים ברשימה הם באורך יחיד, ולכן ההטמעות של הלקוחות יעילות הרבה יותר. האילוצים פשוטים יותר, וסוג הדחיסה הוסר (הדחיסה תמיד מופעלת).

שדות
name

string

חובה. השם של רשימת הגיבוב הספציפית הזו. יכול להיות שזו רשימת איומים או המטמון הגלובלי.
version

bytes

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

מה חדש בגרסה 5: בגרסה 4 של ה-API, הפונקציה הזו נקראה states. עכשיו השם שלה שונה ל-version כדי שהיא תהיה ברורה יותר.
size_constraints

SizeConstraints

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

HashList

רשימה של ערכי hash שמזוהים לפי השם שלהם.

שדות
name

string

השם של רשימת הגיבוב. שימו לב שהמטמון הגלובלי הוא גם רשימת גיבוב, ואפשר לעיין בו כאן.
version

bytes

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

bool

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

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

אם הערך הוא true, הלקוח חייב להחיל עדכון מצטבר על ידי החלת הסרות ולאחר מכן הוספות.
compressed_removals

RiceDeltaEncoded32Bit

גרסת הקידוד של Rice-delta של אינדקסים להסרה. מכיוון שכל רשימת גיבוב מכילה בוודאות פחות מ-2^32 ערכים, המדדים מטופלים כמספרים שלמים של 32 ביט ומקודדים.
minimum_wait_duration

Duration

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

bytes

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

HashListMetadata

מטא-נתונים לגבי רשימת הגיבוב. המאפיין הזה לא מאוכלס על ידי השיטה GetHashList, אבל הוא מאוכלס על ידי השיטה ListHashLists.
שדה איחוד compressed_additions. גרסת התוספות בקידוד Rice-delta. אורכי הקידומות של הגיבוב של התוספות אחידים בכל התוספות ברשימה. הערך compressed_additions יכול להיות רק אחד מהבאים:
additions_four_bytes

RiceDeltaEncoded32Bit

התוספות של 4 בייט.
additions_eight_bytes

RiceDeltaEncoded64Bit

התוספות של 8 בייט.
additions_sixteen_bytes

RiceDeltaEncoded128Bit

התוספות של 16 בייט.
additions_thirty_two_bytes

RiceDeltaEncoded256Bit

התוספות של 32 הבייטים.

HashListMetadata

מטא-נתונים לגבי רשימת hash מסוימת.

שדות
threat_types[]

ThreatType

רשימה לא ממוינת. אם הרשימה לא ריקה, היא מציינת שרשימת הגיבוב היא סוג של רשימת איומים, ומפרטת את סוגי האיומים שמשויכים לגיבובים או לקידומות של גיבובים ברשימת הגיבוב הזו. יכול להיות שיהיה ריק אם הרשומה לא מייצגת איום, כלומר אם היא מייצגת סוג בטוח סביר.
likely_safe_types[]

LikelySafeType

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

string

תיאור קריא של הרשימה. התוכן כתוב באנגלית.
hash_length

HashLength

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

HashLength

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

טיפוסים בני מנייה (enum)
HASH_LENGTH_UNSPECIFIED אורך לא מוגדר.
FOUR_BYTES כל גיבוב הוא קידומת של ארבעה בייטים.
EIGHT_BYTES כל גיבוב הוא תחילית של שמונה בייטים.
SIXTEEN_BYTES כל גיבוב הוא תחילית של שישה-עשר בייט.
THIRTY_TWO_BYTES כל גיבוב הוא גיבוב מלא באורך 32 בייט.

LikelySafeType

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

שימו לב שהתג SearchHashesResponse לא מכיל את התג LikelySafeType בכוונה.

טיפוסים בני מנייה (enum)
LIKELY_SAFE_TYPE_UNSPECIFIED לא ידוע.
GENERAL_BROWSING האתר הזה כנראה בטוח מספיק לגלישה רגילה. הוא נקרא גם המטמון הגלובלי.
CSD סביר להניח שהאתר הזה בטוח מספיק ואין צורך להפעיל מודלים של זיהוי בצד הלקוח או בדיקות של הגנה על סיסמאות.
DOWNLOAD סביר להניח שהאתר הזה בטוח מספיק, כך שאין צורך לבדוק הורדות מהאתר.

ListHashListsRequest

הבקשה להצגת רשימות הגיבוב הזמינות.

שדות
page_size

int32

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

string

טוקן של דף שהתקבל מקריאה קודמת של ListHashLists. צריך להזין את הטוקן כדי לאחזר את הדף הבא.

ListHashListsResponse

התשובה מכילה מטא-נתונים על רשימות הגיבוב.

שדות
hash_lists[]

HashList

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

string

טוקן שאפשר לשלוח כ-page_token כדי לאחזר את הדף הבא. אם משמיטים את השדה הזה, לא יופיעו דפים נוספים.

RiceDeltaEncoded128Bit

זהה ל-RiceDeltaEncoded32Bit, רק שהפונקציה הזו מקודדת מספרים של 128 ביט.

שדות
first_value_hi

uint64

ה-64 ביטים העליונים של הרשומה הראשונה בנתונים המקודדים (גיבובים). אם השדה ריק, 64 הביטים העליונים הם אפס.
first_value_lo

fixed64

ה-64 ביטים התחתונים של הרשומה הראשונה בנתונים המקודדים (גיבובים). אם השדה ריק, 64 הביטים התחתונים הם אפס.
rice_parameter

int32

פרמטר Golomb-Rice. הערך של הפרמטר הזה חייב להיות בין 99 ל-126, כולל.
entries_count

int32

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

bytes

הדלתאות המקודדות שמקודדות באמצעות קודן Golomb-Rice.

RiceDeltaEncoded256Bit

זהה ל-RiceDeltaEncoded32Bit, אלא שהפונקציה הזו מקודדת מספרים בני 256 ביט.

שדות
first_value_first_part

uint64

‫64 הביטים הראשונים של הרשומה הראשונה בנתונים המקודדים (גיבובים). אם השדה ריק, כל 64 הביטים הראשונים הם אפס.
first_value_second_part

fixed64

הביטים 65 עד 128 של הרשומה הראשונה בנתונים המקודדים (גיבובים). אם השדה ריק, הביטים 65 עד 128 הם אפס.
first_value_third_part

fixed64

הביטים 129 עד 192 של הרשומה הראשונה בנתונים המקודדים (גיבובים). אם השדה ריק, הביטים 129 עד 192 הם אפס.
first_value_fourth_part

fixed64

ה-64 ביטים האחרונים של הרשומה הראשונה בנתונים המקודדים (גיבובים). אם השדה ריק, כל 64 הביטים האחרונים הם אפס.
rice_parameter

int32

פרמטר Golomb-Rice. הערך של הפרמטר הזה יהיה בין 227 ל-254, כולל.
entries_count

int32

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

bytes

הדלתאות המקודדות שמקודדות באמצעות קודן Golomb-Rice.

RiceDeltaEncoded32Bit

הנתונים המקודדים ב-Rice-Golomb. היא משמשת לגיבוב או לאינדקסים של הסרות. מובטח שכל גיבוב או אינדקס כאן יהיו באורך זהה, והאורך הזה הוא בדיוק 32 ביט.

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

הערה היסטורית: קידוד Rice-delta שימש לראשונה בגרסה 4 של ה-API הזה. בגרסה 5 בוצעו שני שיפורים משמעותיים: ראשית, קידוד Rice-delta זמין עכשיו עם קידומות גיבוב באורך של יותר מ-4 בייט; שנית, הנתונים המקודדים מטופלים עכשיו כ-big-endian כדי להימנע משלב מיון יקר.

שדות
first_value

uint32

הערך של הרשומה הראשונה בנתונים המקודדים (גיבובים או אינדקסים), או הערך של הרשומה אם קודד רק קידומת גיבוב או אינדקס יחיד. אם השדה ריק, הערך הוא אפס.
rice_parameter

int32

פרמטר Golomb-Rice. הערך של הפרמטר הזה מובטח להיות בין 3 ל-30, כולל.
entries_count

int32

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

bytes

הדלתאות המקודדות שמקודדות באמצעות קודן Golomb-Rice.

RiceDeltaEncoded64Bit

זהה ל-RiceDeltaEncoded32Bit, אבל הפונקציה הזו מקודדת מספרים בני 64 ביט.

שדות
first_value

uint64

הערך של הרשומה הראשונה בנתונים המקודדים (גיבובים), או הערך של הרשומה אם קודדה רק תחילית גיבוב אחת. אם השדה ריק, הערך הוא אפס.
rice_parameter

int32

פרמטר Golomb-Rice. הערך של הפרמטר הזה מובטח להיות בין 35 ל-62, כולל.
entries_count

int32

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

bytes

הדלתאות המקודדות שמקודדות באמצעות קודן Golomb-Rice.

SearchHashesRequest

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

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

מה חדש בגרסה 5: לקוחות לא צריכים לציין ClientInfo או את המצבים של רשימות הגיבוב במסד הנתונים המקומי שלהם. האפשרות הזו נועדה לשפר את הפרטיות. בנוסף, הלקוחות לא צריכים לציין אילו סוגי איומים מעניינים אותם.

שדות
hash_prefixes[]

bytes

חובה. קידומות הגיבוב שצריך לחפש. הלקוחות לא יכולים לשלוח יותר מ-1,000 קידומות של גיבוב. עם זאת, אחרי תהליך העיבוד של כתובת ה-URL, הלקוחות לא צריכים לשלוח יותר מ-30 קידומות של גיבוב.

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

string

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

המסנן מוגדר באמצעות Google Common Expression Language (שפת ביטויים נפוצה של Google), שאפשר למצוא בכתובת https://github.com/google/cel-spec, יחד עם דוגמאות כלליות. ריכזנו כאן כמה דוגמאות ספציפיות שאפשר להשתמש בהן:

המסנן "threat_type == ThreatType.SOCIAL_ENGINEERING" מחייב שהערך של FullHashDetail בתוך סוג האיום יהיה SOCIAL_ENGINEERING. המזהה "threat_type" מתייחס לסוג האיום הנוכחי. המזהה "ThreatType" מתייחס לקבוצה של כל סוגי האיומים האפשריים.

המסנן "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" מחייב שסוג האיום יהיה UNWANTED_SOFTWARE או MALWARE.

SearchHashesResponse

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

אם לא נמצא דבר, השרת יחזיר סטטוס OK (קוד סטטוס HTTP 200) עם שדה full_hashes ריק, במקום להחזיר סטטוס NOT_FOUND (קוד סטטוס HTTP 404).

מה חדש בגרסה 5: יש הפרדה בין FullHash לבין FullHashDetail. במקרה שבו ערך הגיבוב מייצג אתר עם כמה איומים (למשל, גם MALWARE וגם SOCIAL_ENGINEERING), אין צורך לשלוח את ערך הגיבוב המלא פעמיים כמו בגרסה 4. בנוסף, משך הזמן של המטמון פושט לשדה cache_duration אחד.

שדות
full_hashes[]

FullHash

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

Duration

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

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

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

SearchUrlsRequest

בקשה שהלקוח מנפיק כדי לחפש איומים שתואמים לכתובות ה-URL שצוינו.

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

שדות
urls[]

string

חובה. כתובות ה-URL שרוצים לחפש. הלקוחות לא יכולים לשלוח יותר מ-50 כתובות URL.

SearchUrlsResponse

התשובה שמוחזרת אחרי חיפוש איומים שתואמים לכתובות ה-URL שצוינו.

אם לא נמצא דבר, השרת יחזיר סטטוס OK (קוד סטטוס HTTP 200) עם שדה threats ריק, במקום להחזיר סטטוס NOT_FOUND (קוד סטטוס HTTP 404).

שדות
threats[]

ThreatUrl

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

Duration

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

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

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

SizeConstraints

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

שדות
max_update_entries

int32

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

int32

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

ThreatAttribute

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

טיפוסים בני מנייה (enum)
THREAT_ATTRIBUTE_UNSPECIFIED מאפיין לא ידוע. אם השרת מחזיר את הערך הזה, הלקוח צריך להתעלם לחלוטין מהתג FullHashDetail.
CANARY מציין שלא צריך להשתמש ב-threat_type לאכיפה.
FRAME_ONLY מציין שסוג האיום (threat_type) צריך לשמש לאכיפה רק במסגרות.

ThreatType

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

טיפוסים בני מנייה (enum)
THREAT_TYPE_UNSPECIFIED סוג האיום לא ידוע. אם השרת מחזיר את הערך הזה, הלקוח צריך להתעלם לחלוטין מהתג FullHashDetail.
MALWARE

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

מידע נוסף
SOCIAL_ENGINEERING

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

מידע נוסף
UNWANTED_SOFTWARE סוג האיום של תוכנה לא רצויה. תוכנה לא רצויה היא כל תוכנה שלא עומדת בעקרונות של Google בנוגע לתוכנות, אבל היא לא תוכנה זדונית.
POTENTIALLY_HARMFUL_APPLICATION סוג האיום של אפליקציה בעלת פוטנציאל לגרימת נזק כפי שמשמש את Google Play Protect בחנות Play.

ThreatUrl

כתובת URL שתואמת לאיום אחד או יותר.

שדות
url

string

כתובת ה-URL המבוקשת שתאמה לאיום אחד או יותר.
threat_types[]

ThreatType

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