Package google.security.safebrowsing.v4

Indeks

SafeBrowsing

Interfejsy API Bezpiecznego przeglądania umożliwiają klientom sprawdzanie zasobów internetowych (najczęściej adresów URL) na stale aktualizowanych przez Google listach niebezpiecznych zasobów internetowych. Interfejsy API bezpiecznego przeglądania (wersja 4) obejmują interfejs Update API i interfejs Lookup API.

Interfejs Update API jest przeznaczony dla większych klientów i obsługuje metody FindFullHashes oraz FetchThreatListUpdates . Interfejs Update API wymaga, aby klienci przechowywali pobrane listy zagrożeń w lokalnej bazie danych.

Najpierw klienci porównują dane z lokalnymi listami, aby określić stan (bezpieczny lub niebezpieczny) danego zasobu internetowego. Najczęściej listy zawierają prefiksy haszowania wyrażeń adresów URL z czarnej listy. Aby sprawdzić adres URL, klienci generują łańcuchy haszowania danego adresu URL i sprawdzają, czy nie ma kolizji prefiksów na swoich listach lokalnych. Jeśli zostanie znalezione dopasowanie prefiksu, klient uzyskuje pełne łańcuchy haszowania powiązane z dopasowanym prefiksem za pomocą metody FindFullHashes. Następnie klient porównuje lokalny pełny hasz z zwróconymi pełnymi haszami; dopasowanie wskazuje, że adres URL jest niebezpieczny.

Po drugie, klienci uzyskują aktualizacje swoich baz danych lokalnych za pomocą metody FetchThreatListUpdates, która pobiera bieżący stan klienta i zwraca zaktualizowany stan klienta wraz ze zmianami, które klient powinien zastosować do swoich lokalnych list zagrożeń.

Interfejs Lookup API jest przeznaczony dla mniejszych klientów i pozwala im dopasowywać zasoby bezpośrednio do list zagrożeń Safe Browsing za pomocą metody FindThreatMatches.

Klienci korzystający z interfejsu Update API lub Lookup API mogą uzyskać listę list zagrożeń Safe Browsing do pobrania za pomocą metody ListThreatLists.

{-- TRUSTED_THREAT_REPORTER: Trusted threat clients can submit reports to Google for analysis via the SubmitThreatReport method. --}

FetchThreatListUpdates

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

Pobiera najnowsze aktualizacje listy zagrożeń. Klient może poprosić o aktualizację wielu list naraz.
FindFullHashes

rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)

Znajduje pełne hashe, które pasują do żądanych prefiksów haszy.
FindThreatMatches

rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)

Znajduje wpisy zagrożeń pasujące do list Bezpiecznego przeglądania.
ListThreatLists

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

Lista list zagrożeń Bezpiecznego przeglądania dostępnych do pobrania.

Suma kontrolna

Oczekiwany stan lokalnej bazy danych klienta.

Pola
sha256

bytes

Skrót SHA256 stanu klienta, czyli posortowanej listy wszystkich skrótów obecnych w bazie danych.

ClientInfo

Metadane klienta powiązane z żądaniami interfejsu API Bezpiecznego przeglądania.

Pola
client_id

string

Identyfikator klienta, który (miejmy nadzieję) jednoznacznie identyfikuje implementację interfejsu Safe Browsing API.
client_version

string

Wersja implementacji klienta.

CompressionType

Sposoby kompresowania zestawów wpisów dotyczących zagrożeń.

Wartości w polu enum
COMPRESSION_TYPE_UNSPECIFIED Nieznany.
RAW Nieprzetworzone, nieskompresowane dane.
RICE Dane zakodowane algorytmem Rice-Golomb.

FetchThreatListUpdatesRequest

Opisuje żądanie aktualizacji interfejsu API Bezpiecznego przeglądania. Klienci mogą poprosić o aktualizację wielu list w jednym żądaniu. Serwer może nie odpowiadać na niektóre żądania, jeśli nie ma żadnych aktualizacji dotyczących tej listy. UWAGA: indeks pola 2 nie jest używany. DALEJ: 5

Pola
client

ClientInfo

Metadane klienta.
list_update_requests[]

ListUpdateRequest

Zaktualizowana lista zagrożeń.

ListUpdateRequest

jedna prośba o zaktualizowanie listy.

Pola
threat_type

ThreatType

Rodzaj zagrożenia związanego z wpisami na liście.
platform_type

PlatformType

Typ platformy, która jest zagrożona, według wpisów na liście.
threat_entry_type

ThreatEntryType

