Package google.security.safebrowsing.v4

Index

SafeBrowsing

Les API Safe Browsing permettent aux clients de comparer des ressources Web (généralement des URL) aux listes de ressources Web non sécurisées constamment mises à jour par Google. Les API Safe Browsing (v4) incluent l'API Update et l'API Lookup.

L'API Update est conçue pour nos plus grands clients et inclut les méthodes FindFullHashes et FetchThreatListUpdates . L'API Update exige que les clients gèrent les listes de menaces téléchargées dans une base de données locale.

Tout d'abord, les clients effectuent des correspondances avec leurs listes locales pour déterminer l'état (sûr ou non) d'une ressource Web donnée. La plupart du temps, les listes sont constituées de préfixes de hachage des expressions d'URL figurant sur la liste noire. Pour vérifier une URL, les clients génèrent les hachages d'une URL donnée et recherchent des conflits de préfixes dans leurs listes locales. Si une correspondance de préfixe est détectée, le client obtient les hachages complets associés au préfixe de hachage correspondant via la méthode FindFullHashes. Le client compare ensuite le hachage complet local aux hachages complets renvoyés. Une correspondance indique que l'URL n'est pas sécurisée.

Deuxièmement, les clients obtiennent les mises à jour de leurs bases de données locales via la méthode FetchThreatListUpdates, qui prend l'état actuel du client et renvoie un état client mis à jour, ainsi que les modifications que le client doit appliquer à ses listes de menaces locales.

L'API Lookup est conçue pour nos petits clients. Elle leur permet de faire correspondre des ressources directement aux listes de menaces Safe Browsing via la méthode FindThreatMatches.

Les clients qui utilisent l'API Update ou l'API Lookup peuvent obtenir la liste des listes de menaces Safe Browsing disponibles à télécharger via la méthode ListThreatLists.

{-- TRUSTED_THREAT_REPORTER: les clients de menaces fiables peuvent envoyer des rapports à Google pour analyse via la méthode SubmitThreatReport. --}

FetchThreatListUpdates

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

Récupère les dernières mises à jour de la liste de menaces. Un client peut demander des mises à jour pour plusieurs listes à la fois.
FindFullHashes

rpc FindFullHashes(FindFullHashesRequest) returns (FindFullHashesResponse)

Recherche les hachages complets correspondant aux préfixes de hachage demandés.
FindThreatMatches

rpc FindThreatMatches(FindThreatMatchesRequest) returns (FindThreatMatchesResponse)

Recherche les entrées de menace correspondant aux listes de navigation sécurisée.
ListThreatLists

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

Répertorie les listes de menaces de la navigation sécurisée disponibles au téléchargement.

Total

État attendu de la base de données locale d'un client.

Champs
sha256

bytes

Hachage SHA256 de l'état du client, c'est-à-dire de la liste triée de tous les hachages présents dans la base de données.

ClientInfo

Métadonnées client associées aux requêtes de l'API Safe Browsing.

Champs
client_id

string

ID client qui identifie (si possible) de manière unique l'implémentation cliente de l'API Safe Browsing.
client_version

string

Version de l'implémentation client.

CompressionType

Méthodes de compression des ensembles d'entrées de menaces.

Enums
COMPRESSION_TYPE_UNSPECIFIED Inconnu.
RAW Données brutes, non compressées.
RICE Données encodées Rice-Golomb.

FetchThreatListUpdatesRequest

Décrit une requête de mise à jour de l'API Safe Browsing. Les clients peuvent demander des mises à jour pour plusieurs listes dans une seule requête. Le serveur peut ne pas répondre à toutes les requêtes s'il n'a aucune mise à jour pour cette liste. REMARQUE: L'index de champ 2 n'est pas utilisé. SUIVANT: 5

Champs
client

ClientInfo

Métadonnées du client.
list_update_requests[]

ListUpdateRequest

Mises à jour de la liste de menaces demandées.

ListUpdateRequest

Une seule requête de mise à jour de liste.

Champs
threat_type

ThreatType

Type de menace représentée par les entrées de la liste.
platform_type

