Package google.security.safebrowsing.v5alpha1

Índice

• SafeBrowsing (interface)
• BatchGetHashListsRequest (mensagem)
• BatchGetHashListsResponse (mensagem)
• FullHash (mensagem)
• FullHash.FullHashDetail (mensagem)
• GetHashListRequest (mensagem)
• HashList (mensagem)
• HashListMetadata (mensagem)
• HashListMetadata.HashLength (enum)
• LikelySafeType (enum)
• ListHashListsRequest (mensagem)
• ListHashListsResponse (mensagem)
• RiceDeltaEncoded128Bit (mensagem)
• RiceDeltaEncoded256Bit (mensagem)
• RiceDeltaEncoded32Bit (mensagem)
• RiceDeltaEncoded64Bit (mensagem)
• SearchHashesRequest (mensagem)
• SearchHashesResponse (mensagem)
• SizeConstraints (mensagem)
• ThreatAttribute (enum)
• ThreatType (tipo enumerado)

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.

BatchGetHashLists
rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse) Receba várias listas de hash de uma só vez. É muito comum que um cliente precise de várias listas de hash. É preferível usar esse método em vez de usar o método GET normal várias vezes. Este é um método GET padrão em lote, conforme definido por https://google.aip.dev/231, e o método HTTP também é GET.

GetHashList
rpc GetHashList(GetHashListRequest) returns (HashList) Receber o conteúdo mais recente de uma lista de hash. Uma lista de hash pode ser gerada por uma lista de ameaças ou não relacionada a ameaças, como o cache global. Esse é um método GET padrão, conforme definido por https://google.aip.dev/131 (link em inglês), e o método HTTP também é GET.

ListHashLists
rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse) Listar listas de hash. Na API V5, o Google nunca remove uma lista de hash que já foi retornada por esse método. Isso permite que os clientes pulem o uso desse método e codifiquem todas as listas de hash necessárias. Este é um método List padrão, conforme definido por https://google.aip.dev/132, e o método HTTP é GET.

SearchHashes
rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse) Pesquise hashes completos que correspondam aos prefixos especificados. Esse é um método personalizado, conforme definido por https://google.aip.dev/136 (link em inglês). Esse método tem um nome personalizado na nomenclatura geral de desenvolvimento de API do Google, não se refere ao uso de um método HTTP personalizado.

BatchGetHashListsRequest

Solicitação para receber várias listas de hash ao mesmo tempo.

Campos
names[]	string Obrigatório. Os nomes das listas de hash específicas. A lista PODE ser uma lista de ameaças ou pode ser o cache global. Os nomes NÃO PODEM conter cópias; se tiverem, o cliente receberá um erro.
version[]	bytes As versões da lista de hash que o cliente já tem. Se esta for a primeira vez que o cliente estiver buscando as listas de hash, o campo precisará ser deixado em branco. Caso contrário, o cliente precisará fornecer as versões recebidas anteriormente do servidor. O cliente NÃO PODE manipular esses bytes. O cliente não precisa enviar as versões na mesma ordem que os nomes das listas correspondentes. O cliente pode enviar menos ou mais versões em uma solicitação do que nomes. No entanto, o cliente NÃO PODE enviar várias versões que correspondam ao mesmo nome. Se tiver enviado, o cliente receberá um erro. Observação histórica: na V4 da API, era chamado de states. Agora, ele foi renomeado como version para maior clareza.
desired_hash_length	HashLength O tamanho desejado do prefixo de hash dos hashes retornados em bytes. O servidor retornará todos os prefixos de hash nesse tamanho especificado. Listas de hash diferentes têm requisitos distintos sobre os valores aceitáveis do campo desired_hash_length. Isso pode ser encontrado no campo supported_hash_lengths em HashListMetadata. Se desired_hash_length não especificar um valor dentro de supported_hash_lengths, um erro será retornado aos clientes. Para o BatchGetHashListsRequest específico, não é possível que os clientes especifiquem um desired_hash_length diferente para listas diferentes. Se for necessário fazer isso, o cliente precisará ser dividido em várias BatchGetHashListsRequests.
size_constraints	SizeConstraints as restrições de tamanho em cada lista; Se omitido, não há restrições. Observe que os tamanhos são por lista, e não agregados em todas as listas.