Typy wpisów na liście.
state

bytes

bieżący stan klienta na żądanej liście (zaszyfrowany stan klienta otrzymany z ostatniej pomyślnej aktualizacji listy).
constraints

Constraints

Ograniczenia związane z tą prośbą.

Ograniczenia

Ograniczenia tej aktualizacji.

Pola
max_update_entries

int32

Maksymalny rozmiar pod względem liczby wpisów. Aktualizacja nie będzie zawierać większej liczby pozycji niż ta wartość. Powinien być potęgą 2 mieszczącą się w zakresie od 2**10 do 2**20. Jeśli wartość wynosi 0, nie jest ustawiony limit rozmiaru aktualizacji.
max_database_entries

int32

Określa maksymalną liczbę wpisów, które klient chce mieć w bazie danych lokalnej dla określonej listy. Powinien być potęgą 2 mieszczącą się w zakresie od 2**10 do 2**20. Jeśli wartość wynosi 0, nie jest ustawiony limit rozmiaru bazy danych.
region

string

Wymaga listy dla określonej lokalizacji geograficznej. Jeśli nie jest ustawiony, serwer może wybrać tę wartość na podstawie adresu IP użytkownika. Oczekiwany jest format ISO 3166-1 alfa-2.
supported_compressions[]

CompressionType

Typy kompresji obsługiwane przez klienta.
language

string

Wymaga listy dla konkretnego języka. Oczekiwany jest format ISO 639 alfa-2.
device_location

string

Fizyczna lokalizacja klienta wyrażona jako kod regionu w formacie ISO 3166-1 alfa-2.

FetchThreatListUpdatesResponse

Pola
list_update_responses[]

ListUpdateResponse

Lista jest aktualizowana zgodnie z prośbami klientów. Liczba odpowiedzi może być mniejsza niż liczba żądań wysłanych przez klientów. Dzieje się tak na przykład, gdy na serwerze nie ma żadnych aktualizacji dotyczących danej listy.
minimum_wait_duration

Duration

Minimalny czas, przez jaki klient musi czekać, zanim prześle żądanie aktualizacji. Jeśli to pole nie jest ustawione, klienci mogą aktualizować aplikację w dowolnym momencie.

ListUpdateResponse

aktualizacja pojedynczej listy.

Pola
threat_type

ThreatType

Typ zagrożenia, którego dane są zwracane.
threat_entry_type

ThreatEntryType

Format gróźb.
platform_type

PlatformType

Typ platformy, dla której zwracane są dane.
response_type

ResponseType

Typ odpowiedzi. Może to oznaczać, że po otrzymaniu odpowiedzi klient musi podjąć określone działanie.
additions[]

ThreatEntrySet

Zestaw wpisów do dodania do listy lokalnego typu zagrożenia. Powtarzane, aby umożliwić wysyłanie w jednej odpowiedzi kombinacji skompresowanych i nieprzetworzonych danych.
removals[]

ThreatEntrySet

Zestaw wpisów do usunięcia z listy lokalnego typu zagrożenia. W praktyce to pole jest puste lub zawiera dokładnie jeden zestaw wpisów o zagrożeniach.
new_client_state

bytes

Nowy stan klienta w zaszyfrowanym formacie. Niewidoczne dla klientów.
checksum

Checksum

Oczekiwany skrót SHA256 stanu klienta, czyli posortowana lista wszystkich skrótów obecnych w bazie danych po zastosowaniu dostarczonej aktualizacji. Jeśli stan klienta nie odpowiada oczekiwanemu stanowi, klient musi zignorować tę aktualizację i spróbować ponownie później.

ResponseType

Typ odpowiedzi wysłanej do klienta.

Wartości w polu enum
RESPONSE_TYPE_UNSPECIFIED Nieznany.
PARTIAL_UPDATE Częściowe aktualizacje są stosowane do istniejącej bazy danych klienta.
FULL_UPDATE Pełne aktualizacje zastępują całą lokalną bazę danych klienta. Oznacza to, że klient był bardzo przestarzały lub uszkodzony.

FindFullHashesRequest

Żądanie zwrócenia pełnych haszy dopasowanych do podanych prefiksów.

Pola
client

ClientInfo

Metadane klienta.
client_states[]

bytes

Obecne stany klienta dla każdej z lokalnych list zagrożeń klienta.
threat_info

ThreatInfo

listy i łańcuchy haszowe do sprawdzenia.
api_client

ClientInfo

Metadane klienta powiązane z wywoływającymi interfejsami API wyższego poziomu, które zostały stworzone na podstawie implementacji klienta.

