Package google.security.safebrowsing.v5alpha1

Índice

SafeBrowsing

As APIs Safe Browsing permitem que os clientes verifiquem recursos da Web (mais comumente URLs) nas listas de recursos inseguros da Web do Google, que são atualizadas constantemente.

BatchGetHashLists

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

Recebe várias listas de hash de uma só vez.

É muito comum que um cliente precise receber várias listas de hash. É preferível usar esse método em vez do método Get normal várias vezes.

Esse é um método Get em lote padrão, conforme definido em https://google.aip.dev/231, e o método HTTP também é GET.
GetHashList

rpc GetHashList(GetHashListRequest) returns (HashList)

Recebe o conteúdo mais recente de uma lista de hash. Uma lista de hash pode ser uma lista de ameaças ou não ameaças, como o cache global.

Esse é um método Get padrão, conforme definido em https://google.aip.dev/131, 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 evitem usar esse método e simplesmente codifiquem todas as listas de hash necessárias.

Esse é um método List padrão, conforme definido em 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 em https://google.aip.dev/136. O método personalizado se refere a um método com um nome personalizado na nomenclatura geral de desenvolvimento de APIs do Google. Ele não se refere ao uso de um método HTTP personalizado.
SearchUrls

rpc SearchUrls(SearchUrlsRequest) returns (SearchUrlsResponse)

Pesquisar URLs que correspondam a ameaças conhecidas. Cada URL e suas expressões de sufixo de host e prefixo de caminho (até uma profundidade limitada) são verificados. Isso significa que a resposta pode conter URLs que não foram incluídos na solicitação, mas são expressões dos URLs solicitados.

BatchGetHashListsRequest

A 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 o cache global. Os nomes NÃO PODEM conter duplicados. Se isso acontecer, o cliente vai receber um erro.
version[]

bytes

As versões da lista de hash que o cliente já tem. Se for a primeira vez que o cliente está buscando as listas de hash, deixe o campo vazio. Caso contrário, o cliente precisa 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 dos nomes de lista correspondentes. O cliente pode enviar menos ou mais versões em uma solicitação do que há nomes. No entanto, o cliente NÃO DEVE enviar várias versões que correspondam ao mesmo nome. Se isso acontecer, o cliente vai receber um erro.

Observação histórica: na API v4, isso era chamado de states. Agora, foi renomeado como version para maior clareza.
size_constraints

SizeConstraints

As restrições de tamanho em cada lista. Se omitido, não haverá restrições. Os tamanhos aqui são por lista, não agregados em todas as listas.

BatchGetHashListsResponse

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

Campos
hash_lists[]

HashList

As listas de hash na mesma ordem da solicitação.

FullHash

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

Campos
full_hash

bytes

O hash completo correspondente. Este é o hash SHA256. O comprimento será exatamente de 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.

