Esta página foi traduzida pela API Cloud Translation.

Overview

Observação: esta documentação ainda está em desenvolvimento. Esperamos melhorias em breve.

A Navegação segura v5 é uma evolução da v4. As duas principais mudanças feitas na v5 são a atualização de dados e a privacidade de IP. Além disso, a superfície da API foi aprimorada para aumentar a flexibilidade, a eficiência e reduzir o inchaço. Além disso, a Navegação segura v5 do Google foi projetada para facilitar a migração da v4.

No momento, o Google oferece a v4 e a v5, e ambas estão prontas para produção. Você pode usar a v4 ou a v5. Não anunciamos uma data para o desativamento da v4. Se fizermos isso, daremos um aviso mínimo de um ano. Esta página descreve a v5 e um guia de migração da v4 para a v5. A documentação completa da v4 continua disponível.

Atualização de dados

Na v5, apresentamos um modo de operação conhecido como proteção em tempo real. Isso contorna o problema de desatuação de dados acima. Na v4, os clientes precisam fazer o download e manter um banco de dados local, realizar verificações nas listas de ameaças baixadas localmente e, quando houver uma correspondência parcial do prefixo, fazer uma solicitação para fazer o download do hash completo. Na v5, embora os clientes precisem continuar fazendo o download e mantendo um banco de dados local de listas de ameaças, eles também precisam fazer o download de uma lista de sites provavelmente benignos (chamado de cache global), realizar uma verificação local para esse cache global e uma verificação local de listas de ameaças e, por fim, quando houver uma correspondência parcial de prefixo para listas de ameaças ou uma não correspondência no cache global, faça uma solicitação para fazer o download dos hashes completos. Para saber mais sobre o processamento local exigido pelo cliente, consulte o procedimento abaixo. Isso representa uma mudança de "permitir por padrão" para "verificar por padrão", o que pode melhorar a proteção em relação à propagação mais rápida de ameaças na Web. Em outras palavras, esse é um protocolo projetado para oferecer proteção quase em tempo real: nosso objetivo é que os clientes se beneficiem de dados mais recentes da Navegação segura do Google.

Privacidade de IP

A Navegação segura do Google (v4 ou v5) não processa nada associado à identidade de um usuário durante a veiculação de solicitações. Os cookies, se enviados, são ignorados. O Google conhece os endereços IP de origem das solicitações, mas só os usa para necessidades essenciais de rede (por exemplo, para enviar respostas) e para fins de proteção contra ataques DDoS.

Com a v5, apresentamos uma API complementar, conhecida como API Gateway HTTP da Navegação segura. Isso usa o HTTP Oblivious para ocultar os endereços IP dos usuários finais do Google. Ele funciona com uma parte externa não envolvida em fraude para processar uma versão criptografada da solicitação do usuário e encaminhar ao Google. Assim, a parte externa só tem acesso aos endereços IP, e o Google só tem acesso ao conteúdo da solicitação. O terceiro opera um repetidor HTTP Oblivious (como este serviço da Fastly) e o Google opera o gateway HTTP Oblivious. Essa é uma API complementar opcional. Quando usado com a Navegação segura do Google, os endereços IP dos usuários finais não são mais enviados ao Google.

Os modos de operação

A Navegação segura do Google v5 permite que os clientes escolham entre três modos de operação.

Modo de tempo real

Quando os clientes optam por usar o Google Safe Browsing v5 no modo em tempo real, eles mantêm no banco de dados local: (i) um cache global de sites provavelmente benignos, formatado como hashes SHA256 de expressões de URL de sufixo do host/prefixo do caminho; (ii) um conjunto de listas de ameaças, formatado como prefixos de hash SHA256 de expressões de URL de sufixo do host/prefixo do caminho. A ideia geral é que sempre que o cliente quiser verificar um URL específico, uma verificação local será realizada usando o cache global. Se essa verificação for aprovada, uma verificação de listas de ameaças locais será realizada. Caso contrário, o cliente continua com a verificação de hash em tempo real, conforme detalhado abaixo.

Além do banco de dados local, o cliente vai manter um cache local. Esse cache local não precisa estar em armazenamento persistente e pode ser limpo em caso de pressão de memória.

Confira abaixo uma especificação detalhada do procedimento.

Modo de lista local

Quando os clientes escolhem usar o Google Safe Browsing v5 nesse modo, o comportamento do cliente é semelhante ao da API Update v4, exceto pelo uso da superfície de API aprimorada da v5. Os clientes vão manter no banco de dados local um conjunto de listas de ameaças formatadas como prefixos de hash SHA256 de expressões de URL de sufixo do host/prefixo do caminho. Sempre que o cliente quiser verificar um URL específico, uma verificação será realizada usando a lista de ameaças local. Se houver uma correspondência, o cliente vai se conectar ao servidor para continuar a verificação.

Como no exemplo acima, o cliente também mantém um cache local que não precisa estar em armazenamento permanente.

