Package google.security.safebrowsing.v4

Indice

SafeBrowsing

Le API Navigazione sicura consentono ai client di verificare le risorse web (solitamente gli URL) rispetto agli elenchi costantemente aggiornati di risorse web non sicure di Google. Le API di Navigazione sicura (v4) includono l'API Update e l'API Lookup.

L'API Update è progettata per i nostri clienti più grandi e include i metodi FindFullHashes e FetchThreatListUpdates . L'API Update richiede che i client gestiscano gli elenchi di minacce scaricati in un database locale.

Innanzitutto, i client eseguono una ricerca nei propri elenchi locali per determinare lo stato (sicuro o non sicuro) di una determinata risorsa web. In genere, gli elenchi sono costituiti da prefissi hash delle espressioni URL inserite nella lista nera. Per controllare un URL, i client generano gli hash di un determinato URL e controllano la presenza di collisioni di prefisso nei loro elenchi locali. Se viene trovata una corrispondenza del prefisso, il client ottiene gli hash completi associati al prefisso dell'hash corrispondente tramite il metodo FindFullHashes. Il client confronta quindi l'hash completo locale con gli hash completi restituiti. Una corrispondenza indica che l'URL non è sicuro.

In secondo luogo, i client ottengono gli aggiornamenti dei propri database locali tramite il metodo FetchThreatListUpdates , che prende lo stato corrente del client e restituisce uno stato del client aggiornato insieme alle modifiche che il client deve applicare ai propri elenchi di minacce locali.

L'API Lookup è progettata per i nostri clienti più piccoli e consente loro di associare le risorse direttamente agli elenchi di minacce di Navigazione sicura tramite il metodo FindThreatMatches.

I client che utilizzano l'API Update o l'API Lookup possono ottenere un elenco degli elenchi di minacce di Navigazione sicura disponibili per il download tramite il metodo ListThreatLists.

{-- TRUSTED_THREAT_REPORTER: i client di segnalazione delle minacce attendibili possono inviare segnalazioni a Google per l'analisi tramite il metodo SubmitThreatReport. --}

FetchThreatListUpdates

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

Recupera gli aggiornamenti più recenti dell'elenco delle minacce. Un client può richiedere aggiornamenti per più elenchi contemporaneamente.
FindFullHashes

rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)

Trova gli hash completi che corrispondono ai prefissi degli hash richiesti.
FindThreatMatches

rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)

Individua le voci di minaccia corrispondenti agli elenchi di Navigazione sicura.
ListThreatLists

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

Elenca gli elenchi di minacce di Navigazione sicura disponibili per il download.

Checksum

Lo stato previsto del database locale di un client.

Campi
sha256

bytes

L'hash SHA256 dello stato del client, ovvero dell'elenco ordinato di tutti gli hash presenti nel database.

ClientInfo

I metadati del client associati alle richieste dell'API Navigazione sicura.

Campi
client_id

string

Un ID cliente che (si spera) identifica in modo univoco l'implementazione client dell'API Safe Browsing.
client_version

string

La versione dell'implementazione del client.

CompressionType

I modi in cui i set di voci di minaccia possono essere compressi.

Enum
COMPRESSION_TYPE_UNSPECIFIED Sconosciuto.
RAW Dati non elaborati e non compressi.
RICE Dati codificati Rice-Golomb.

FetchThreatListUpdatesRequest

Descrive una richiesta di aggiornamento dell'API Safe Browsing. I clienti possono richiedere aggiornamenti per più elenchi in un'unica richiesta. Il server potrebbe non rispondere a tutte le richieste se non ha aggiornamenti per l'elenco. NOTA: l'indice di campo 2 non è utilizzato. SUCCESSIVO: 5

Campi
client

ClientInfo

I metadati del client.
list_update_requests[]

ListUpdateRequest

Gli aggiornamenti dell'elenco delle minacce richiesti.

ListUpdateRequest

Una singola richiesta di aggiornamento dell'elenco.

Campi
threat_type

ThreatType

Il tipo di minaccia rappresentata dalle voci presenti nell'elenco.
platform_type

PlatformType

