Package google.security.safebrowsing.v4

Índice

SafeBrowsing

As APIs da Navegação segura permitem que os clientes verifiquem recursos da Web (geralmente URLs) nas listas de recursos da Web inseguros do Google, que são constantemente atualizadas. As APIs Safe Browsing (v4) incluem a API Update e a API Lookup.

A API Update foi projetada para nossos clientes maiores e inclui os métodos FindFullHashes e FetchThreatListUpdates . A API Update exige que os clientes mantenham as listas de ameaças salvas em um banco de dados local.

Primeiro, os clientes fazem a correspondência com as listas locais para determinar o estado (seguro ou não seguro) de um determinado recurso da Web. Normalmente, as listas são compostas de prefixos de hash de expressões de URL na lista de bloqueio. Para verificar um URL, os clientes geram os hashes de um determinado URL e verificam colisões de prefixo nas listas locais. Se uma correspondência de prefixo for encontrada, o cliente vai receber os hashes completos associados ao prefixo de hash correspondente pelo método FindFullHashes. Em seguida, o cliente compara o hash completo local com os hashes completos retornados. Uma correspondência indica que o URL não é seguro.

Em segundo lugar, os clientes recebem atualizações nos bancos de dados locais pelo método FetchThreatListUpdates , que recebe o estado atual do cliente e retorna um estado atualizado do cliente com as mudanças que o cliente precisa aplicar às listas de ameaças locais.

A API Lookup foi projetada para nossos clientes menores e permite que eles correspondam recursos diretamente às listas de ameaças da Navegação segura pelo método FindThreatMatches.

Os clientes que usam a API Update ou a API Lookup podem acessar uma lista das listas de ameaças do Safe Browsing disponíveis para download pelo método ListThreatLists.

{-- TRUSTED_THREAT_REPORTER: os clientes de ameaças confiáveis podem enviar relatórios ao Google para análise usando o método SubmitThreatReport. --}

FetchThreatListUpdates

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

Busca as atualizações mais recentes da lista de ameaças. Um cliente pode solicitar atualizações para várias listas de uma só vez.
FindFullHashes

rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)

Encontra os hashes completos que correspondem aos prefixos de hash solicitados.
FindThreatMatches

rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)

Encontra as entradas de ameaças que correspondem às listas do recurso Navegação segura.
ListThreatLists

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

Lista as listas de ameaças da Navegação segura disponíveis para download.

Soma de verificação

O estado esperado do banco de dados local de um cliente.

Campos
sha256

bytes

O hash SHA256 do estado do cliente, ou seja, da lista classificada de todos os hashes presentes no banco de dados.

ClientInfo

Os metadados do cliente associados às solicitações da API Safe Browsing.

Campos
client_id

string

Um ID de cliente que identifica exclusivamente a implementação do cliente da API Safe Browsing.
client_version

string

A versão da implementação do cliente.

CompressionType

As maneiras de compactar os conjuntos de entradas de ameaças.

Enums
COMPRESSION_TYPE_UNSPECIFIED Desconhecido.
RAW Dados brutos e não compactados.
RICE Dados codificados com Rice-Golomb.

FetchThreatListUpdatesRequest

Descreve uma solicitação de atualização da API Safe Browsing. Os clientes podem solicitar atualizações para várias listas em uma única solicitação. O servidor pode não responder a todas as solicitações se não tiver atualizações para essa lista. OBSERVAÇÃO: o índice de campo 2 não é usado. PRÓXIMA: 5

Campos
client

ClientInfo

Os metadados do cliente.
list_update_requests[]

ListUpdateRequest

As atualizações da lista de ameaças solicitadas.

ListUpdateRequest

Uma única solicitação de atualização de lista.

Campos
threat_type

ThreatType

O tipo de ameaça causado pelas entradas presentes na lista.
platform_type

PlatformType

O tipo de plataforma em risco pelas entradas presentes na lista.
threat_entry_type

ThreatEntryType

