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 V5 Google จะไม่นำรายการแฮชที่เมธอดนี้เคยแสดงผลออก ซึ่งจะช่วยให้ไคลเอ็นต์ข้ามการใช้วิธีนี้และเพียงแค่ฮาร์ดโค้ดรายการแฮชทั้งหมดที่ต้องการได้

นี่คือเมธอด List มาตรฐานตามที่กำหนดโดย https://google.aip.dev/132 และเมธอด HTTP คือ GET
SearchHashes

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

ค้นหาแฮชแบบเต็มที่ตรงกับคำนำหน้าที่ระบุ

นี่คือวิธีที่กำหนดเองตามที่ระบุไว้ใน https://google.aip.dev/136 (วิธีที่กำหนดเองหมายถึงวิธีนี้มีชื่อที่กำหนดเองภายในคำศัพท์การพัฒนา API ทั่วไปของ Google ไม่ได้หมายถึงการใช้วิธี HTTP ที่กำหนดเอง)
SearchUrls

rpc SearchUrls(SearchUrlsRequest) returns (SearchUrlsResponse)

ค้นหา URL ที่ตรงกับภัยคุกคามที่รู้จัก ระบบจะตรวจสอบ URL แต่ละรายการ รวมถึงนิพจน์คำต่อท้ายโฮสต์และคำนำหน้าเส้นทาง (สูงสุดตามระดับที่จำกัด) ซึ่งหมายความว่าการตอบกลับอาจมี URL ที่ไม่ได้รวมอยู่ในคำขอ แต่เป็นนิพจน์ของ URL ที่ขอ

BatchGetHashListsRequest

คำขอรับรายการแฮชหลายรายการพร้อมกัน

ช่อง
names[]

string

ต้องระบุ ชื่อของรายการแฮชที่เฉพาะเจาะจง รายการอาจเป็นรายการภัยคุกคามหรือแคชส่วนกลาง ชื่อต้องไม่ซ้ำกัน หากซ้ำกัน ไคลเอ็นต์จะได้รับข้อผิดพลาด
version[]

bytes

เวอร์ชันของรายการแฮชที่ไคลเอ็นต์มีอยู่แล้ว หากไคลเอ็นต์ดึงข้อมูลรายการแฮชเป็นครั้งแรก คุณควรปล่อยให้ช่องนี้ว่างไว้ มิฉะนั้น ไคลเอ็นต์ควรระบุเวอร์ชันที่ได้รับจากเซิร์ฟเวอร์ก่อนหน้านี้ ไคลเอ็นต์ต้องไม่แก้ไขไบต์เหล่านั้น

ไคลเอ็นต์ไม่จำเป็นต้องส่งเวอร์ชันตามลำดับเดียวกับชื่อรายการที่เกี่ยวข้อง ไคลเอ็นต์อาจส่งเวอร์ชันในคำขอน้อยกว่าหรือมากกว่าจำนวนชื่อ อย่างไรก็ตาม ไคลเอ็นต์ต้องไม่ส่งหลายเวอร์ชันที่สอดคล้องกับชื่อเดียวกัน หากส่ง ไคลเอ็นต์จะได้รับข้อผิดพลาด

หมายเหตุเกี่ยวกับประวัติ: ใน API เวอร์ชัน 4 เราเรียกพารามิเตอร์นี้ว่า states แต่ตอนนี้เราได้เปลี่ยนชื่อเป็น version เพื่อให้ชัดเจนยิ่งขึ้น
size_constraints

SizeConstraints

ข้อจำกัดด้านขนาดในแต่ละรายการ หากละเว้น จะไม่มีข้อจำกัด โปรดทราบว่าขนาดที่ระบุที่นี่เป็นขนาดต่อรายการ ไม่ใช่ขนาดรวมของทุกรายการ

BatchGetHashListsResponse

การตอบกลับที่มีรายการแฮชหลายรายการ

ช่อง
hash_lists[]

HashList

รายการแฮชตามลำดับเดียวกันกับที่ระบุในคำขอ

FullHash

แฮชแบบเต็มที่ระบุว่าตรงกันอย่างน้อย 1 รายการ

ช่อง
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

คำขอรับรายการแฮช ซึ่งอาจเป็นรายการภัยคุกคามหรือรายการที่ไม่ใช่ภัยคุกคาม เช่น แคชส่วนกลาง