Il tipo di piattaforma a rischio in base alle voci presenti nell'elenco.
threat_entry_type

ThreatEntryType

I tipi di voci presenti nell'elenco.
state

bytes

Lo stato corrente del client per l'elenco richiesto (lo stato del client criptato ricevuto dall'ultimo aggiornamento dell'elenco riuscito).
constraints

Constraints

I vincoli associati a questa richiesta.

Vincoli

I vincoli per questo aggiornamento.

Campi
max_update_entries

int32

La dimensione massima in numero di voci. L'aggiornamento non conterrà più voci di questo valore. Deve essere una potenza di 2 compresa tra 2**10 e 2**20. Se è pari a zero, non è impostato alcun limite di dimensioni dell'aggiornamento.
max_database_entries

int32

Imposta il numero massimo di voci che il client è disposto ad avere nel database locale per l'elenco specificato. Deve essere una potenza di 2 compresa tra 2**10 e 2**20. Se è pari a zero, non è impostato alcun limite di dimensione del database.
region

string

Richiede l'elenco per una località geografica specifica. Se non è impostato, il server potrebbe scegliere questo valore in base all'indirizzo IP dell'utente. Deve essere nel formato ISO 3166-1 alpha-2.
supported_compressions[]

CompressionType

I tipi di compressione supportati dal client.
language

string

Richiede gli elenchi per una lingua specifica. Deve essere nel formato ISO 639 alpha-2.
device_location

string

La posizione fisica di un cliente, espressa come codice regione ISO 31166-1 alpha-2.

FetchThreatListUpdatesResponse

Campi
list_update_responses[]

ListUpdateResponse

Gli aggiornamenti dell'elenco richiesti dai clienti. Il numero di risposte riportato qui potrebbe essere inferiore al numero di richieste inviate dai clienti. Questo accade, ad esempio, se il server non ha aggiornamenti per un determinato elenco.
minimum_wait_duration

Duration

La durata minima che il client deve attendere prima di inviare una richiesta di aggiornamento. Se questo campo non è impostato, i clienti possono eseguire l'aggiornamento quando vogliono.

ListUpdateResponse

Un aggiornamento di un singolo elenco.

Campi
threat_type

ThreatType

Il tipo di minaccia per cui vengono restituiti i dati.
threat_entry_type

ThreatEntryType

Il formato delle minacce.
platform_type

PlatformType

Il tipo di piattaforma per cui vengono restituiti i dati.
response_type

ResponseType

Il tipo di risposta. Ciò potrebbe indicare che il cliente richiede un'azione al momento della ricezione della risposta.
additions[]

ThreatEntrySet

Un insieme di voci da aggiungere all'elenco di un tipo di minaccia locale. Ripetuto per consentire l'invio di una combinazione di dati compressi e non elaborati in una singola risposta.
removals[]

ThreatEntrySet

Un insieme di voci da rimuovere dall'elenco di un tipo di minaccia locale. In pratica, questo campo è vuoto o contiene esattamente un ThreatEntrySet.
new_client_state

bytes

Il nuovo stato del client, in formato criptato. Non trasparente per i clienti.
checksum

Checksum

L'hash SHA256 previsto dello stato del client, ovvero dell'elenco ordinato di tutti gli hash presenti nel database dopo l'applicazione dell'aggiornamento fornito. Se lo stato del client non corrisponde a quello previsto, il client deve ignorare questo aggiornamento e riprovare in un secondo momento.

ResponseType

Il tipo di risposta inviata al client.

Enum
RESPONSE_TYPE_UNSPECIFIED Sconosciuto.
PARTIAL_UPDATE Gli aggiornamenti parziali vengono applicati al database locale esistente del cliente.
FULL_UPDATE Gli aggiornamenti completi sostituiscono l'intero database locale del client. Ciò significa che il client era gravemente obsoleto o che si ritiene sia danneggiato.

FindFullHashesRequest

Richiedi di restituire gli hash completi corrispondenti ai prefissi hash forniti.

Campi
client

ClientInfo

I metadati del client.
client_states[]

bytes

Gli stati attuali del client per ciascuno degli elenchi di minacce locali del client.
threat_info

ThreatInfo