FindFullHashesResponse

Pola
matches[]

ThreatMatch

Całkowite wartości haszujące, które pasują do żądanych prefiksów.
minimum_wait_duration

Duration

Minimalny czas, przez jaki klient musi czekać, zanim wyśle żądanie znajdowania haszy. Jeśli to pole nie jest ustawione, klienci mogą wysyłać żądania w dowolnym momencie.
negative_cache_duration

Duration

W przypadku żądanych elementów, które nie pasują do listy zagrożeń, czas przechowywania odpowiedzi w pamięci podręcznej.

FindThreatMatchesRequest

Prośba o sprawdzenie wpisów na liście.

Pola
client

ClientInfo

Metadane klienta.
threat_info

ThreatInfo

listy i wpisy, które mają być sprawdzane pod kątem dopasowań;

FindThreatMatchesResponse

Pola
matches[]

ThreatMatch

Lista zagrożeń jest taka sama.

ListThreatListsResponse

Pola
threat_lists[]

ThreatListDescriptor

listy dostępne do pobrania przez klienta.

PlatformType

Typy platform

Wartości w polu enum
PLATFORM_TYPE_UNSPECIFIED Nieznana platforma.
WINDOWS Zagrożenie dla systemu Windows.
LINUX Zagrożenie dla Linuksa.
ANDROID Zagrożenie dla Androida.
OSX Zagrożenie dla systemu operacyjnego OS X.
IOS Zagrożenie dla iOS.
ANY_PLATFORM Zagrożenie dla co najmniej jednej z zdefiniowanych platform.
ALL_PLATFORMS Zagrożenie dla wszystkich zdefiniowanych platform.
CHROME Zagrożenie dla Chrome.

RawHashes

Nieskompresowane wpisy zagrożeń w formacie hasz o określonej długości prefiksu. Rozmiar hasha może wynosić od 4 do 32 bajtów. Większość z nich to 4 bajty, ale niektóre hashe są dłuższe, jeśli kolidują z hashem popularnego adresu URL.

Służy do wysyłania zestawu ThreatEntry do klientów, którzy nie obsługują kompresji, lub do wysyłania haszy niebędących 4-bajtowymi haszami do klientów, którzy obsługują kompresję.

Pola
prefix_size

int32

Liczba bajtów dla każdego zaszyfrowanego poniżej prefiksu. To pole może zawierać od 4 (najkrótszy prefiks) do 32 znaków (pełny ciąg znaków SHA256).
raw_hashes

bytes

hashy w formacie binarnym połączone w jeden długi ciąg znaków; Hasze są sortowane w kolejności alfabetycznej. W przypadku użytkowników interfejsu JSON API szyfry są kodowane w formacie Base64.

RawIndices

Zestaw indeksów surowych do usunięcia z listy lokalnej.

Pola
indices[]

int32

Indeksy do usunięcia z posortowanej alfabetycznie listy lokalnej.

RiceDeltaEncoding

Dane zakodowane algorytmem Rice-Golomb. Służy do wysyłania skompresowanych haszy 4-bajtowych lub skompresowanych indeksów usuwania.

Pola
first_value

int64

Odsunięcie pierwszego wpisu w zakodowanych danych lub, jeśli zakodowano tylko jedną liczbę całkowitą, jej wartość. Jeśli pole jest puste lub nie można go odnaleźć, przyjmuje się wartość 0.
rice_parameter

int32

parametr Golomb-Rice, który jest liczbą z zakresu od 2 do 28; To pole jest puste (czyli ma wartość 0), jeśli num_entries ma wartość 0.
num_entries

int32

Liczba wpisów zakodowanych w danych zakodowanych za pomocą kodowania delty. Jeśli zakodowana została tylko jedna liczba całkowita, będzie ona równa 0, a jedyna wartość zostanie zapisana w polu first_value.
encoded_data

bytes

zakodowane delty, które są kodowane za pomocą kodera Golomb-Rice;

ThreatEntry

pojedyncza groźba, np. złośliwy adres URL lub jego reprezentacja w postaci hasha; Należy ustawić tylko jedno z tych pól.

Pola
hash

bytes

Prefiks skrótu, który składa się z 4–32 najbardziej znaczących bajtów identyfikatora SHA-256. To pole ma format binarny. W przypadku żądań JSON hasze są kodowane w formacie Base64.
url

string

adres URL,
digest

bytes

Skrót pliku wykonywalnego w formacie SHA256. Interfejs API obsługuje zarówno sumę kontrolną w postaci binarnej, jak i szesnastkowej. W przypadku żądań JSON skróty są kodowane w formacie Base64.