มีอะไรใหม่ใน V5: เราได้เปลี่ยนชื่อสิ่งที่เคยเรียกว่า states ใน V4 เป็น version เพื่อความชัดเจน ตอนนี้มีการตั้งชื่อรายการแล้ว และระบบได้นำประเภทแพลตฟอร์มและประเภทรายการภัยคุกคามออกแล้ว ตอนนี้รายการหลายรายการสามารถมีภัยคุกคามประเภทเดียวกัน หรือรายการเดียวที่เกี่ยวข้องกับภัยคุกคามหลายประเภทได้แล้ว ซึ่งแตกต่างจากคำนำหน้าแฮชแบบความยาวผันแปรของ V4 ที่ทำให้เกิดปัญหาในการติดตั้งใช้งานไคลเอ็นต์หลายรายการ ตอนนี้แฮชทั้งหมดในรายการมีความยาวเดียว ซึ่งช่วยให้การติดตั้งใช้งานไคลเอ็นต์มีประสิทธิภาพมากขึ้น เราได้ลดความซับซ้อนของข้อจำกัดและนำประเภทการบีบอัดออก (ระบบจะใช้การบีบอัดเสมอ)

ช่อง
name

string

ต้องระบุ ชื่อของรายการแฮชนี้ ซึ่งอาจเป็นรายการภัยคุกคามหรือแคชส่วนกลาง
version

bytes

เวอร์ชันของรายการแฮชที่ไคลเอ็นต์มีอยู่แล้ว หากไคลเอ็นต์ดึงข้อมูลรายการแฮชเป็นครั้งแรก คุณต้องเว้นช่องนี้ไว้ มิฉะนั้นไคลเอ็นต์ควรระบุเวอร์ชันที่ได้รับจากเซิร์ฟเวอร์ก่อนหน้านี้ ไคลเอ็นต์ต้องไม่แก้ไขไบต์เหล่านั้น

มีอะไรใหม่ใน V5: ใน API เวอร์ชัน 4 ฟิลด์นี้มีชื่อว่า states ตอนนี้เราได้เปลี่ยนชื่อเป็น version เพื่อให้เข้าใจได้ง่ายขึ้น
size_constraints

SizeConstraints

ข้อจำกัดด้านขนาดในรายการ หากละเว้น จะไม่มีข้อจำกัด ขอแนะนำให้ใช้ข้อจำกัดในอุปกรณ์ทั้งหมดที่มีกำลังประมวลผล แบนด์วิดท์ หรือพื้นที่เก็บข้อมูลจำกัด

HashList

รายการแฮชที่ระบุตามชื่อ

ช่อง
name

string

ชื่อของรายการแฮช โปรดทราบว่าแคชส่วนกลางเป็นเพียงรายการแฮชและดูได้ที่นี่
version

bytes

เวอร์ชันของรายการแฮช ไคลเอ็นต์ต้องไม่แก้ไขไบต์เหล่านั้น
partial_update

bool

หากเป็นจริง นี่คือ Diff บางส่วนที่มีการเพิ่มและการนำออกตามสิ่งที่ไคลเอ็นต์มีอยู่แล้ว เมื่อเป็นเท็จ นี่คือรายการแฮชที่สมบูรณ์

หากเป็นเท็จ ไคลเอ็นต์ต้องลบเวอร์ชันที่จัดเก็บไว้ในเครื่องสำหรับรายการแฮชนี้ ซึ่งหมายความว่าเวอร์ชันที่ไคลเอ็นต์มีนั้นล้าสมัยอย่างมาก หรือระบบเชื่อว่าข้อมูลไคลเอ็นต์เสียหาย ฟิลด์ compressed_removals จะว่างเปล่า

หากเป็นจริง ไคลเอ็นต์ต้องใช้การอัปเดตแบบเพิ่มทีละรายการโดยใช้การนำออกก่อน แล้วจึงเพิ่ม
compressed_removals

RiceDeltaEncoded32Bit

ดัชนีการนำออกเวอร์ชันที่เข้ารหัส Rice-delta เนื่องจากรายการแฮชแต่ละรายการมีรายการน้อยกว่า 2^32 รายการแน่นอน ระบบจึงถือว่าดัชนีเป็นจำนวนเต็ม 32 บิตและเข้ารหัส
minimum_wait_duration

Duration

