Method: hashes.search

Wyszukaj pełne hasze pasujące do określonych prefiksów.

Jest to metoda niestandardowa zdefiniowana na stronie https://google.aip.dev/136 (metoda niestandardowa oznacza jej niestandardową nazwę zgodnie z ogólną nazwą programistyczną interfejsu API Google – nie odnosi się do używania niestandardowej metody HTTP).

Żądanie HTTP

GET https://safebrowsing.googleapis.com/v5/hashes:search

Adres URL używa składni transkodowania gRPC.

Parametry zapytania

Parametry
hashPrefixes[]

string (bytes format)

To pole jest wymagane. Prefiksy skrótu do wyszukania. Klienty NIE MOGĄ wysyłać więcej niż 1000 prefiksów skrótów. Pamiętaj jednak, że zgodnie z procedurą przetwarzania adresów URL klienci NIE MUSZĄ wysyłać więcej niż 30 prefiksów haszujących.

Obecnie każdy prefiks skrótu musi mieć dokładnie 4 bajty. W przyszłości MOGĄ się uspokoić.

Ciąg zakodowany w standardzie base64.

Treść żądania

Treść żądania musi być pusta.

Treść odpowiedzi

Odpowiedź zwrócona po wyszukaniu haszów zagrożeń.

Jeśli nic nie zostanie znalezione, serwer zwróci stan OK (kod stanu HTTP 200) i pole fullHashes jest puste, a nie zwróci stan NOT_FOUND (kod stanu HTTP 404).

Nowości w wersji 5: istnieje rozdzielenie między opcjami FullHash i FullHashDetail. W przypadku, gdy hasz reprezentuje witrynę, w której występuje wiele zagrożeń (np. MALWARE i SOCIAL_ENGINEERING), nie trzeba wysyłać pełnego haszy dwa razy niż w wersji 4. Poza tym czas trwania pamięci podręcznej został uproszczony do pojedynczego pola cacheDuration.

W przypadku powodzenia treść żądania zawiera dane o następującej strukturze:

Zapis JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Pola
fullHashes[]

object (FullHash)

Lista nieuporządkowana. Nieuporządkowana lista pełnych haszów.
cacheDuration

string (Duration format)

Czas trwania pamięci podręcznej po stronie klienta. Klient MUSI dodać ten czas trwania do bieżącego czasu, aby określić czas wygaśnięcia. Czas wygaśnięcia jest następnie stosowany do każdego prefiksu skrótu, którego dotyczy zapytanie klienta w żądaniu, niezależnie od tego, ile pełnych haszów jest zwróconych w odpowiedzi. Nawet jeśli serwer nie zwraca pełnych haszów dla konkretnego prefiksu skrótu, ta informacja MUSI też znajdować się w pamięci podręcznej klienta.

Ważne: klient NIE MOŻE zakładać, że serwer zwróci ten sam czas trwania pamięci podręcznej dla wszystkich odpowiedzi. Serwer MOŻE wybrać różne czasy trwania pamięci podręcznej dla różnych odpowiedzi w zależności od sytuacji.

Czas trwania w sekundach z maksymalnie 9 cyframi po przecinku, kończącym się cyframi „s”. Przykład: "3.5s".

FullHash

Pełny hasz z co najmniej 1 dopasowaniem.

Zapis JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Pola
fullHash

string (bytes format)

Pasujący hasz. Jest to hasz SHA256. Będzie ona miała dokładnie 32 bajty.

Ciąg zakodowany w standardzie base64.
fullHashDetails[]

object (FullHashDetail)

Lista nieuporządkowana. Pole powtarzane identyfikujące szczegóły związane z tym pełnym haszem.

FullHashDetail

Szczegółowe informacje o pasującej pełnej wartości hash.

Ważna uwaga dotycząca zgodności z przejściem: serwer może w każdej chwili dodawać nowe typy zagrożeń i atrybuty zagrożeń. Takie dodatki są uznawane za drobne zmiany w wersji. Zgodnie z zasadami Google nie ujawniamy numerów wersji podrzędnych w interfejsach API (informacje o zasadach obsługi wersji znajdziesz na stronie https://cloud.google.com/apis/design/versioning). Klienci MUSZĄ przygotować się na otrzymanie wiadomości FullHashDetail z wartościami wyliczeniowymi ThreatType lub wartościami wyliczenia ThreatAttribute, które zostały uznane przez klienta za nieprawidłowe. Dlatego obowiązkiem klienta jest sprawdzenie poprawności wszystkich wartości wyliczeniowych ThreatType i ThreatAttribute. Jeśli którakolwiek wartość zostanie uznana za nieprawidłową, klient MUSI zignorować cały komunikat FullHashDetail.

Zapis JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Pola
threatType

enum (ThreatType)

Rodzaj zagrożenia. To pole nigdy nie jest puste.
attributes[]

enum (ThreatAttribute)

Lista nieuporządkowana. Atrybuty dodatkowe dotyczące tych pełnych haszów. To pole może być puste.

ThreatType

Typy zagrożeń.

Wartości w polu enum
THREAT_TYPE_UNSPECIFIED Nieznany typ zagrożenia. Jeśli zostanie ona zwrócona przez serwer, klient całkowicie zignoruje treść FullHashDetail.
MALWARE

Rodzaj zagrożenia związany ze złośliwym oprogramowaniem. Termin „złośliwe oprogramowanie” odnosi się do programów komputerowych lub aplikacji mobilnych zaprojektowanych specjalnie w celu zaszkodzenia użytkownikom lub zakłócania pracy komputera, urządzenia mobilnego bądź zainstalowanych na nim aplikacji. Działanie złośliwego oprogramowania objawia się instalowaniem programów bez zgody użytkownika lub instalowaniem szkodliwych aplikacji, np. wirusów.

Więcej informacji znajdziesz tutaj.
SOCIAL_ENGINEERING

Rodzaj zagrożenia związany z inżynierią społeczną. Strony stosujące inżynierię społeczną fałszywie sugerują, że działają w imieniu osoby trzeciej w celu skłonienia widzów do wykonania czynności, którą widz zaufałby wyłącznie prawdziwemu przedstawicielowi tej firmy. Phishing (wyłudzanie informacji) to rodzaj inżynierii społecznej, który polega na nakłonieniu widza do wykonania określonej czynności polegającej na udostępnieniu informacji, takich jak dane logowania.

Więcej informacji znajdziesz tutaj.
UNWANTED_SOFTWARE Typ zagrożenia związanego z niechcianym oprogramowaniem. Niechciane oprogramowanie to takie, które nie jest zgodne z zasadami Google dotyczącymi oprogramowania, ale nie jest złośliwym oprogramowaniem.
POTENTIALLY_HARMFUL_APPLICATION Potencjalnie szkodliwy rodzaj zagrożenia dla aplikacji wykorzystywany przez Google Play Protect w Sklepie Play.

ThreatAttribute

Cechy gróźb. Te atrybuty mogą nadać dodatkowe znaczenie określonemu zagrożeniu, ale nie mają wpływu na jego typ. Na przykład atrybut może określać niższy poziom ufności, a inny – wyższy. W przyszłości możemy dodać więcej atrybutów.

Wartości w polu enum
THREAT_ATTRIBUTE_UNSPECIFIED Nieznany atrybut. Jeśli zostanie ona zwrócona przez serwer, klient całkowicie zignoruje treść FullHashDetail.
CANARY Wskazuje, że do egzekwowania zasad nie należy używać obiektu threatType.
FRAME_ONLY Wskazuje, że typ threatType powinien być używany tylko do egzekwowania zasad dotyczących ramek.