Os tipos de entradas presentes na lista.
state

bytes

O estado atual do cliente para a lista solicitada (o estado criptografado do cliente que foi recebido na última atualização bem-sucedida da lista).
constraints

Constraints

As restrições associadas a essa solicitação.

Restrições

As restrições para esta atualização.

Campos
max_update_entries

int32

O tamanho máximo em número de entradas. A atualização não vai conter mais entradas do que esse valor. Esse valor precisa ser uma potência de 2 entre 2**10 e 2**20. Se for zero, nenhum limite de tamanho de atualização será definido.
max_database_entries

int32

Define o número máximo de entradas que o cliente quer ter no banco de dados local para a lista especificada. Esse valor precisa ser uma potência de 2 entre 2**10 e 2**20. Se for zero, nenhum limite de tamanho do banco de dados será definido.
region

string

Solicita a lista de um local geográfico específico. Se não for definido, o servidor poderá escolher esse valor com base no endereço IP do usuário. Espera o formato ISO 3166-1 alfa-2.
supported_compressions[]

CompressionType

Os tipos de compactação aceitos pelo cliente.
language

string

Solicita as listas de um idioma específico. Espera o formato ISO 639 alfa-2.
device_location

string

O local físico de um cliente, expresso como um código regional ISO 31166-1 alfa-2.

FetchThreatListUpdatesResponse

Campos
list_update_responses[]

ListUpdateResponse

As atualizações de lista solicitadas pelos clientes. O número de respostas aqui pode ser menor do que o número de solicitações enviadas pelos clientes. Isso acontece, por exemplo, se o servidor não tiver atualizações para uma lista específica.
minimum_wait_duration

Duration

A duração mínima que o cliente precisa aguardar antes de emitir qualquer solicitação de atualização. Se esse campo não estiver definido, os clientes poderão atualizar quando quiserem.

ListUpdateResponse

Uma atualização de uma lista individual.

Campos
threat_type

ThreatType

O tipo de ameaça para o qual os dados são retornados.
threat_entry_type

ThreatEntryType

O formato das ameaças.
platform_type

PlatformType

O tipo de plataforma para a qual os dados são retornados.
response_type

ResponseType

O tipo de resposta. Isso pode indicar que uma ação é necessária pelo cliente quando a resposta é recebida.
additions[]

ThreatEntrySet

Um conjunto de entradas a serem adicionadas à lista de um tipo de ameaça local. Repetido para permitir que uma combinação de dados compactados e brutos seja enviada em uma única resposta.
removals[]

ThreatEntrySet

Um conjunto de entradas a serem removidas da lista de um tipo de ameaça local. Na prática, esse campo está vazio ou contém exatamente um ThreatEntrySet.
new_client_state

bytes

O novo estado do cliente, em formato criptografado. Oculto para os clientes.
checksum

Checksum

O hash SHA256 esperado do estado do cliente, ou seja, da lista classificada de todos os hashes presentes no banco de dados após a aplicação da atualização fornecida. Se o estado do cliente não corresponder ao esperado, ele vai precisar ignorar essa atualização e tentar novamente mais tarde.

ResponseType

O tipo de resposta enviada ao cliente.

Enums
RESPONSE_TYPE_UNSPECIFIED Desconhecido.
PARTIAL_UPDATE As atualizações parciais são aplicadas ao banco de dados local do cliente.
FULL_UPDATE As atualizações completas substituem todo o banco de dados local do cliente. Isso significa que o cliente estava desatualizado ou que ele está corrompido.

FindFullHashesRequest

Solicitação para retornar hashes completos correspondentes aos prefixos de hash fornecidos.

Campos
client

ClientInfo

Os metadados do cliente.
client_states[]

bytes

Os estados atuais do cliente para cada uma das listas de ameaças locais do cliente.
threat_info

ThreatInfo

As listas e os hashes a serem verificados.
api_client

ClientInfo