ThreatEntryMetadata

Metadane powiązane z konkretnym wpisem dotyczącym zagrożenia. Klient powinien znać pary klucz/wartość metadanych powiązane z każdym typem zagrożenia.

Pola
entries[]

MetadataEntry

Wpisy metadanych.

MetadataEntry

pojedynczy wpis metadanych;

Pola
key

bytes

Klucz wpisu metadanych. W przypadku żądań JSON klucz jest kodowany w formacie Base64.
value

bytes

Wartość wpisu metadanych. W przypadku żądań JSON wartość jest kodowana w formacie Base64.

ThreatEntrySet

Zestaw zagrożeń, które należy dodać do bazy danych klienta lub z niej usunąć.

Pola
compression_type

CompressionType

Typ kompresji wpisów w tym zbiorze.
raw_hashes

RawHashes

Nieprzetworzone wpisy w formacie SHA256.
raw_indices

RawIndices

Surowe indeksy usunięcia dla listy lokalnej.
rice_hashes

RiceDeltaEncoding

Zakodowane 4-bajtowe prefiksy wpisów w formacie SHA256 za pomocą kodowania Golomb-Rice. Hasze są konwertowane na uint32, sortowane w kolejności rosnącej, a następnie kodowane delta i zapisywane jako encoded_data.
rice_indices

RiceDeltaEncoding

Zakodowane lokalne indeksy list posortowane leksykograficznie za pomocą kodowania Golomb-Rice. Służy do wysyłania skompresowanych indeksów usuwania. Indeksy usuwania (uint32) są sortowane w kolejności rosnącej, a następnie kodowane i przechowywane jako zakodowane_dane.

ThreatEntryType

Typy wpisów, które stanowią zagrożenie. Listy zagrożeń to zbiory wpisów jednego typu.

Wartości w polu enum
THREAT_ENTRY_TYPE_UNSPECIFIED Nie określono.
URL adres URL,
EXECUTABLE Plik wykonywalny.

ThreatInfo

Informacje o co najmniej 1 zagrożeniu, które klient przesyła podczas sprawdzania dopasowań na listach zagrożeń.

Pola
threat_types[]

ThreatType

Typy zagrożeń do sprawdzenia.
platform_types[]

PlatformType

Typy platform, które mają być sprawdzane.
threat_entry_types[]

ThreatEntryType

Typy wpisów do sprawdzenia.
threat_entries[]

ThreatEntry

Wpisy zagrożeń do sprawdzenia.

ThreatListDescriptor

Opis pojedynczej listy zagrożeń. Lista jest definiowana przez 3 parametry: typ zagrożenia, typ platformy, na której występuje zagrożenie, oraz typ wpisów na liście.

Pola
threat_type

ThreatType

Typ zagrożenia związanego z elementami na liście.
platform_type

PlatformType

Typ platformy objętej kierowaniem przez wpisy na liście.
threat_entry_type

ThreatEntryType

Typy wpisów na liście.

ThreatMatch

Dopasowanie podczas sprawdzania wpisu zagrożenia na listach zagrożeń Bezpiecznego przeglądania.

Pola
threat_type

ThreatType

Typ zagrożenia pasujący do tego zagrożenia.
platform_type

PlatformType

Typ platformy pasujący do tego zagrożenia.
threat_entry_type

ThreatEntryType

Typ wpisu o zagrożeniu odpowiadający temu zagrożeniu.
threat

ThreatEntry

Zagrożenie pasujące do tego zagrożenia.
threat_entry_metadata

ThreatEntryMetadata

Opcjonalne metadane powiązane z tym zagrożeniem.
cache_duration

Duration

Czas przechowywania w pamięci podręcznej zwróconego dopasowania. Aby uniknąć wyników fałszywie dodatnich, klienci nie mogą przechowywać w pamięci podręcznej tej odpowiedzi przez dłuższy czas.

ThreatType

Rodzaje zagrożeń

Wartości w polu enum
THREAT_TYPE_UNSPECIFIED Nieznany.
MALWARE Typ zagrożenia związanego ze złośliwym oprogramowaniem.
SOCIAL_ENGINEERING Typ zagrożenia związanego z inżynierią społeczną.
UNWANTED_SOFTWARE Typ zagrożenia związanego z niechcianym oprogramowaniem.
POTENTIALLY_HARMFUL_APPLICATION Typ zagrożenia związanego z potencjalnie szkodliwą aplikacją.