ไคลเอ็นต์ควรรออย่างน้อยเท่านี้เพื่อรับรายการแฮชอีกครั้ง หากไม่มีหรือเป็น 0 ไคลเอ็นต์ควรดึงข้อมูลทันทีเนื่องจากแสดงว่าเซิร์ฟเวอร์มีการอัปเดตเพิ่มเติมที่จะส่งไปยังไคลเอ็นต์ แต่ส่งไม่ได้เนื่องจากข้อจำกัดที่ไคลเอ็นต์ระบุ
sha256_checksum

bytes

รายการแฮชทั้งหมดที่จัดเรียงแล้ว ซึ่งแฮชอีกครั้งด้วย SHA256 นี่คือผลรวมตรวจสอบสำหรับรายการแฮชทั้งหมดที่เรียงแล้วซึ่งอยู่ในฐานข้อมูลหลังจากใช้การอัปเดตที่ระบุ ในกรณีที่ไม่มีการอัปเดต เซิร์ฟเวอร์จะละเว้นฟิลด์นี้เพื่อระบุว่าไคลเอ็นต์ควรใช้ผลรวมตรวจสอบที่มีอยู่
metadata

HashListMetadata

ข้อมูลเมตาเกี่ยวกับรายการแฮช GetHashList จะไม่สร้างข้อมูลนี้ แต่ ListHashLists จะสร้างข้อมูลนี้
ฟิลด์ Union 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

ความยาวของแฮชที่รองรับสำหรับรายการแฮชนี้ รายการแฮชแต่ละรายการจะรองรับความยาวได้เพียง 1 รายการ หากมีการนำความยาวแฮชที่แตกต่างกันมาใช้สำหรับชุดประเภทภัยคุกคามหรือประเภทที่ปลอดภัยชุดเดียวกัน ระบบจะนำมาใช้เป็นรายการแยกต่างหากที่มีชื่อเฉพาะและชุดความยาวแฮชที่เกี่ยวข้อง

HashLength

ความยาวของแฮชในรายการแฮช

Enum
HASH_LENGTH_UNSPECIFIED ความยาวที่ไม่ได้ระบุ
FOUR_BYTES แฮชแต่ละรายการเป็นคำนำหน้า 4 ไบต์
EIGHT_BYTES แฮชแต่ละรายการคือคำนำหน้า 8 ไบต์
SIXTEEN_BYTES แฮชแต่ละรายการคือคำนำหน้า 16 ไบต์
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 บิตบนจะเป็น 0 ทั้งหมด
first_value_lo

fixed64

64 บิตล่างของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากฟิลด์ว่าง บิตล่าง 64 บิตจะเป็น 0 ทั้งหมด
rice_parameter

int32

พารามิเตอร์ Golomb-Rice เรารับประกันว่าพารามิเตอร์นี้จะมีค่าอยู่ระหว่าง 99 ถึง 126
entries_count

int32

จำนวนรายการที่เข้ารหัสเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มเพียงค่าเดียว ค่านี้จะเป็น 0 และระบบจะจัดเก็บค่าเดียวใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวเข้ารหัส Golomb-Rice

RiceDeltaEncoded256Bit

เหมือนกับ RiceDeltaEncoded32Bit แต่จะเข้ารหัสตัวเลข 256 บิต

ช่อง
first_value_first_part

uint64

64 บิตแรกของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากฟิลด์ว่าง บิต 64 บิตแรกจะเป็น 0 ทั้งหมด
first_value_second_part

fixed64

บิตที่ 65 ถึง 128 ของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากช่องว่าง บิตที่ 65 ถึง 128 จะเป็น 0 ทั้งหมด
first_value_third_part

fixed64

บิตที่ 129 ถึง 192 ของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากฟิลด์ว่าง บิตที่ 129 ถึง 192 จะเป็น 0 ทั้งหมด
first_value_fourth_part

fixed64

64 บิตสุดท้ายของรายการแรกในข้อมูลที่เข้ารหัส (แฮช) หากฟิลด์ว่างเปล่า บิต 64 บิตสุดท้ายจะเป็น 0 ทั้งหมด
rice_parameter

int32

พารามิเตอร์ Golomb-Rice พารามิเตอร์นี้รับประกันว่าจะมีค่าอยู่ระหว่าง 227 ถึง 254 (รวมค่าแรกและค่าสุดท้าย)
entries_count