Gli elenchi e gli hash da controllare.
api_client

ClientInfo

Metadati del client associati agli utenti chiamanti di API di livello superiore create in base all'implementazione del client.

FindFullHashesResponse

Campi
matches[]

ThreatMatch

Gli hash completi corrispondenti ai prefissi richiesti.
minimum_wait_duration

Duration

La durata minima che il client deve attendere prima di emettere una richiesta di ricerca di hash. Se questo campo non è impostato, i client possono inviare una richiesta in qualsiasi momento.
negative_cache_duration

Duration

Per le entità richieste che non corrispondono all'elenco delle minacce, il tempo di memorizzazione nella cache della risposta.

FindThreatMatchesRequest

Richiedi di controllare le voci in base agli elenchi.

Campi
client

ClientInfo

I metadati del client.
threat_info

ThreatInfo

Gli elenchi e le voci da controllare per le corrispondenze.

FindThreatMatchesResponse

Campi
matches[]

ThreatMatch

L'elenco delle minacce corrisponde.

ListThreatListsResponse

Campi
threat_lists[]

ThreatListDescriptor

Gli elenchi disponibili per il download da parte del cliente.

PlatformType

Tipi di piattaforme.

Enum
PLATFORM_TYPE_UNSPECIFIED Piattaforma sconosciuta.
WINDOWS Minaccia per Windows.
LINUX Minaccia rappresentata per Linux.
ANDROID Minaccia rappresentata per Android.
OSX Minaccia rappresentata per OS X.
IOS Minaccia per iOS.
ANY_PLATFORM Minaccia rappresentata per almeno una delle piattaforme definite.
ALL_PLATFORMS Minaccia rappresentata per tutte le piattaforme definite.
CHROME Minaccia rappresentata per Chrome.

RawHashes

Le voci delle minacce non compresse in formato hash di una determinata lunghezza del prefisso. Gli hash possono avere una dimensione compresa tra 4 e 32 byte. La maggior parte è di 4 byte, ma alcuni hash vengono allungati se entrano in conflitto con l'hash di un URL popolare.

Utilizzato per inviare ThreatEntrySet a client che non supportano la compressione o per inviare hash diversi da 4 byte a client che supportano la compressione.

Campi
prefix_size

int32

Il numero di byte per ogni prefisso codificato di seguito. Questo campo può variare da 4 (prefisso più breve) a 32 (hash SHA256 completo).
raw_hashes

bytes

Gli hash, in formato binario, concatenati in una lunga stringa. Gli hash sono ordinati in ordine lessicografico. Per gli utenti dell'API JSON, gli hash sono codificati in base64.

RawIndices

Un insieme di indici non elaborati da rimuovere da un elenco locale.

Campi
indices[]

int32

Gli indici da rimuovere da un elenco locale ordinato in ordine alfabetico.

RiceDeltaEncoding

I dati codificati Rice-Golomb. Utilizzato per l'invio di hash compressi di 4 byte o di indici di rimozione compressi.

Campi
first_value

int64

L'offset della prima voce nei dati codificati o, se è stato codificato un solo numero intero, il valore di quel numero intero. Se il campo è vuoto o mancante, si presume zero.
rice_parameter

int32

Il parametro Golomb-Rice, che è un numero compreso tra 2 e 28. Questo campo non è presente (ovvero è pari a zero) se num_entries è pari a zero.
num_entries

int32

Il numero di voci con codifica delta nei dati codificati. Se è stato codificato un solo numero intero, questo sarà zero e il singolo valore verrà memorizzato in first_value.
encoded_data

bytes

I delta codificati che vengono codificati utilizzando il codificatore Golomb-Rice.

ThreatEntry

Una singola minaccia, ad esempio un URL dannoso o la sua rappresentazione sotto forma di hash. Deve essere impostato solo uno di questi campi.

Campi
hash

bytes

Un prefisso hash costituito dai 4-32 byte più significativi di un hash SHA256. Questo campo è in formato binario. Per le richieste JSON, gli hash sono codificati in base64.
url

string

Un URL.
digest

bytes