BatchGetHashListsResponse

A resposta que contém várias listas de hash.

Campos
hash_lists[]	HashList O hash é listado na mesma ordem dada na solicitação.

FullHash

O hash completo identificado com uma ou mais correspondências.

Campos
full_hash	bytes O hash completo correspondente. Esse é o hash SHA256. O comprimento será de exatamente 32 bytes.
full_hash_details[]	FullHashDetail Lista não ordenada. Um campo repetido que identifica os detalhes relevantes para esse hash completo.

FullHashDetail

Detalhes sobre um hash completo correspondente.

Uma observação importante sobre compatibilidade futura: novos tipos de ameaça e atributos de ameaça podem ser adicionados pelo servidor a qualquer momento; essas adições são consideradas pequenas alterações de versão. É política do Google não expor números de versão secundários nas APIs (consulte https://cloud.google.com/apis/design/versioning para a política de controle de versões). Por isso, os clientes PRECISAM estar preparados para receber mensagens FullHashDetail contendo valores de tipo enumerado ThreatType ou valores de tipo enumerado ThreatAttribute que são considerados inválidos pelo cliente. Portanto, é responsabilidade do cliente verificar a validade de todos os valores de tipo enumerado ThreatType e ThreatAttribute. Se algum valor for considerado inválido, o cliente PRECISA desconsiderar toda a mensagem FullHashDetail.

Campos
threat_type	ThreatType O tipo de ameaça. Este campo nunca ficará vazio.
attributes[]	ThreatAttribute Lista não ordenada. Atributos adicionais sobre esses hashes completos. Esse campo pode estar vazio.

GetHashListRequest

Uma solicitação para receber uma lista de hash, que pode ser uma lista de ameaças ou uma lista não relacionada, como o cache global.

Novidades na V5: o que anteriormente era chamado de states na V4 foi renomeado como version para maior clareza. As listas agora são nomeadas, os tipos de plataforma e os tipos de entrada de ameaças foram removidos. Agora é possível que várias listas tenham o mesmo tipo de ameaça ou uma única lista relacionada a vários tipos de ameaça. Os clientes podem especificar um tamanho de hash desejado. Isso faz parte da resposta aos prefixos de hash de tamanho variável da V4, que causaram problemas em muitas implementações de clientes: todos os hashes em uma lista agora têm um único tamanho, permitindo implementações de cliente muito mais eficientes. As restrições foram simplificadas, e o tipo de compactação foi removido (a compactação sempre é aplicada).

Campos
name	string Obrigatório. É o nome dessa lista de hash específica. Pode ser uma lista de ameaças ou o cache global.
version	bytes A versão da lista de hash que o cliente já tem. Se esta for a primeira vez que o cliente está buscando a lista de hash, esse campo PRECISA ser deixado em branco. Caso contrário, o cliente DEVE fornecer a versão recebida anteriormente do servidor. O cliente NÃO PODE manipular esses bytes. Novidades na V5: na V4 da API, esse recurso era chamado de states. Agora, ele foi renomeado como version para maior clareza.
desired_hash_length	HashLength O tamanho desejado do prefixo de hash dos hashes retornados em bytes. O servidor retornará todos os prefixos de hash nesse tamanho especificado. Listas de hash diferentes têm requisitos distintos sobre os valores aceitáveis do campo desired_hash_length. Isso pode ser encontrado no campo supported_hash_lengths em HashListMetadata. Se desired_hash_length não especificar um valor dentro de supported_hash_lengths, será retornado um erro.
size_constraints	SizeConstraints As restrições de tamanho na lista. Se omitido, não há restrições. As restrições são recomendadas em todos os dispositivos com capacidade de processamento, largura de banda ou armazenamento limitados.

HashList

Uma lista de hashes identificados por seu nome.

Campos
name	string O nome da lista de hash. O cache global também é apenas uma lista de hash e pode ser referenciado aqui.
version	bytes A versão da lista de hash. O cliente NÃO PODE manipular esses bytes.
partial_update	bool Quando verdadeiro, essa diferença é parcial, mas contém adições e remoções com base no que o cliente já tem. Quando definido como falso, esta é a lista completa de hash. Quando definido como "false", o cliente PRECISA excluir qualquer versão armazenada localmente para essa lista de hash. Isso significa que a versão que o cliente possui está seriamente desatualizada ou os dados dele estão corrompidos. O campo compressed_removals vai estar vazio. Quando verdadeiro, o cliente PRECISA aplicar uma atualização incremental aplicando remoções e, em seguida, adições.
compressed_removals	RiceDeltaEncoded32Bit A versão codificada de Rice-delta dos índices de remoção. Como cada lista de hashes definitivamente tem menos de 2^32 entradas, os índices são tratados como números inteiros de 32 bits e codificados.
minimum_wait_duration	Duration Os clientes precisam esperar pelo menos esse tempo para acessar a lista de hashes novamente. Se omitido ou zero, os clientes DEVEM buscar imediatamente porque isso indica que o servidor tem uma atualização adicional a ser enviada ao cliente, mas não conseguiu devido às restrições especificadas pelo cliente.
metadata	HashListMetadata Metadados sobre a lista de hash. Isso não é preenchido pelo método GetHashList, mas pelo método ListHashLists.
Campo de união compressed_additions. A versão de adições codificada em delta de arroz. O tamanho das adições do prefixo de hash é uniforme em todas as adições na lista. Ele é o desired_hash_length enviado pelo cliente ou um valor escolhido pelo servidor se o cliente tiver omitido esse campo. compressed_additions pode ser apenas de um dos tipos a seguir:
additions_four_bytes	RiceDeltaEncoded32Bit As adições de 4 bytes.
additions_eight_bytes	RiceDeltaEncoded64Bit As adições de 8 bytes.
additions_sixteen_bytes	RiceDeltaEncoded128Bit As adições de 16 bytes.
additions_thirty_two_bytes	RiceDeltaEncoded256Bit As adições de 32 bytes.
Campo de união checksum. Essa é a soma de verificação da lista classificada de todos os hashes presentes no banco de dados após a atualização fornecida. Este é um campo "oneof" para permitir vários algoritmos de hash. Também é possível que o servidor omita esse campo (caso nenhuma atualização tenha sido fornecida) para indicar que o cliente precisa usar a soma de verificação atual. checksum só pode ser de um dos seguintes tipos:
sha256_checksum	bytes A lista classificada de todos os hashes, novamente com hash com SHA256.

HashListMetadata

Metadados sobre uma lista de hash específica.

Campos
threat_types[]	ThreatType Lista não ordenada. Se não estiver vazio, especifica que a lista de hash é um tipo de lista de ameaças e enumera o tipo de ameaças associadas a hashes ou prefixos de hash nessa lista. Pode estar em branco se a entrada não representar uma ameaça, ou seja, no caso de representar um tipo provável seguro.
likely_safe_types[]	LikelySafeType Lista não ordenada. Se não estiver vazio, esse atributo especifica que a lista de hash representa uma lista de prováveis hashes seguros e enumera as maneiras como eles são considerados prováveis seguros. Esse campo é mutuamente exclusivo com o campo threat_types.
mobile_optimized	bool Indica se a lista está otimizada para dispositivos móveis (Android e iOS).
description	string Uma descrição legível sobre esta lista. Escrita em inglês.
supported_hash_lengths[]	HashLength Os comprimentos de hash compatíveis com esta lista de hash. Cada lista de hash pode ter pelo menos um comprimento. Este campo, portanto, não estará vazio.

HashLength

O tamanho dos hashes em uma lista de hashes.

Tipos enumerados
HASH_LENGTH_UNSPECIFIED	Tamanho não especificado. O servidor não vai retornar esse valor nas respostas ao cliente (no campo supported_hash_lengths), mas o cliente tem permissão para enviar esse valor para o servidor (no campo desired_hash_length). Nesse caso, o servidor escolherá um valor automaticamente. Os clientes DEVEM deixar o servidor selecionar um valor.
FOUR_BYTES	Cada hash é um prefixo de quatro bytes.
EIGHT_BYTES	Cada hash é um prefixo de oito bytes.
SIXTEEN_BYTES	Cada hash é um prefixo de 16 bytes.
THIRTY_TWO_BYTES	Cada hash é um hash completo de 32 bytes.

LikelySafeType

Tipos de sites que podem ser seguros.

Observe que o SearchHashesResponse intencionalmente não contém LikelySafeType.

Tipos enumerados
LIKELY_SAFE_TYPE_UNSPECIFIED	Desconhecido.
GENERAL_BROWSING	É provável que este site seja seguro o suficiente para a navegação geral. Isso também é conhecido como cache global.
CSD	É provável que este site seja seguro o suficiente para que não seja necessário executar modelos de detecção do lado do cliente ou verificações de proteção de senha.
DOWNLOAD	Este site provavelmente é seguro o suficiente para que os downloads do site não precisem ser verificados.

ListHashListsRequest

A solicitação para listar as listas de hash disponíveis.

Campos
page_size	int32 O número máximo de listas de hash a serem retornadas. O serviço pode retornar menos que esse valor. Se não for especificado, o servidor escolherá um tamanho de página, que pode ser maior do que o número de listas de hash para que a paginação não seja necessária.
page_token	string Um token de página recebido de uma chamada ListHashLists anterior. Forneça isso para recuperar a página subsequente.

ListHashListsResponse

A resposta contendo metadados sobre listas de hash.

Campos
hash_lists[]	HashList O hash é listado em uma ordem arbitrária. Somente os metadados sobre as listas de hash serão incluídos, não o conteúdo.
next_page_token	string Um token, que pode ser enviado como page_token para recuperar a próxima página. Se esse campo for omitido, não haverá páginas subsequentes.

RiceDeltaEnencoded128Bit

Funciona da mesma forma que RiceDeltaEncoded32Bit, mas codifica números de 128 bits.

Campos
first_value_hi	uint64 Os 64 bits mais altos da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 64 bits superiores serão todos zero.
first_value_lo	fixed64 Os 64 bits mais baixos da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 64 bits mais baixos serão todos zero.
rice_parameter	int32 O parâmetro Golomb-Rice. Esse parâmetro está entre 99 e 126, inclusive.
entries_count	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.

RiceDeltaEnencoded256bit

O mesmo que RiceDeltaEncoded32Bit, mas codifica números de 256 bits.

Campos
first_value_first_part	uint64 Os primeiros 64 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os primeiros 64 bits serão todos zero.
first_value_second_part	fixed64 Os 65 a 128 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 65 a 128 bits serão todos zero.
first_value_third_part	fixed64 Os 129 a 192 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 129 a 192 bits serão todos zero.
first_value_fourth_part	fixed64 Os últimos 64 bits da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os últimos 64 bits serão todos zero.
rice_parameter	int32 O parâmetro Golomb-Rice. Esse parâmetro está garantido entre 227 e 254.
entries_count	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.

RiceDeltaEnencoded32bit

Os dados codificados em Rice-Golomb. Usado para hashes ou índices de remoção. É garantido que cada hash ou índice aqui tenha o mesmo comprimento, e esse comprimento é de exatamente 32 bits.

De modo geral, se classificarmos todas as entradas lexicograficamente, descobriremos que os bits de ordem superior tendem a não mudar com a mesma frequência que os bits de ordem inferior. Isso significa que, se também tomarmos a diferença adjacente entre as entradas, os bits de ordem superior terão uma alta probabilidade de serem zero. Isso explora essa alta probabilidade de zero essencialmente escolhendo um certo número de bits. Todos os bits mais significativos que isso provavelmente são zero, por isso usamos codificação unária. Veja o campo rice_parameter.

Observação histórica: a codificação delta de arroz foi usada pela primeira vez na V4 dessa API. Na V5, duas melhorias significativas foram feitas: primeiro, a codificação delta do arroz agora está disponível com prefixos de hash com mais de 4 bytes; em segundo lugar, os dados codificados agora são tratados como big-endian para evitar uma etapa de classificação dispendiosa.

Campos
first_value	uint32 a primeira entrada nos dados codificados (hashes ou índices) ou, se apenas um prefixo de hash ou índice tiver sido codificado, o valor dessa entrada. Se o campo estiver vazio, a entrada será zero.
rice_parameter	int32 O parâmetro Golomb-Rice. Esse parâmetro está entre 3 e 30, inclusive.
entries_count	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.

RiceDeltaEnencoded64bit

O mesmo que RiceDeltaEncoded32Bit, mas codifica números de 64 bits.

Campos
first_value	uint64 A primeira entrada nos dados codificados (hashes) ou, se apenas um prefixo de hash tiver sido codificado, o valor dessa entrada. Se o campo estiver vazio, a entrada será zero.
rice_parameter	int32 O parâmetro Golomb-Rice. Esse parâmetro certamente está entre 35 e 62.
entries_count	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.

SearchHashesRequest

Uma solicitação que o cliente emite para pesquisar prefixos de hash específicos.

Ele foi desenvolvido para pesquisar apenas listas de ameaças, e não listas que não são ameaças, como o Cache global.

Novidades na V5: os clientes não precisam especificar um ClientInfo nem os estados das listas de hash no banco de dados local. Isso é para melhorar a privacidade. Além disso, os clientes não precisam informar quais tipos de ameaça estão interessados.

Campos
hash_prefixes[]	bytes Obrigatório. Os prefixos de hash a serem pesquisados. Os clientes NÃO PODEM enviar mais de 1.000 prefixos de hash. No entanto, seguindo o procedimento de processamento de URL, os clientes NÃO DEVEM enviar mais de 30 prefixos de hash. Atualmente, cada prefixo de hash precisa ter exatamente 4 bytes. Isso PODE ser amenizado no futuro.
filter	string Opcional. Se o cliente estiver interessado em filtrar, por exemplo, apenas para recuperar tipos específicos de ameaças, isso pode ser especificado. Se omitido, todas as ameaças correspondentes são retornadas. É altamente recomendável omitir isso para ter a proteção mais completa que o recurso Navegação segura pode oferecer. O filtro é especificado usando a Common Expression Language do Google, que pode ser encontrada em https://github.com/google/cel-spec (link em inglês), além de exemplos gerais. Aqui estão alguns exemplos específicos que podem ser usados aqui: O filtro "threat_type == ThreatType.SOCIAL_ENGINEERING" exige que o tipo de ameaça em FullHashDetail seja SOCIAL_ENGINEERING. O identificador "threat_type" se refere ao tipo de ameaça atual. O identificador "ThreatType" se refere à coleção de todos os tipos de ameaça possíveis. O filtro "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" exige que o tipo de ameaça seja UNWANTED_SOFTWARE ou MALWARE.

SearchHashesResponse

A resposta retornada após a pesquisa de hashes de ameaça.

Se nada for encontrado, o servidor retornará um status OK (código de status HTTP 200) com o campo full_hashes vazio, em vez de retornar um status NOT_FOUND (código de status HTTP 404).

Novidades na V5: há uma separação entre FullHash e FullHashDetail. No caso em que um hash representa um site que apresenta várias ameaças (por exemplo, MALWARE e SOCIAL_engineERING), o hash completo não precisa ser enviado duas vezes como na V4. Além disso, a duração do cache foi simplificada em um único campo cache_duration.

Campos
full_hashes[]	FullHash Lista não ordenada. A lista não ordenada de hashes completos foi encontrada.
cache_duration	Duration A duração do cache do lado do cliente. O cliente PRECISA adicionar essa duração ao horário atual para determinar o prazo de validade. O prazo de validade é aplicado a cada prefixo de hash consultado pelo cliente na solicitação, independentemente de quantos hashes completos forem retornados na resposta. Mesmo que o servidor não retorne hashes completos para um prefixo de hash específico, esse fato também PRECISA ser armazenado em cache pelo cliente. Somente se o campo full_hashes estiver vazio, o cliente poderá aumentar o cache_duration para determinar uma nova expiração posterior à especificada pelo servidor. Em qualquer caso, o aumento da duração do cache não pode ser maior do que 24 horas. Importante: o cliente NÃO PODE presumir que o servidor retornará a mesma duração de cache para todas as respostas. O servidor PODE escolher durações de cache diferentes para respostas distintas, dependendo da situação.

SizeConstraints

As restrições dos tamanhos das listas de hash.

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, mas é possível que a atualização contenha menos entradas do que este valor. PRECISA ser pelo menos 1.024. Se omitido ou 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. O servidor PODE fazer com que o cliente armazene menos que esse número de entradas. Se omitido ou zero, nenhum limite de tamanho do banco de dados será definido.

ThreatAttribute

Atributos das ameaças. Esses atributos podem conferir um significado adicional a uma ameaça específica, mas não afetam o tipo dela. Por exemplo, um atributo pode especificar uma confiança mais baixa, enquanto um atributo diferente pode especificar uma confiança mais alta. Mais atributos podem ser adicionados no futuro.

Tipos enumerados
THREAT_ATTRIBUTE_UNSPECIFIED	Atributo desconhecido. Se esse valor for retornado pelo servidor, o cliente precisará desconsiderar completamente o FullHashDetail.
CANARY	Indica que o threat_type não deve ser usado para aplicação.
FRAME_ONLY	Indica que o threat_type deve ser usado apenas para a aplicação em frames.

ThreatType

Tipos de ameaças.

Tipos enumerados
THREAT_TYPE_UNSPECIFIED	Tipo de ameaça desconhecido. Se esse valor for retornado pelo servidor, o cliente precisará desconsiderar completamente o FullHashDetail.
MALWARE	Tipo de ameaça de malware. Malware é qualquer software ou aplicativo para dispositivos móveis projetado especificamente para causar danos a um computador, dispositivo móvel, bem como a usuários ou outro software. Além disso, o malware apresenta um comportamento malicioso que pode incluir a instalação de software sem o consentimento do usuário e a instalação de software nocivo, como vírus. Saiba mais aqui.
SOCIAL_ENGINEERING	Tipo de ameaça de engenharia social. Páginas de engenharia social têm a intenção falsa de agir em nome de terceiros com a intenção de confundir os espectadores, fazendo-os realizar uma ação com a qual eles confiam somente em um agente desse terceiro. Phishing é um tipo de engenharia social que engana o espectador para que realize a ação específica de fornecer informações, como credenciais de login. Saiba mais aqui.
UNWANTED_SOFTWARE	Tipo de ameaça de software indesejado. Software indesejado é qualquer software que não esteja em conformidade com os Princípios de software do Google, mas não seja malware.
POTENTIALLY_HARMFUL_APPLICATION	Tipo de ameaça de apps potencialmente nocivos usado pelo Google Play Protect na Play Store.