Metadados do cliente associados a autores de chamadas de APIs de nível superior criadas com base na implementação do cliente.

FindFullHashesResponse

Campos
matches[]

ThreatMatch

Os hashes completos que correspondem aos prefixos solicitados.
minimum_wait_duration

Duration

A duração mínima que o cliente precisa esperar antes de emitir uma solicitação de hashes de detecção. Se esse campo não estiver definido, os clientes poderão emitir uma solicitação quando quiserem.
negative_cache_duration

Duration

Para entidades solicitadas que não correspondem à lista de ameaças, por quanto tempo armazenar a resposta em cache.

FindThreatMatchesRequest

Solicitação para verificar as entradas em listas.

Campos
client

ClientInfo

Os metadados do cliente.
threat_info

ThreatInfo

As listas e entradas que serão verificadas para correspondências.

FindThreatMatchesResponse

Campos
matches[]

ThreatMatch

A lista de ameaças corresponde.

ListThreatListsResponse

Campos
threat_lists[]

ThreatListDescriptor

As listas disponíveis para download pelo cliente.

PlatformType

Tipos de plataformas.

Enums
PLATFORM_TYPE_UNSPECIFIED Plataforma desconhecida.
WINDOWS Ameaça apresentada ao Windows.
LINUX Ameaça apresentada ao Linux.
ANDROID Ameaça apresentada ao Android.
OSX Ameaça apresentada ao OS X.
IOS Ameaça apresentada ao iOS.
ANY_PLATFORM Ameaça a pelo menos uma das plataformas definidas.
ALL_PLATFORMS Ameaça apresentada a todas as plataformas definidas.
CHROME Ameaça apresentada ao Chrome.

RawHashes

As entradas de ameaça não compactadas em formato de hash de uma determinada extensão de prefixo. Os hashes podem ter de 4 a 32 bytes. A grande maioria tem 4 bytes, mas alguns hashes são alongados se colidirem com o hash de um URL conhecido.

É usado para enviar ThreatEntrySet a clientes que não oferecem suporte à compactação ou para enviar hashes de 4 bytes a clientes que oferecem suporte à compactação.

Campos
prefix_size

int32

O número de bytes de cada prefixo codificado abaixo. Esse campo pode variar de 4 (prefixo mais curto) a 32 (hash SHA256 completo).
raw_hashes

bytes

Os hashes, em formato binário, são concatenados em uma string longa. Os hashes são classificados em ordem lexicográfica. Para usuários da API JSON, os hashes são codificados em base64.

RawIndices

Um conjunto de índices brutos a serem removidos de uma lista local.

Campos
indices[]

int32

Os índices a serem removidos de uma lista local classificada em ordem alfabética.

RiceDeltaEncoding

Os dados codificados com Rice-Golomb. Usado para enviar hashes compactados de 4 bytes ou índices de remoção compactados.

Campos
first_value

int64

O deslocamento da primeira entrada nos dados codificados ou, se apenas um número inteiro foi codificado, o valor desse número inteiro. Se o campo estiver vazio ou ausente, considere o valor como zero.
rice_parameter

int32

O parâmetro Golomb-Rice, que é um número entre 2 e 28. Este campo está ausente (ou seja, zero) se num_entries for zero.
num_entries

int32

O número de entradas codificadas delta nos dados codificados. Se apenas um número inteiro for codificado, ele será zero e o valor único será armazenado em first_value.
encoded_data

bytes

As deltas codificadas usando o codificador Golomb-Rice.

ThreatEntry

Uma ameaça individual, por exemplo, um URL malicioso ou a representação de hash dele. Apenas um desses campos precisa ser definido.

Campos
hash

bytes

Um prefixo de hash, que consiste nos 4 a 32 bytes mais significativos de um hash SHA256. Esse campo está no formato binário. Para solicitações JSON, os hashes são codificados em base64.
url

string

Um URL.
digest

bytes

O resumo de um executável no formato SHA256. A API oferece suporte a resumos binários e hexadecimais. Para solicitações JSON, os resumos são codificados em base64.

