Package google.security.safebrowsing.v4

Índice

SafeBrowsing

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

A API Update foi desenvolvida para nossos clientes maiores e inclui os métodos FindFullHashes e FetchThreatListUpdates . A API Update exige que os clientes mantenham listas de ameaças transferidas por download 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) de um determinado recurso da Web. Geralmente, as listas são compostas por prefixos de hash de expressões de URL em listas de proibições. Para verificar um URL, os clientes geram os hashes de um determinado URL e verificam se há conflitos de prefixos em suas listas locais. Se uma correspondência de prefixo for encontrada, o cliente obtém os hashes completos associados ao prefixo de hash correspondente por meio do 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 obtêm atualizações em seus bancos de dados locais através do método FetchThreatListUpdates , que pega o estado atual do cliente e retorna um estado atualizado do cliente juntamente com as alterações que o cliente deve aplicar às suas listas de ameaças locais.

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

Clientes que usam a API Update ou a API Lookup podem obter uma lista das listas de ameaças da Navegação segura disponíveis para download pelo método ListThreatLists.

{-- TRUSTED_THREAT_REPORTER: Clientes de ameaças confiáveis podem enviar relatórios ao Google para análise por meio do 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 ao mesmo tempo.
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 com ameaças que correspondem às listas da 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 (espera-se) identifique de forma exclusiva a implementação cliente da API Safe Browsing.
client_version

string

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

CompressionType

Os modos pelos quais os conjuntos de entradas de ameaças podem ser compactados.

Enums
COMPRESSION_TYPE_UNSPECIFIED Desconhecido.
RAW Dados brutos e não compactados.
RICE Dados codificados de arroz em 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 a lista. OBSERVAÇÃO: o índice de campo 2 não é usado. PRÓXIMO: 5

Campos
client

ClientInfo

Os metadados do cliente.
list_update_requests[]

ListUpdateRequest

A lista de ameaças solicitada é atualizada.

ListUpdateRequest

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

Campos
threat_type

ThreatType

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

PlatformType

O tipo de plataforma em risco de acordo com as 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 recebido na última atualização bem-sucedida da lista).
constraints

Constraints

As restrições associadas a esta 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 conterá mais entradas do que esse valor. Deve 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 está disposto a ter no banco de dados local para a lista especificada. Deve ser uma potência de 2 entre 2**10 e 2**20. Se for zero, nenhum limite de tamanho de banco de dados será definido.
region

string

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

CompressionType

Os tipos de compactação compatíveis com o cliente.
language

string

Solicita as listas para um idioma específico. Espera-se 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

Atualizações de lista solicitadas pelos clientes. O número de respostas pode ser menor que o número de solicitações enviadas pelos clientes. Isso acontece, por exemplo, quando o servidor não tem atualizações para determinada lista.
minimum_wait_duration

Duration

A duração mínima que o cliente precisa esperar antes de emitir qualquer solicitação de atualização. Se este campo não for definido, os clientes poderão ser atualizados assim que quiserem.

ListUpdateResponse

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 o qual os dados são retornados.
response_type

ResponseType

O tipo de resposta. Isso pode indicar que o cliente precisa realizar uma ação quando a resposta é recebida.
additions[]

ThreatEntrySet

Um conjunto de entradas a adicionar à 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. Opaco 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 atualização fornecida. Se o estado do cliente não corresponder ao estado esperado, o cliente deverá 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 seriamente desatualizado ou acredita-se que ele estivesse corrompido.

FindFullHashesRequest

Solicitação para retornar hashes completos que correspondem 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 criados com base na implementação do cliente.

FindFullHashesResponse

Campos
matches[]

ThreatMatch

Os hashes completos que corresponderam aos prefixos solicitados.
minimum_wait_duration

Duration

O tempo mínimo que o cliente precisa aguardar antes de emitir qualquer solicitação de localização de hashes. Se esse campo não for definido, os clientes poderão emitir uma solicitação quando quiserem.
negative_cache_duration

Duration

Por quanto tempo a resposta será armazenada em cache para entidades solicitadas que não correspondem à lista de ameaças.

FindThreatMatchesRequest

Solicitação para verificar entradas em relação a listas.

Campos
client

ClientInfo

Os metadados do cliente.
threat_info

ThreatInfo

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

FindThreatMatchesResponse

Campos
matches[]

ThreatMatch

A lista de ameaças coincide.

ListThreatListsResponse

Campos
threat_lists[]

ThreatListDescriptor

As listas disponíveis para download pelo cliente.

PlatformType

Tipos de plataformas.

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

RawHashes

Entradas de ameaças não compactadas em formato hash com um tamanho de prefixo específico. Os hashes podem ter de 4 a 32 bytes. A maioria deles tem 4 bytes, mas alguns hashes são ampliados se colidem com o hash de um URL conhecido.

Usado para enviar ThreatEntrySet a clientes que não oferecem suporte à compactação ou ao enviar hashes que não são de 4 bytes a clientes compatíveis.

Campos
prefix_size

int32

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

bytes

Os hashes, em formato binário, concatenados em uma única 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 lexicograficamente.

RiceDeltaEncoding

Os dados codificados em Rice-Golomb. Usado para enviar hashes de 4 bytes compactados 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 único inteiro. Se o campo estiver vazio ou ausente, considere zero.
rice_parameter

int32

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

int32

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

bytes

Os deltas codificados que são codificados usando o codificador Golomb-Rice.

ThreatEntry

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

Campos
hash

bytes

Um prefixo de hash, que consiste nos 4 a 32 bytes mais significativos de um hash SHA256. Este 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. Espera-se que o cliente conheça 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 deve ser adicionada ou removida do banco de dados local do cliente.

Campos
compression_type

CompressionType

O tipo de compactação para as entradas nesse conjunto.
raw_hashes

RawHashes

Entradas brutas formatadas em SHA256.
raw_indices

RawIndices

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

RiceDeltaEncoding

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

RiceDeltaEncoding

Os índices de lista locais codificados lexicograficamente classificados, 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, depois codificados em delta e armazenados comoencoded_data.

ThreatEntryType

Tipos de entradas que representam ameaç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 relativas a uma ou mais ameaças que um cliente envia ao verificar correspondências nas 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 individual de ameaças. Uma lista é definida por três parâmetros: o tipo de ameaça apresentado, o tipo de plataforma visada pela ameaça e o tipo de entradas na lista.

Campos
threat_type

ThreatType

O tipo de ameaça representado 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 esta ameaça.
platform_type

PlatformType

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

ThreatEntryType

O tipo de entrada que corresponde a essa ameaça.
threat

ThreatEntry

A ameaça que corresponde a esta ameaça.
threat_entry_metadata

ThreatEntryMetadata

Metadados opcionais associados a essa ameaça.
cache_duration

Duration

A vida útil do cache para a correspondência retornada. Os clientes não podem armazenar essa resposta em cache por mais tempo 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.