Modo em tempo real sem armazenamento

Quando os clientes optam por usar a Navegação segura do Google v5 no modo sem armazenamento em tempo real, eles não precisam manter nenhum banco de dados local persistente. No entanto, o cliente ainda precisa manter um cache local. Esse cache local não precisa estar em armazenamento persistente e pode ser limpo em caso de pressão de memória.

Sempre que o cliente quer verificar um URL específico, ele se conecta ao servidor para realizar a verificação. Esse modo é semelhante ao que os clientes da API Lookup v4 podem implementar.

Em comparação com o modo em tempo real, esse modo pode usar mais largura de banda de rede, mas pode ser mais adequado se for inconveniente para o cliente manter o estado local persistente.

Procedimento de verificação de URLs em tempo real

Esse procedimento é usado quando o cliente escolhe o modo de operação em tempo real.

Esse procedimento usa um único URL u e retorna SAFE, UNSAFE ou UNSURE. Se ele retornar SAFE, o URL será considerado seguro pelo recurso Navegação segura do Google. Se ele retornar UNSAFE, o URL será considerado potencialmente inseguro pelo Google Safe Browsing, e as ações apropriadas precisarão ser tomadas, como mostrar um aviso ao usuário final, mover uma mensagem recebida para a pasta de spam ou exigir uma confirmação extra do usuário antes de prosseguir. Se ele retornar UNSURE, o procedimento de verificação local a seguir deverá ser usado depois.

Considere expressions como uma lista de expressões de sufixo/prefixo geradas pelo URL u.
Considere expressionHashes como uma lista em que os elementos são hashes SHA256 de cada expressão em expressions.
Para cada hash de expressionHashes:
1. Se hash puder ser encontrado no cache global, retorne UNSURE.
Considere expressionHashPrefixes como uma lista em que os elementos são os quatro primeiros bytes de cada hash em expressionHashes.
Para cada expressionHashPrefix de expressionHashPrefixes:
1. Procure expressionHashPrefix no cache local.
2. Se a entrada em cache for encontrada:
  1. Determine se o horário atual é maior que o prazo de validade.
  2. Se for maior:
    1. Remova a entrada em cache encontrada do cache local.
    2. Continue com o loop.
  3. Se não for maior:
    1. Remova esse expressionHashPrefix específico de expressionHashPrefixes.
    2. Verifique se o hash completo correspondente em expressionHashes é encontrado na entrada em cache.
    3. Se encontrado, retorne UNSAFE.
    4. Se não for encontrado, continue com o loop.
3. Se a entrada em cache não for encontrada, continue com o loop.
Envie expressionHashPrefixes ao servidor da Navegação segura v5 do Google usando SearchHashes do RPC ou o método REST hashes.search. Se ocorrer um erro (incluindo erros de rede, HTTP etc.), retorne UNSURE. Caso contrário, a resposta será o response recebido do servidor do SB, que é uma lista de hashes completos com algumas informações auxiliares que identificam a natureza da ameaça (engenharia social, malware etc.), bem como o tempo de expiração do cache expiration.
Para cada fullHash de response:
1. Insira fullHash no cache local com expiration.
Para cada fullHash de response:
1. Vamos supor que isFound seja o resultado da descoberta de fullHash em expressionHashes.
2. Se isFound for falso, continue com o loop.
3. Se isFound for verdadeiro, retorne UNSAFE.
Retorne o SAFE.

Embora esse protocolo especifique quando o cliente envia expressionHashPrefixes para o servidor, ele não especifica exatamente como enviá-los. Por exemplo, é aceitável que o cliente envie todos os expressionHashPrefixes em uma única solicitação e também que envie cada prefixo individual em expressionHashPrefixes para o servidor em solicitações separadas (talvez em paralelo). Também é aceitável que o cliente envie prefixos de hash não relacionados ou gerados aleatoriamente com os prefixos de hash em expressionHashPrefixes, desde que o número de prefixos de hash enviados em uma única solicitação não exceda 30.

O procedimento de verificação de URL da lista de ameaças locais

Esse procedimento é usado quando o cliente opta pelo modo de operação da lista local. Ele também é usado quando o cliente o procedimento RealTimeCheck acima retorna o valor de UNSURE.

Esse procedimento usa um único URL u e retorna SAFE ou UNSAFE.

Considere expressions como uma lista de expressões de sufixo/prefixo geradas pelo URL u.
Considere expressionHashes como uma lista em que os elementos são hashes SHA256 de cada expressão em expressions.
Considere expressionHashPrefixes como uma lista em que os elementos são os quatro primeiros bytes de cada hash em expressionHashes.
Para cada expressionHashPrefix de expressionHashPrefixes:
1. Procure expressionHashPrefix no cache local.
2. Se a entrada em cache for encontrada:
  1. Determine se o horário atual é maior que o prazo de validade.
  2. Se for maior:
    1. Remova a entrada em cache encontrada do cache local.
    2. Continue com o loop.
  3. Se não for maior:
    1. Remova esse expressionHashPrefix específico de expressionHashPrefixes.
    2. Verifique se o hash completo correspondente em expressionHashes é encontrado na entrada em cache.
    3. Se encontrado, retorne UNSAFE.
    4. Se não for encontrado, continue com o loop.