int32

จำนวนรายการที่เข้ารหัสเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มเพียงค่าเดียว ค่านี้จะเป็น 0 และระบบจะจัดเก็บค่าเดียวใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวเข้ารหัส Golomb-Rice

RiceDeltaEncoded32Bit

ข้อมูลที่เข้ารหัส Rice-Golomb ใช้สำหรับแฮชหรือดัชนีการนำออก เรารับประกันว่าแฮชหรือดัชนีทุกรายการที่นี่มีความยาวเท่ากัน และความยาวนี้คือ 32 บิต

โดยทั่วไปแล้ว หากเราจัดเรียงรายการทั้งหมดตามพจนานุกรม เราจะพบว่าบิตที่มีลำดับสูงมักจะไม่เปลี่ยนแปลงบ่อยเท่าบิตที่มีลำดับต่ำ ซึ่งหมายความว่าหากเราพิจารณาความแตกต่างที่อยู่ติดกันระหว่างรายการต่างๆ บิตที่มีลำดับสูงกว่าก็มีโอกาสสูงที่จะเป็น 0 ซึ่งใช้ประโยชน์จากความน่าจะเป็นสูงที่ค่าจะเป็น 0 โดยการเลือกจำนวนบิตที่แน่นอน โดยบิตทั้งหมดที่มีความสำคัญมากกว่านี้มีแนวโน้มที่จะเป็น 0 ดังนั้นเราจึงใช้การเข้ารหัสแบบเอกภาค ดูฟิลด์ rice_parameter

หมายเหตุเกี่ยวกับประวัติ: การเข้ารหัสแบบ Rice-delta ใช้ครั้งแรกใน API เวอร์ชัน 4 ใน V5 มีการปรับปรุงที่สำคัญ 2 อย่าง ได้แก่ ประการแรก ตอนนี้การเข้ารหัส Rice-delta พร้อมใช้งานกับคำนำหน้าแฮชที่ยาวกว่า 4 ไบต์แล้ว ประการที่สอง ตอนนี้ระบบจะถือว่าข้อมูลที่เข้ารหัสเป็นแบบ Big-Endian เพื่อหลีกเลี่ยงขั้นตอนการจัดเรียงที่มีค่าใช้จ่ายสูง

ช่อง
first_value

uint32

รายการแรกในข้อมูลที่เข้ารหัส (แฮชหรือดัชนี) หรือค่าของรายการนั้นหากมีการเข้ารหัสเฉพาะคำนำหน้าแฮชหรือดัชนีเดียว หากช่องว่างเปล่า รายการจะเป็น 0
rice_parameter

int32

พารามิเตอร์ Golomb-Rice พารามิเตอร์นี้รับประกันว่าจะมีค่าอยู่ระหว่าง 3 ถึง 30
entries_count

int32

จำนวนรายการที่เข้ารหัสเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มเพียงค่าเดียว ค่านี้จะเป็น 0 และระบบจะจัดเก็บค่าเดียวใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวเข้ารหัส Golomb-Rice

RiceDeltaEncoded64Bit

เหมือนกับ RiceDeltaEncoded32Bit ยกเว้นว่าตัวนี้จะเข้ารหัสตัวเลข 64 บิต

ช่อง
first_value

uint64

รายการแรกในข้อมูลที่เข้ารหัส (แฮช) หรือค่าของรายการนั้นหากมีการเข้ารหัสเฉพาะคำนำหน้าแฮชรายการเดียว หากช่องว่างเปล่า รายการจะเป็น 0
rice_parameter

int32

พารามิเตอร์ Golomb-Rice เรารับประกันว่าพารามิเตอร์นี้จะอยู่ระหว่าง 35 ถึง 62
entries_count

int32

จำนวนรายการที่เข้ารหัสเดลต้าในข้อมูลที่เข้ารหัส หากมีการเข้ารหัสจำนวนเต็มเพียงค่าเดียว ค่านี้จะเป็น 0 และระบบจะจัดเก็บค่าเดียวใน first_value
encoded_data

bytes

เดลต้าที่เข้ารหัสซึ่งเข้ารหัสโดยใช้ตัวเข้ารหัส Golomb-Rice

SearchHashesRequest