PlatformType

Type de plate-forme à risque en fonction des entrées de la liste.
threat_entry_type

ThreatEntryType

Types d'entrées présents dans la liste.
state

bytes

État actuel du client pour la liste demandée (état client chiffré reçu lors de la dernière mise à jour de la liste réussie).
constraints

Constraints

Contraintes associées à cette requête.

Contraintes

Contraintes de cette mise à jour.

Champs
max_update_entries

int32

Taille maximale en nombre d'entrées. La mise à jour ne contiendra pas plus d'entrées que cette valeur. Il doit s'agir d'une puissance de 2 comprise entre 2**10 et 2**20. Si la valeur est nulle, aucune limite de taille de mise à jour n'est définie.
max_database_entries

int32

Définit le nombre maximal d'entrées que le client souhaite avoir dans la base de données locale pour la liste spécifiée. Il doit s'agir d'une puissance de 2 comprise entre 2**10 et 2**20. Si la valeur est nulle, aucune limite de taille de base de données n'est définie.
region

string

Demande la liste pour une zone géographique spécifique. Si ce n'est pas le cas, le serveur peut choisir cette valeur en fonction de l'adresse IP de l'utilisateur. Format attendu : ISO 3166-1 alpha-2.
supported_compressions[]

CompressionType

Types de compression acceptés par le client.
language

string

Demande les listes pour une langue spécifique. Format ISO 639 alpha-2 attendu.
device_location

string

Emplacement physique d'un client, exprimé sous la forme d'un code régional ISO 3166-1 alpha-2.

FetchThreatListUpdatesResponse

Champs
list_update_responses[]

ListUpdateResponse

Mises à jour de la liste demandées par les clients. Le nombre de réponses peut être inférieur au nombre de requêtes envoyées par les clients. C'est le cas, par exemple, si le serveur ne dispose d'aucune mise à jour pour une liste spécifique.
minimum_wait_duration

Duration

Durée minimale pendant laquelle le client doit attendre avant d'envoyer une demande de mise à jour. Si ce champ n'est pas défini, les clients peuvent effectuer des mises à jour dès qu'ils le souhaitent.

ListUpdateResponse

Mise à jour d'une liste spécifique.

Champs
threat_type

ThreatType

Type de menace pour lequel les données sont renvoyées.
threat_entry_type

ThreatEntryType

Format des menaces.
platform_type

PlatformType

Type de plate-forme pour laquelle les données sont renvoyées.
response_type

ResponseType

Type de réponse. Cela peut indiquer qu'une action est requise du client lorsqu'il reçoit la réponse.
additions[]

ThreatEntrySet

Ensemble d'entrées à ajouter à la liste d'un type de menace local. Répété pour permettre d'envoyer une combinaison de données brutes et compressées dans une seule réponse.
removals[]

ThreatEntrySet

Ensemble d'entrées à supprimer de la liste d'un type de menace local. En pratique, ce champ est vide ou contient exactement un seul ThreatEntrySet.
new_client_state

bytes

Nouvel état du client, au format chiffré. Opaque pour les clients.
checksum

Checksum

Le hachage SHA256 attendu de l'état du client, c'est-à-dire de la liste triée de tous les hachages présents dans la base de données après l'application de la mise à jour fournie. Si l'état du client ne correspond pas à l'état attendu, le client doit ignorer cette mise à jour et réessayer plus tard.

ResponseType

Type de réponse envoyée au client.

Enums
RESPONSE_TYPE_UNSPECIFIED Inconnu.
PARTIAL_UPDATE Les mises à jour partielles sont appliquées à la base de données locale existante du client.
FULL_UPDATE Les mises à jour complètes remplacent l'intégralité de la base de données locale du client. Cela signifie que le client était très obsolète ou qu'il est considéré comme corrompu.

FindFullHashesRequest

Requête visant à renvoyer les hachages complets correspondant aux préfixes de hachage fournis.

Champs
client

ClientInfo

Métadonnées du client.
client_states[]

bytes