3. Se a entrada em cache não for encontrada, continue com o loop.
Para cada expressionHashPrefix de expressionHashPrefixes:
1. Procure expressionHashPrefix no banco de dados da lista de ameaças locais.
2. Se o expressionHashPrefix não for encontrado no banco de dados da lista de ameaças locais, remova-o de expressionHashPrefixes.
Envie expressionHashPrefixes ao servidor da Navegação segura v5 do Google usando o RPC SearchHashes ou o método REST hashes.search. Se ocorrer um erro (incluindo erros de rede, HTTP etc.), retorne SAFE. Caso contrário, a resposta será o response recebido do servidor do SB, que é uma lista de hashes completos com algumas informações auxiliares que identificam a natureza da ameaça (engenharia social, malware etc.), bem como o tempo de expiração do cache expiration.
Para cada fullHash de response:
1. Insira fullHash no cache local com expiration.
Para cada fullHash de response:
1. Vamos supor que isFound seja o resultado da descoberta de fullHash em expressionHashes.
2. Se isFound for falso, continue com o loop.
3. Se isFound for verdadeiro, retorne UNSAFE.
Retorne o SAFE.

O procedimento de verificação de URL em tempo real sem um banco de dados local

Esse procedimento é usado quando o cliente escolhe o modo de operação em tempo real sem armazenamento.

Esse procedimento usa um único URL u e retorna SAFE ou UNSAFE.

Considere expressions como uma lista de expressões de sufixo/prefixo geradas pelo URL u.
Considere expressionHashes como uma lista em que os elementos são hashes SHA256 de cada expressão em expressions.
Considere expressionHashPrefixes como uma lista em que os elementos são os quatro primeiros bytes de cada hash em expressionHashes.
Para cada expressionHashPrefix de expressionHashPrefixes:
1. Procure expressionHashPrefix no cache local.
2. Se a entrada em cache for encontrada:
  1. Determine se o horário atual é maior que o prazo de validade.
  2. Se for maior:
    1. Remova a entrada em cache encontrada do cache local.
    2. Continue com o loop.
  3. Se não for maior:
    1. Remova esse expressionHashPrefix específico de expressionHashPrefixes.
    2. Verifique se o hash completo correspondente em expressionHashes é encontrado na entrada em cache.
    3. Se encontrado, retorne UNSAFE.
    4. Se não for encontrado, continue com o loop.
3. Se a entrada em cache não for encontrada, continue com o loop.
Envie expressionHashPrefixes ao servidor da Navegação segura v5 do Google usando o RPC SearchHashes ou o método REST hashes.search. Se ocorrer um erro (incluindo erros de rede, HTTP etc.), retorne SAFE. Caso contrário, a resposta será o response recebido do servidor do SB, que é uma lista de hashes completos com algumas informações auxiliares que identificam a natureza da ameaça (engenharia social, malware etc.), bem como o tempo de expiração do cache expiration.
Para cada fullHash de response:
1. Insira fullHash no cache local com expiration.
Para cada fullHash de response:
1. Vamos supor que isFound seja o resultado da descoberta de fullHash em expressionHashes.
2. Se isFound for falso, continue com o loop.
3. Se isFound for verdadeiro, retorne UNSAFE.
Retorne o SAFE.

Assim como o procedimento de verificação de URL em tempo real, este procedimento não especifica exatamente como enviar os prefixos de hash para o servidor. Por exemplo, é aceitável que o cliente envie todos os expressionHashPrefixes em uma única solicitação e também que envie cada prefixo individual em expressionHashPrefixes para o servidor em solicitações separadas (talvez em paralelo). Também é aceitável que o cliente envie prefixos de hash não relacionados ou gerados aleatoriamente com os prefixos de hash em expressionHashPrefixes, desde que o número de prefixos de hash enviados em uma única solicitação não exceda 30.

Exemplos de solicitação

Esta seção documenta alguns exemplos de uso direto da API HTTP para acessar a Navegação segura do Google. Em geral, é recomendável usar uma vinculação de linguagem gerada, porque ela processa automaticamente a codificação e a decodificação de maneira conveniente. Consulte a documentação para saber mais sobre essa vinculação.

Confira um exemplo de solicitação HTTP usando o método hashes.search:

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

O corpo da resposta é um payload formatado por buffer de protocolo que pode ser decodificado.

Confira um exemplo de solicitação HTTP usando o método hashLists.batchGet:

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw-4b

O corpo da resposta é, mais uma vez, um payload formatado por buffer de protocolo que pode ser decodificado.