คำขอที่ไคลเอ็นต์ส่งเพื่อค้นหาคำนำหน้าแฮชที่เฉพาะเจาะจง

โดยออกแบบมาเพื่อค้นหารายการภัยคุกคามเท่านั้น และจะไม่ค้นหารายการที่ไม่ใช่ภัยคุกคาม เช่น แคชส่วนกลาง

มีอะไรใหม่ใน V5: ไคลเอ็นต์ไม่จำเป็นต้องระบุ ClientInfo หรือสถานะของรายการแฮชในฐานข้อมูลภายใน เพื่อความเป็นส่วนตัวที่ดียิ่งขึ้น นอกจากนี้ ไคลเอ็นต์ไม่จำเป็นต้องส่งประเภทภัยคุกคามที่สนใจ

ช่อง
hash_prefixes[]

bytes

ต้องระบุ คำนำหน้าแฮชที่จะค้นหา ไคลเอ็นต์ต้องไม่ส่งคำนำหน้าแฮชเกิน 1,000 รายการ อย่างไรก็ตาม ตามขั้นตอนการประมวลผล URL แล้ว ไคลเอ็นต์ไม่ควรต้องส่งคำนำหน้าแฮชมากกว่า 30 รายการ

ปัจจุบันคำนำหน้าแฮชแต่ละรายการต้องมีความยาว 4 ไบต์พอดี ซึ่งอาจมีการผ่อนปรนในอนาคต
filter

string

ไม่บังคับ หากไคลเอ็นต์สนใจการกรอง เช่น ดึงเฉพาะภัยคุกคามบางประเภท ก็สามารถระบุได้ หากละไว้ ระบบจะแสดงภัยคุกคามที่ตรงกันทั้งหมด เราขอแนะนำอย่างยิ่งให้ละเว้นการตั้งค่านี้เพื่อรับการปกป้องที่สมบูรณ์ที่สุดที่ Google Safe Browsing มอบให้ได้

ตัวกรองจะระบุโดยใช้ Google Common Expression Language ซึ่งดูได้ที่ 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)

มีอะไรใหม่ใน V5: มีการแยกส่วนระหว่าง FullHash กับ FullHashDetail ในกรณีที่แฮชแสดงถึงเว็บไซต์ที่มีภัยคุกคามหลายอย่าง (เช่น ทั้ง MALWARE และ SOCIAL_ENGINEERING) คุณไม่จำเป็นต้องส่งแฮชแบบเต็ม 2 ครั้งเหมือนใน V4 นอกจากนี้ เรายังลดความซับซ้อนของระยะเวลาแคชให้เหลือเพียงcache_durationฟิลด์เดียว

ช่อง
full_hashes[]

FullHash

รายการที่ไม่เรียงลำดับ รายการแฮชแบบเต็มที่พบโดยไม่มีการเรียงลำดับ
cache_duration

Duration

ระยะเวลาแคชฝั่งไคลเอ็นต์ ไคลเอ็นต์ต้องเพิ่มระยะเวลานี้ลงในเวลาปัจจุบันเพื่อกำหนดเวลาหมดอายุ จากนั้นเวลาหมดอายุจะมีผลกับคำนำหน้าแฮชทุกรายการที่ไคลเอ็นต์ค้นหาในคำขอ ไม่ว่าระบบจะส่งแฮชแบบเต็มกี่รายการในการตอบกลับก็ตาม แม้ว่าเซิร์ฟเวอร์จะไม่แสดงแฮชแบบเต็มสำหรับคำนำหน้าแฮชหนึ่งๆ แต่ไคลเอ็นต์ก็ต้องแคชข้อเท็จจริงนี้ด้วย

หากฟิลด์ full_hashes ว่างเปล่าเท่านั้น ไคลเอ็นต์อาจเพิ่ม cache_duration เพื่อกำหนดวันหมดอายุใหม่ที่หลังจากวันที่เซิร์ฟเวอร์ระบุ ไม่ว่าในกรณีใดก็ตาม ระยะเวลาแคชที่เพิ่มขึ้นต้องไม่เกิน 24 ชั่วโมง

สำคัญ: ไคลเอ็นต์ต้องไม่ถือว่าเซิร์ฟเวอร์จะแสดงระยะเวลาแคชเดียวกันสำหรับการตอบกลับทั้งหมด เซิร์ฟเวอร์อาจเลือกระยะเวลาแคชที่แตกต่างกันสำหรับการตอบกลับที่แตกต่างกันได้ ทั้งนี้ขึ้นอยู่กับสถานการณ์

