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)

החזרת רשימה של רשימות הגיבוב שישנן.

ב-API בגרסה 5, 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 שהלקוח מחשיב כלא תקינים. לכן, הלקוח אחראי לבדוק את התוקף של כל ערכי ה-enum‏ ThreatType ו-ThreatAttribute. אם ערך כלשהו נחשב לא חוקי, הלקוח חייב להתעלם מההודעה 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, זהו diff חלקי שמכיל תוספות והסרות על סמך מה שכבר קיים אצל הלקוח. אם הערך הוא 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

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

שדות
threat_types[]

ThreatType

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

LikelySafeType

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

string

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

HashLength

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

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

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

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 מסווגת כקשורים אליהם.