ThreatEntryMetadata

Os metadados associados a uma entrada de ameaça específica. O cliente precisa conhecer os pares de chave-valor de metadados associados a cada tipo de ameaça.

Campos
entries[]

MetadataEntry

As entradas de metadados.

MetadataEntry

Uma única entrada de metadados.

Campos
key

bytes

A chave de entrada de metadados. Para solicitações JSON, a chave é codificada em base64.
value

bytes

O valor da entrada de metadados. Para solicitações JSON, o valor é codificado em base64.

ThreatEntrySet

Um conjunto de ameaças que precisam ser adicionadas ou removidas do banco de dados local de um cliente.

Campos
compression_type

CompressionType

O tipo de compactação das entradas neste conjunto.
raw_hashes

RawHashes

As entradas brutas formatadas em SHA256.
raw_indices

RawIndices

Os índices de remoção brutos de uma lista local.
rice_hashes

RiceDeltaEncoding

Os prefixos codificados de 4 bytes de entradas formatadas em SHA256, usando uma codificação Golomb-Rice. Os hashes são convertidos em uint32, classificados em ordem crescente e codificados em delta e armazenados como encoded_data.
rice_indices

RiceDeltaEncoding

Os índices de lista locais codificados e classificados lexicograficamente usando uma codificação Golomb-Rice. Usado para enviar índices de remoção compactados. Os índices de remoção (uint32) são classificados em ordem crescente, codificados em delta e armazenados como "encoded_data".

ThreatEntryType

Tipos de entradas que representam ameaças. As listas de ameaças são coleções de entradas de um único tipo.

Enums
THREAT_ENTRY_TYPE_UNSPECIFIED Não especificado.
URL Um URL.
EXECUTABLE Um programa executável.

ThreatInfo

As informações sobre uma ou mais ameaças que um cliente envia ao verificar correspondências em listas de ameaças.

Campos
threat_types[]

ThreatType

Os tipos de ameaça a serem verificados.
platform_types[]

PlatformType

Os tipos de plataforma a serem verificados.
threat_entry_types[]

ThreatEntryType

Os tipos de entrada a serem verificados.
threat_entries[]

ThreatEntry

As entradas de ameaças a serem verificadas.

ThreatListDescriptor

Descreve uma lista de ameaças individual. Uma lista é definida por três parâmetros: o tipo de ameaça, o tipo de plataforma alvo da ameaça e o tipo de entradas na lista.

Campos
threat_type

ThreatType

O tipo de ameaça causado pelas entradas da lista.
platform_type

PlatformType

O tipo de plataforma segmentado pelas entradas da lista.
threat_entry_type

ThreatEntryType

Os tipos de entrada contidos na lista.

ThreatMatch

Uma correspondência ao verificar uma entrada de ameaça nas listas de ameaças da Navegação segura.

Campos
threat_type

ThreatType

O tipo de ameaça correspondente a essa ameaça.
platform_type

PlatformType

O tipo de plataforma que corresponde a essa ameaça.
threat_entry_type

ThreatEntryType

O tipo de entrada de ameaça correspondente a essa ameaça.
threat

ThreatEntry

A ameaça correspondente a essa ameaça.
threat_entry_metadata

ThreatEntryMetadata

Metadados opcionais associados a essa ameaça.
cache_duration

Duration

A duração do cache para a correspondência retornada. Os clientes não podem armazenar essa resposta em cache por mais do que essa duração para evitar falsos positivos.

ThreatType

Tipos de ameaças.

Enums
THREAT_TYPE_UNSPECIFIED Desconhecido.
MALWARE Tipo de ameaça de malware.
SOCIAL_ENGINEERING Tipo de ameaça de engenharia social.
UNWANTED_SOFTWARE Tipo de ameaça de software indesejado.
POTENTIALLY_HARMFUL_APPLICATION Tipo de ameaça de app potencialmente nocivo.