Il digest di un file eseguibile in formato SHA256. L'API supporta i digest sia in formato binario che esadecimale. Per le richieste JSON, i digest sono codificati in base64.

ThreatEntryMetadata

I metadati associati a una voce di minaccia specifica. Il cliente deve conoscere le coppie chiave/valore dei metadati associate a ogni tipo di minaccia.

Campi
entries[]

MetadataEntry

Le voci dei metadati.

MetadataEntry

Una singola voce di metadati.

Campi
key

bytes

La chiave di accesso ai metadati. Per le richieste JSON, la chiave è codificata in base64.
value

bytes

Il valore della voce dei metadati. Per le richieste JSON, il valore è codificato in base64.

ThreatEntrySet

Un insieme di minacce da aggiungere o rimuovere dal database locale di un cliente.

Campi
compression_type

CompressionType

Il tipo di compressione per le voci in questo set.
raw_hashes

RawHashes

Le voci non elaborate in formato SHA256.
raw_indices

RawIndices

Gli indici di rimozione non elaborati per un elenco locale.
rice_hashes

RiceDeltaEncoding

I prefissi codificati di 4 byte delle voci con formato SHA256, utilizzando una codifica Golomb-Rice. Gli hash vengono convertiti in uint32, ordinati in ordine crescente, poi codificati in delta e archiviati come encoded_data.
rice_indices

RiceDeltaEncoding

Gli indici degli elenchi locali codificati e ordinati in ordine alfabetico, utilizzando una codifica Golomb-Rice. Utilizzato per l'invio di indici di rimozione compressi. Gli indici di rimozione (uint32) sono ordinati in ordine crescente, poi codificati in delta e archiviati come encoded_data.

ThreatEntryType

Tipi di voci che rappresentano minacce. Gli elenchi di minacce sono raccolte di voci di un singolo tipo.

Enum
THREAT_ENTRY_TYPE_UNSPECIFIED Non specificato.
URL Un URL.
EXECUTABLE Un programma eseguibile.

ThreatInfo

Le informazioni relative a una o più minacce inviate da un client durante la ricerca di corrispondenze negli elenchi di minacce.

Campi
threat_types[]

ThreatType

I tipi di minacce da controllare.
platform_types[]

PlatformType

I tipi di piattaforme da controllare.
threat_entry_types[]

ThreatEntryType

I tipi di voci da controllare.
threat_entries[]

ThreatEntry

Le voci di minaccia da controllare.

ThreatListDescriptor

Descrive un singolo elenco di minacce. Un elenco è definito da tre parametri: il tipo di minaccia rappresentata, il tipo di piattaforma presa di mira dalla minaccia e il tipo di voci nell'elenco.

Campi
threat_type

ThreatType

Il tipo di minaccia rappresentato dalle voci dell'elenco.
platform_type

PlatformType

Il tipo di piattaforma scelto come target dalle voci dell'elenco.
threat_entry_type

ThreatEntryType

I tipi di voci contenuti nell'elenco.

ThreatMatch

Una corrispondenza durante il controllo di una voce di minaccia negli elenchi delle minacce di Navigazione sicura.

Campi
threat_type

ThreatType

Il tipo di minaccia corrispondente.
platform_type

PlatformType

Il tipo di piattaforma corrispondente a questa minaccia.
threat_entry_type

ThreatEntryType

Il tipo di voce della minaccia corrispondente a questa minaccia.
threat

ThreatEntry

La minaccia corrispondente a questa minaccia.
threat_entry_metadata

ThreatEntryMetadata

Metadati facoltativi associati a questa minaccia.
cache_duration

Duration

La durata della cache per la corrispondenza restituita. Per evitare falsi positivi, i client non devono memorizzare nella cache questa risposta per più di questa durata.

ThreatType

Tipi di minacce.

Enum
THREAT_TYPE_UNSPECIFIED Sconosciuto.
MALWARE Tipo di minaccia malware.
SOCIAL_ENGINEERING Tipo di minaccia di ingegneria sociale.
UNWANTED_SOFTWARE Tipo di minaccia di software indesiderato.
POTENTIALLY_HARMFUL_APPLICATION Tipo di minaccia da app potenzialmente dannose.