États actuels du client pour chacune de ses listes de menaces locales.
threat_info

ThreatInfo

Les listes et les hachages à vérifier.
api_client

ClientInfo

Métadonnées client associées aux appelants d'API de niveau supérieur créées sur la base de l'implémentation du client.

FindFullHashesResponse

Champs
matches[]

ThreatMatch

Les hachages complets correspondant aux préfixes demandés.
minimum_wait_duration

Duration

Durée minimale pendant laquelle le client doit attendre avant d'envoyer une requête de recherche de hachages. Si ce champ n'est pas défini, les clients peuvent envoyer une requête dès qu'ils le souhaitent.
negative_cache_duration

Duration

Pour les entités demandées qui ne correspondaient pas à la liste de menaces, durée de mise en cache de la réponse.

FindThreatMatchesRequest

Demande de vérification des entrées par rapport à des listes.

Champs
client

ClientInfo

Métadonnées du client.
threat_info

ThreatInfo

Listes et entrées à rechercher

FindThreatMatchesResponse

Champs
matches[]

ThreatMatch

La liste des menaces correspond.

ListThreatListsResponse

Champs
threat_lists[]

ThreatListDescriptor

Listes disponibles en téléchargement par le client.

PlatformType

Types de plates-formes

Enums
PLATFORM_TYPE_UNSPECIFIED Plate-forme inconnue.
WINDOWS Menace pour Windows.
LINUX Menaces pour Linux
ANDROID Menace pour Android
OSX Menace pour OS X
IOS Menace pour iOS
ANY_PLATFORM Menace posée à au moins une des plates-formes définies.
ALL_PLATFORMS Menace posée à toutes les plates-formes définies.
CHROME Menaces pour Chrome

RawHashes

Entrées de menace non compressées au format hachage d'une longueur de préfixe spécifique. La taille des hachages peut varier de 4 à 32 octets. La grande majorité d'entre eux comportent 4 octets, mais certains hachages sont allongés s'ils entrent en conflit avec le hachage d'une URL populaire.

Utilisé pour envoyer ThreatEntrySet aux clients qui ne prennent pas en charge la compression ou pour envoyer des hachages autres que 4 octets aux clients qui prennent en charge la compression.

Champs
prefix_size

int32

Nombre d'octets pour chaque préfixe encodé ci-dessous. La longueur de ce champ peut varier de 4 (préfixe le plus court) à 32 (hachage SHA256 complet).
raw_hashes

bytes

Les hachages, au format binaire, concaténés en une longue chaîne. Les hachages sont triés par ordre lexicographique. Pour les utilisateurs de l'API JSON, les hachages sont encodés en base64.

RawIndices

Ensemble d'indices bruts à supprimer d'une liste locale.

Champs
indices[]

int32

Indices à supprimer d'une liste locale triée par ordre alphabétique.

RiceDeltaEncoding

Données encodées Rice-Golomb. Utilisé pour envoyer des hachages compressés à 4 octets ou des indices de suppression compressés.

Champs
first_value

int64

Décalage de la première entrée dans les données encodées ou, si un seul entier a été encodé, valeur de cet entier. Si le champ est vide ou manquant, la valeur est supposée être nulle.
rice_parameter

int32