SearchUrlsRequest

คำขอที่ไคลเอ็นต์ส่งเพื่อค้นหาภัยคุกคามที่ตรงกับ URL ที่ระบุ

โดยออกแบบมาเพื่อค้นหารายการภัยคุกคามเท่านั้น และจะไม่ค้นหารายการที่ไม่ใช่ภัยคุกคาม เช่น แคชส่วนกลาง

ช่อง
urls[]

string

ต้องระบุ URL ที่จะค้นหา ไคลเอ็นต์ต้องไม่ส่ง URL เกิน 50 รายการ

SearchUrlsResponse

การตอบกลับที่แสดงหลังจากค้นหาภัยคุกคามที่ตรงกับ URL ที่ระบุ

หากไม่พบอะไรเลย เซิร์ฟเวอร์จะแสดงสถานะ OK (รหัสสถานะ HTTP 200) โดยที่ฟิลด์ threats ว่างเปล่า แทนที่จะแสดงสถานะ NOT_FOUND (รหัสสถานะ HTTP 404)

ช่อง
threats[]

ThreatUrl

รายการที่ไม่เรียงลำดับ รายการการจับคู่ภัยคุกคามที่พบซึ่งไม่มีการเรียงลำดับ แต่ละรายการจะมี URL และประเภทภัยคุกคามที่พบซึ่งตรงกับ URL นั้น ขนาดรายการอาจมากกว่าจำนวน URL ในคำขอ เนื่องจากระบบจะพิจารณานิพจน์ทั้งหมดของ URL
cache_duration

Duration

ระยะเวลาแคชฝั่งไคลเอ็นต์ ไคลเอ็นต์ต้องเพิ่มระยะเวลานี้ลงในเวลาปัจจุบันเพื่อกำหนดเวลาหมดอายุ จากนั้นเวลาหมดอายุจะมีผลกับทุก URL ที่ไคลเอ็นต์ค้นหาในคำขอ ไม่ว่าการตอบกลับจะแสดง URL กี่รายการก็ตาม แม้ว่าเซิร์ฟเวอร์จะไม่พบรายการที่ตรงกันสำหรับ URL ใด URL หนึ่ง แต่ไคลเอ็นต์ก็ต้องแคชข้อเท็จจริงนี้ด้วย

หากฟิลด์ threats ว่างเปล่าเท่านั้น ไคลเอ็นต์อาจเพิ่ม cache_duration เพื่อกำหนดวันหมดอายุใหม่ที่หลังจากวันที่เซิร์ฟเวอร์ระบุ ไม่ว่าในกรณีใดก็ตาม ระยะเวลาแคชที่เพิ่มขึ้นต้องไม่เกิน 24 ชั่วโมง

สำคัญ: ไคลเอ็นต์ต้องไม่ถือว่าเซิร์ฟเวอร์จะแสดงระยะเวลาแคชเดียวกันสำหรับการตอบกลับทั้งหมด เซิร์ฟเวอร์อาจเลือกระยะเวลาแคชที่แตกต่างกันสำหรับการตอบกลับที่แตกต่างกันได้ ทั้งนี้ขึ้นอยู่กับสถานการณ์

SizeConstraints

ข้อจำกัดเกี่ยวกับขนาดของรายการแฮช

ช่อง
max_update_entries

int32

ขนาดสูงสุดในจำนวนรายการ การอัปเดตจะมีรายการไม่เกินค่านี้ แต่การอัปเดตอาจมีรายการน้อยกว่าค่านี้ ค่านี้ต้องมีอย่างน้อย 1024 หากเว้นว่างไว้หรือตั้งค่าเป็น 0 ระบบจะไม่กำหนดขีดจำกัดขนาดการอัปเดต
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 Store

ThreatUrl

URL ที่ตรงกับภัยคุกคามอย่างน้อย 1 รายการ

ช่อง
url

string

URL ที่ขอซึ่งตรงกับภัยคุกคามอย่างน้อย 1 รายการ
threat_types[]

ThreatType

รายการที่ไม่เรียงลำดับ รายการภัยคุกคามที่ไม่มีการเรียงลำดับซึ่ง URL จัดอยู่ในประเภท