Observação importante sobre compatibilidade futura: novos tipos e atributos de ameaças podem ser adicionados pelo servidor a qualquer momento. Essas adições são consideradas mudanças de versão secundárias. A política do Google não permite expor números de versões secundárias em APIs (consulte https://cloud.google.com/apis/design/versioning para conferir a política de controle de versões). Portanto, os clientes PRECISAM estar preparados para receber mensagens FullHashDetail que contenham valores de enumeração ThreatType ou ThreatAttribute considerados inválidos pelo cliente. Portanto, é responsabilidade do cliente verificar a validade de todos os valores de enumeração ThreatType e ThreatAttribute. Se algum valor for considerado inválido, o cliente PRECISA ignorar toda a mensagem FullHashDetail.

Campos
threat_type

ThreatType

O tipo de ameaça. Esse campo nunca vai ficar vazio.
attributes[]

ThreatAttribute

Lista não ordenada. Outros atributos sobre esses hashes completos. Pode estar vazio.

GetHashListRequest

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

Novidades da V5: o que antes era chamado de states na V4 foi renomeado como version para maior clareza. As listas agora têm nomes, e os tipos de plataforma e de entrada de ameaça foram removidos. Agora é possível que várias listas tenham o mesmo tipo de ameaça ou que uma única lista se preocupe com vários tipos de ameaças. Ao contrário dos prefixos de hash de comprimento variável da V4, que causaram problemas em muitas implementações de clientes, todos os hashes em uma lista agora têm um único comprimento, permitindo implementações de clientes 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 for a primeira vez que o cliente está buscando a lista de hash, esse campo PRECISA ficar vazio. 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, isso era chamado de states. Agora, foi renomeado como version para maior clareza.
size_constraints

SizeConstraints

As restrições de tamanho na lista. Se omitido, não haverá 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 pelo nome.

Campos
name

string

O nome da lista de hash. O cache global também é apenas uma lista de hash e pode ser consultado aqui.
version

bytes

A versão da lista de hash. O cliente NÃO PODE manipular esses bytes.
partial_update

bool

Quando verdadeiro, esse é um diff parcial que contém adições e remoções com base no que o cliente já tem. Quando for "false", essa será a lista de hash completa.

Quando for "false", o cliente PRECISA excluir qualquer versão armazenada localmente dessa lista de hash. Isso significa que a versão do cliente está muito desatualizada ou que os dados do cliente estão corrompidos. O campo compressed_removals vai estar vazio.

Quando for "true", o cliente PRECISA aplicar uma atualização incremental removendo e adicionando.
compressed_removals

RiceDeltaEncoded32Bit

A versão codificada em delta de Rice dos índices de remoção. Como cada lista de hash 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 receber a lista de hash novamente. Se for omitido ou zero, os clientes DEVERÃO buscar imediatamente porque isso indica que o servidor tem uma atualização adicional para enviar ao cliente, mas não pôde devido às restrições especificadas pelo cliente.
sha256_checksum

bytes

A lista classificada de todos os hashes, com hash novamente usando SHA256. Este é o checksum da lista classificada de todos os hashes presentes no banco de dados após a aplicação da atualização fornecida. Se nenhuma atualização for fornecida, o servidor vai omitir esse campo para indicar que o cliente deve usar a soma de verificação atual.
metadata

HashListMetadata

Metadados sobre a lista de hash. Não é preenchido pelo método GetHashList, mas pelo método ListHashLists.
Campo de união compressed_additions. A versão codificada por Rice-delta das adições. Os comprimentos dos prefixos de hash das adições são uniformes em todas as adições da lista. 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.

HashListMetadata

Metadados sobre uma lista de hash específica.

Campos
threat_types[]

ThreatType

Lista não ordenada. Se não estiver vazia, especifica que a lista de hash é um tipo de lista de ameaças e enumera os tipos de ameaças associadas a hashes ou prefixos de hash nessa lista. Pode estar vazio se a entrada não representar uma ameaça, ou seja, se representar um tipo provavelmente seguro.
likely_safe_types[]

LikelySafeType

Lista não ordenada. Se não estiver vazia, isso especifica que a lista de hash representa uma lista de hashes provavelmente seguros e enumera as maneiras como eles são considerados provavelmente seguros. Esse campo é mutuamente exclusivo com o campo "threat_types".
description

string

Uma descrição legível sobre esta lista. Escrito em inglês.
hash_length

HashLength

O comprimento de hash compatível com essa lista de hash. Cada lista de hash vai aceitar exatamente um comprimento. Se um comprimento de hash diferente for introduzido para o mesmo conjunto de tipos de ameaça ou seguros, ele será introduzido como uma lista separada com um nome distinto e o respectivo conjunto de comprimento de hash.

HashLength

O tamanho dos hashes em uma lista de hashes.

Tipos enumerados
HASH_LENGTH_UNSPECIFIED Comprimento não especificado.
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 provavelmente seguros.

O SearchHashesResponse não contém LikelySafeType intencionalmente.

Tipos enumerados
LIKELY_SAFE_TYPE_UNSPECIFIED Desconhecido.
GENERAL_BROWSING Esse site provavelmente é seguro o suficiente para navegação geral. Isso também é conhecido como cache global.
CSD É provável que esse site seja seguro o suficiente para não precisar executar modelos de detecção do lado do cliente ou verificações de proteção de senha.
DOWNLOAD Esse site provavelmente é seguro o suficiente para que os downloads 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 um valor inferior a este. Se não for especificado, o servidor vai escolher um tamanho de página, que pode ser maior 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 que contém metadados sobre listas de hash.

Campos
hash_lists[]

HashList

As listas de hash aparecem em uma ordem arbitrária. Apenas 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.

RiceDeltaEncoded128Bit

Igual a RiceDeltaEncoded32Bit, exceto que codifica números de 128 bits.

Campos
first_value_hi

uint64

Os 64 bits superiores 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 inferiores da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os 64 bits inferiores serão todos zero.
rice_parameter

int32

O parâmetro de Golomb-Rice. Esse parâmetro fica entre 99 e 126, inclusive.
entries_count

int32

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

bytes

Os deltas codificados usando o codificador Golomb-Rice.

RiceDeltaEncoded256Bit

Igual a 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 bits de 65 a 128 da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os bits de 65 a 128 serão todos zero.
first_value_third_part

fixed64

Os bits de 129 a 192 da primeira entrada nos dados codificados (hashes). Se o campo estiver vazio, os bits de 129 a 192 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 de Golomb-Rice. Esse parâmetro está entre 227 e 254, inclusive.
entries_count

int32

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

bytes

Os deltas codificados usando o codificador Golomb-Rice.

RiceDeltaEncoded32Bit

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

Em geral, se classificarmos todas as entradas lexicograficamente, vamos descobrir que os bits de ordem superior não mudam com tanta frequência quanto os de ordem inferior. Isso significa que, se também considerarmos 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 escolhendo um determinado número de bits. Todos os bits mais significativos que esse provavelmente serão zero, então usamos a codificação unária. Consulte o campo rice_parameter.

Observação histórica: a codificação Rice-delta foi usada pela primeira vez na V4 desta API. Na V5, foram feitas duas melhorias significativas: primeiro, a codificação Rice-delta agora está disponível com prefixos de hash maiores que 4 bytes; segundo, 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 foi codificado, o valor dessa entrada. Se o campo estiver vazio, a entrada será zero.
rice_parameter

int32

O parâmetro de Golomb-Rice. Esse parâmetro precisa estar entre 3 e 30, inclusive.
entries_count

int32

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

bytes

Os deltas codificados usando o codificador Golomb-Rice.

RiceDeltaEncoded64Bit

Igual a RiceDeltaEncoded32Bit, exceto que codifica números de 64 bits.

Campos
first_value

uint64

A primeira entrada nos dados codificados (hashes) ou, se apenas um prefixo de hash foi codificado, o valor dessa entrada. Se o campo estiver vazio, a entrada será zero.
rice_parameter

int32

O parâmetro de Golomb-Rice. Esse parâmetro precisa estar entre 35 e 62, inclusive.
entries_count

int32

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

bytes

Os deltas codificados usando o codificador Golomb-Rice.

SearchHashesRequest

Uma solicitação emitida pelo cliente para pesquisar prefixos de hash específicos.

Ela foi projetada para pesquisar apenas listas de ameaças e não listas que não são de ameaças, como o cache global.

Novidades na V5: os clientes não precisam especificar um ClientInfo ou os estados das listas de hash no banco de dados local. Isso é feito para melhorar a privacidade. Além disso, os clientes não precisam enviar os tipos de ameaças em que têm interesse.

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 PRECISAM enviar mais de 30 prefixos de hash.

No momento, cada prefixo de hash precisa ter exatamente 4 bytes. Isso PODE ser flexibilizado no futuro.
filter

string

Opcional. Se o cliente tiver interesse em filtrar, como recuperar apenas tipos específicos de ameaças, isso pode ser especificado. Se omitido, todas as ameaças correspondentes serão retornadas. É altamente recomendável omitir isso para ter a proteção mais completa que a 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, junto com exemplos gerais. Confira alguns exemplos específicos que podem ser usados aqui:

O filtro "threat_type == ThreatType.SOCIAL_ENGINEERING" exige que, em FullHashDetail, o tipo de ameaça 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ças.

Se nada for encontrado, o servidor vai retornar um status OK (código de status HTTP 200) com o campo full_hashes vazio, em vez de 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 com várias ameaças (por exemplo, MALWARE e SOCIAL_ENGINEERING), não é necessário enviar o hash completo 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 encontrados.
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 horário de expiração. O tempo de expiração se aplica a todos os prefixos de hash consultados pelo cliente na solicitação, independentemente de quantos hashes completos são retornados na resposta. Mesmo que o servidor não retorne hashes completos para um determinado prefixo de hash, esse fato também PRECISA ser armazenado em cache pelo cliente.

Se e 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 superior a 24 horas.

Importante: o cliente NÃO PODE presumir que o servidor vai retornar a mesma duração de cache para todas as respostas. O servidor PODE escolher durações de cache diferentes para respostas diferentes, dependendo da situação.

SearchUrlsRequest

Um pedido que o cliente faz para pesquisar ameaças que correspondam aos URLs especificados.

Ela foi projetada para pesquisar apenas listas de ameaças e não listas que não são de ameaças, como o cache global.

Campos
urls[]

string

Obrigatório. Os URLs a serem pesquisados. Os clientes NÃO PODEM enviar mais de 50 URLs.

SearchUrlsResponse

A resposta retornada após a pesquisa de ameaças que correspondem aos URLs especificados.

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

Campos
threats[]

ThreatUrl

Lista não ordenada. A lista não ordenada de correspondências de ameaças encontradas. Cada entrada contém um URL e os tipos de ameaças encontradas que correspondem a esse URL. O tamanho da lista pode ser maior que o número de URLs na solicitação, já que todas as expressões do URL foram consideradas.
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 horário de expiração. O tempo de expiração é aplicado a todos os URLs consultados pelo cliente na solicitação, não importa quantos URLs sejam retornados na resposta. Mesmo que o servidor não retorne correspondências para um URL específico, esse fato também PRECISA ser armazenado em cache pelo cliente.

Se e somente se o campo threats 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 superior a 24 horas.

Importante: o cliente NÃO PODE presumir que o servidor vai retornar a mesma duração de cache para todas as respostas. O servidor PODE escolher durações de cache diferentes para respostas diferentes, dependendo da situação.

SizeConstraints

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

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, mas é possível que ela tenha menos entradas. Esse valor PRECISA ser pelo menos 1024. Se for 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 quer ter no banco de dados local para a lista. O servidor PODE fazer com que o cliente armazene menos entradas do que esse número. Se omitido ou zero, nenhum limite de tamanho do banco de dados será definido.

ThreatAttribute

Atributos de 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 menor, enquanto outro pode especificar uma confiança maior. Mais atributos podem ser adicionados no futuro.

Tipos enumerados
THREAT_ATTRIBUTE_UNSPECIFIED Atributo desconhecido. Se isso for retornado pelo servidor, o cliente vai ignorar o FullHashDetail.
CANARY Indica que o "threat_type" não deve ser usado para aplicação.
FRAME_ONLY Indica que o threat_type só deve ser usado para aplicação em frames.

ThreatType

Tipos de ameaças.

Tipos enumerados
THREAT_TYPE_UNSPECIFIED Tipo de ameaça desconhecido. Se isso for retornado pelo servidor, o cliente vai ignorar 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.

Encontre mais informações neste link.
SOCIAL_ENGINEERING

Tipo de ameaça de engenharia social. As páginas de engenharia social afirmam falsamente agir em nome de terceiros com a intenção de confundir os espectadores para que realizem uma ação em que só confiariam em um agente verdadeiro desse terceiro. O phishing é um tipo de engenharia social que engana o espectador para que ele realize a ação específica de fornecer informações, como credenciais de login.

Encontre mais informações neste link.
UNWANTED_SOFTWARE Tipo de ameaça de software indesejado. Software indesejado é qualquer software que não segue os Princípios de software do Google, mas não é malware.
POTENTIALLY_HARMFUL_APPLICATION Tipo de ameaça de app potencialmente nocivo usado pelo Google Play Protect na Play Store.

ThreatUrl

Um URL que corresponde a uma ou mais ameaças.

Campos
url

string

O URL solicitado que foi correspondido por uma ou mais ameaças.
threat_types[]

ThreatType

Lista não ordenada. A lista não ordenada de ameaças em que o URL é classificado.