Paramètre Golomb-Rice, qui est un nombre compris entre 2 et 28. Ce champ est manquant (c'est-à-dire, nul) si num_entries est nul.
num_entries

int32

Nombre d'entrées encodées en delta dans les données encodées. Si un seul entier a été encodé, cette valeur sera nulle et la valeur unique sera stockée dans first_value.
encoded_data

bytes

Deltas encodés à l'aide de l'encodeur Golomb-Rice.

ThreatEntry

Menace individuelle, par exemple une URL malveillante ou sa représentation en hachage. Un seul de ces champs doit être défini.

Champs
hash

bytes

Préfixe de hachage, composé des 4 à 32 octets les plus significatifs d'un hachage SHA-256. Ce champ est au format binaire. Pour les requêtes JSON, les hachages sont encodés en base64.
url

string

une URL ;
digest

bytes

Condensé d'un exécutable au format SHA256. L'API est compatible avec les récapitulatifs binaires et hexadécimaux. Pour les requêtes JSON, les récapitulatifs sont encodés en base64.

ThreatEntryMetadata

Métadonnées associées à une entrée de menace spécifique. Le client doit connaître les paires clé/valeur de métadonnées associées à chaque type de menace.

Champs
entries[]

MetadataEntry

Les entrées de métadonnées.

MetadataEntry

Une seule entrée de métadonnées.

Champs
key

bytes

Clé d'entrée des métadonnées. Pour les requêtes JSON, la clé est encodée en base64.
value

bytes

Valeur de l'entrée de métadonnées. Pour les requêtes JSON, la valeur est encodée en base64.

ThreatEntrySet

Ensemble de menaces à ajouter ou à supprimer de la base de données locale d'un client.

Champs
compression_type

CompressionType

Type de compression des entrées de cet ensemble.
raw_hashes

RawHashes

Entrées brutes au format SHA256.
raw_indices

RawIndices

Indices de suppression bruts pour une liste locale.
rice_hashes

RiceDeltaEncoding

Préfixes de 4 octets encodés des entrées au format SHA256, à l'aide d'un encodage Golomb-Rice. Les hachages sont convertis en uint32, triés par ordre croissant, puis codés en delta et stockés sous forme de données encodées.
rice_indices

RiceDeltaEncoding

Indices de liste locaux encodés et triés par ordre alphabétique, à l'aide d'un encodage Golomb-Rice. Permet d'envoyer des indices de suppression compressés. Les indices de suppression (uint32) sont triés par ordre croissant, puis codés en delta et stockés sous forme de données encodées.

ThreatEntryType

Types d'entrées qui constituent des menaces. Les listes de menaces sont des collections d'entrées d'un même type.

Enums
THREAT_ENTRY_TYPE_UNSPECIFIED Non spécifié.
URL une URL ;
EXECUTABLE Programme exécutable.

ThreatInfo

Informations sur une ou plusieurs menaces qu'un client envoie lors de la recherche de correspondances dans des listes de menaces.

Champs
threat_types[]

ThreatType

Types de menaces à vérifier.
platform_types[]

PlatformType

Types de plates-formes à vérifier.
threat_entry_types[]

ThreatEntryType

Types d'entrées à vérifier.
threat_entries[]

ThreatEntry

Entrées de menace à vérifier.

ThreatListDescriptor

Décrit une liste de menaces individuelle. Une liste est définie par trois paramètres: le type de menace, le type de plate-forme ciblée par la menace et le type d'entrées de la liste.

Champs
threat_type

ThreatType

Type de menace représenté par les entrées de la liste.
platform_type

PlatformType

Type de plate-forme ciblé par les entrées de la liste.
threat_entry_type

ThreatEntryType

Types d'entrées contenus dans la liste.

ThreatMatch

Correspondance lors de la vérification d'une entrée de menace dans les listes de menaces de la navigation sécurisée.

Champs
threat_type

ThreatType

Type de menace correspondant à cette menace.
platform_type

PlatformType

Type de plate-forme correspondant à cette menace.
threat_entry_type

ThreatEntryType

Type d'entrée de menace correspondant à cette menace.
threat

ThreatEntry

Menace correspondant à cette menace.
threat_entry_metadata

ThreatEntryMetadata

Métadonnées facultatives associées à cette menace.
cache_duration

Duration

Durée de vie du cache pour la correspondance renvoyée. Pour éviter les faux positifs, les clients ne doivent pas mettre en cache cette réponse pendant plus de cette durée.

ThreatType

Types de menaces.

Enums
THREAT_TYPE_UNSPECIFIED Inconnu.
MALWARE Type de menace de logiciel malveillant.
SOCIAL_ENGINEERING Type de menace d'ingénierie sociale.
UNWANTED_SOFTWARE Type de menace de logiciel indésirable.
POTENTIALLY_HARMFUL_APPLICATION Type de menace d'application potentiellement dangereuse.