Package google.security.safebrowsing.v4

Index

SafeBrowsing

Les API Safe Browsing permettent aux clients de comparer des ressources Web (le plus souvent des URL) à des listes de ressources Web non sécurisées qui sont constamment mises à jour par Google. Les API Safe Browsing (v4) incluent les API Update et Lookup.

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

Tout d'abord, les clients mettent en correspondance leurs listes locales pour déterminer l'état (sécurité ou non sécurisé) d'une ressource Web donnée. Le plus souvent, les listes sont constituées de préfixes de hachage d'expressions d'URL sur liste noire. Pour vérifier une URL, les clients génèrent les hachages d'une URL donnée et vérifient les conflits de préfixes dans leurs listes locales. Si une correspondance de préfixe est trouvé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.

Ensuite, 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 de client actualisé ainsi que les modifications que le client doit appliquer à ses listes de menaces locales.

L'API Lookup est conçue pour nos petits clients et leur permet de mettre en correspondance les ressources directement avec les listes de menaces de la navigation sécurisée via la méthode FindThreatMatchs.

Les clients qui utilisent l'API Update ou Lookup peuvent obtenir la liste des listes de menaces de la navigation sécurisée pouvant être téléchargées via la méthode ListThreatLists.

{-- Approuvée_THREAT_REPORTER: Les clients de confiance peuvent envoyer des rapports à Google pour analyse via la méthode SubmitThreatReport. --}

FetchThreatListUpdates

rpc FetchThreatListUpdates(FetchThreatListUpdatesRequest) returns (FetchThreatListUpdatesResponse)

Récupère les mises à jour les plus récentes de la liste des 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 menaces correspondant aux listes de la navigation sécurisée.
ListThreatLists

rpc ListThreatLists(Empty) returns (ListThreatListsResponse)

Répertorie les listes des menaces associées à la navigation sécurisée pouvant être téléchargées.

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 du client associées aux requêtes de l'API Safe Browsing.

Champs
client_id

string

Un ID client qui identifie (idéalement) de manière unique l'implémentation client de l'API Safe Browsing.
client_version

string

Version de l'implémentation client.

CompressionType

Les différentes manières de compresser les ensembles d'entrées de menaces

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

FetchThreatListUpdatesRequest

Cette page décrit une requête de mise à jour de l'API Safe Browsing. Les clients peuvent demander des mises à jour de plusieurs listes avec une seule requête. Si aucune mise à jour n'est disponible pour cette liste, le serveur risque de ne pas répondre à toutes les demandes. REMARQUE: L'index du champ 2 n'est pas utilisé. SUIVANT: 5

Champs
client

ClientInfo

Métadonnées du client.
list_update_requests[]

ListUpdateRequest

Mise à jour de la liste des menaces demandée.

ListUpdateRequest

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

Champs
threat_type

ThreatType

Type de menace posé par les entrées présentes dans la liste.
platform_type

PlatformType

Type de plate-forme menacée par les entrées présentes dans 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 chiffré du client reçu lors de la dernière mise à jour réussie de la liste).
constraints

Constraints

Contraintes associées à cette requête.

Contraintes

Contraintes pour cette mise à jour.

Champs
max_update_entries

int32

Taille maximale du nombre d'entrées. La mise à jour ne contiendra pas plus d'entrées que cette valeur. Cela devrait être une puissance de 2 comprise entre 2**10 et 2**20. Si la valeur est zéro, 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 est prêt à avoir dans la base de données locale pour la liste spécifiée. Cela devrait être une puissance de 2 comprise entre 2**10 et 2**20. Si la valeur est zéro, aucune limite de taille de la base de données n'est définie.
region

string

Demande la liste pour un emplacement géographique spécifique. Si cette règle n'est pas configurée, le serveur peut choisir cette valeur en fonction de l'adresse IP de l'utilisateur. Attend le format 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. Attend le format ISO 639 alpha-2.
device_location

string

Emplacement physique du client, exprimé sous la forme d'un code de région ISO 31166-1 alpha-2.

FetchThreatListUpdatesResponse

Champs
list_update_responses[]

ListUpdateResponse

Mises à jour de 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 donnée.
minimum_wait_duration

Duration

Durée minimale que le client doit attendre avant d'envoyer une requête de mise à jour. Si ce champ n'est pas défini, les clients peuvent se mettre à jour dès qu'ils le souhaitent.

ListUpdateResponse

Mise à jour d'une liste individuelle.

Champs
threat_type

ThreatType

Type de menace pour lequel des 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 de la part du client lorsque la réponse est reçue.
additions[]

ThreatEntrySet

Ensemble d'entrées à ajouter à la liste des types de menaces locaux. Répétition pour permettre l'envoi d'une combinaison de données brutes et compressées dans une seule réponse.
removals[]

ThreatEntrySet

Ensemble d'entrées à supprimer de la liste des types de menaces locaux. En pratique, ce champ est vide ou contient exactement un ThreatEntrySet.
new_client_state

bytes

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

Checksum

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 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 vraiment obsolète ou qu'il est soupçonné d'être corrompu.

FindFullHashesRequest

Requête pour renvoyer des 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 des listes de menaces locales du client.
threat_info

ThreatInfo

Listes et hachages à vérifier.
api_client

ClientInfo

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

FindFullHashesResponse

Champs
matches[]

ThreatMatch

Hachages complets correspondant aux préfixes demandés.
minimum_wait_duration

Duration

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

Duration

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

FindThreatMatchesRequest

Requête 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 dont les correspondances doivent être vérifiées.

FindThreatMatchesResponse

Champs
matches[]

ThreatMatch

La liste des menaces correspond.

ListThreatListsResponse

Champs
threat_lists[]

ThreatListDescriptor

Listes pouvant être téléchargées par le client.

PlatformType

Types de plates-formes.

Enums
PLATFORM_TYPE_UNSPECIFIED Plate-forme inconnue.
WINDOWS Menace pesant sur Windows.
LINUX Menace pesant sur Linux.
ANDROID Menace pesant sur Android.
OSX Menace pesant sur OS X.
IOS Menace pesant sur iOS.
ANY_PLATFORM Menace représentée contre au moins une des plates-formes définies.
ALL_PLATFORMS Menace pesant sur toutes les plates-formes définies.
CHROME Menace pesant sur Chrome.

RawHashes

Entrées de menaces non compressées sous forme de hachage d'une longueur de préfixe particulière. La taille des hachages peut varier de 4 à 32 octets. Une grande majorité correspond à 4 octets, mais certains hachages sont allongés s'ils entrent en conflit avec le hachage d'une URL populaire.

Utilisé pour envoyer ThreatEntrySet à des clients non compatibles avec la compression ou lors de l'envoi de hachages de moins de 4 octets à des clients compatibles avec la compression.

Champs
prefix_size

int32

Nombre d'octets pour chaque préfixe encodé ci-dessous. La valeur de ce champ peut être comprise entre 4 (préfixe le plus court) et 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'index bruts à supprimer d'une liste locale.

Champs
indices[]

int32

Index à supprimer d'une liste locale triée lexicographiquement.

RiceDeltaEncoding

Les données encodées en Rice-Golomb. Utilisé pour envoyer des hachages de 4 octets compressés ou des index de suppression compressés.

Champs
first_value

int64

Décalage de la première entrée des données encodées ou, si un seul entier a été encodé, la valeur de cet entier unique. Si le champ est vide ou manquant, indiquez la valeur zéro.
rice_parameter

int32

Le paramètre Golomb-Rice, qui est un nombre compris entre 2 et 28. Ce champ est manquant (c'est-à-dire zéro) si la valeur de num_entries est zéro.
num_entries

int32

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

bytes

Deltas encodés à l'aide du codeur Golomb-Rice

ThreatEntry

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

Champs
hash

bytes

Un préfixe de hachage, composé des 4 à 32 octets les plus significatifs d'un hachage SHA256. 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 condensés binaires et hexadécimaux. Pour les requêtes JSON, les condensés 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 des métadonnées associées à chaque type de menace.

Champs
entries[]

MetadataEntry

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 d'entrée des métadonnées. Pour les requêtes JSON, la valeur est encodée en base64.

ThreatEntrySet

Ensemble de menaces qui doivent être ajoutées ou supprimées de la base de données locale d'un client.

Champs
compression_type

CompressionType

Type de compression pour les entrées de cet ensemble.
raw_hashes

RawHashes

Entrées brutes au format SHA256
raw_indices

RawIndices

Indices bruts d'élimination pour une liste locale.
rice_hashes

RiceDeltaEncoding

Préfixes à 4 octets encodés pour les entrées au format SHA256, utilisant un encodage Golomb-Rice. Les hachages sont convertis en uint32, triés par ordre croissant, puis encodés en delta et stockés en tant que coded_data.
rice_indices

RiceDeltaEncoding

Indices de listes locaux encodés, triés de façon lexicographique, utilisant un encodage Golomb-Rice. Utilisé pour envoyer les index de suppression compressés. Les index de suppression (uint32) sont triés par ordre croissant, puis encodés en delta et stockés sous forme de données encodées.

ThreatEntryType

Types d'entrées qui présentent des menaces. Les listes de menaces sont des collections d’entrées d’un seul type.

Enums
THREAT_ENTRY_TYPE_UNSPECIFIED URL indéterminée.
URL Une URL.
EXECUTABLE Un programme exécutable.

ThreatInfo

Informations concernant une ou plusieurs menaces envoyées par un client lors de la recherche de correspondances dans les 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 la menace à vérifier.

ThreatListDescriptor

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

Champs
threat_type

ThreatType

Type de menace posé 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

Une correspondance est établie 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. Les clients ne doivent pas mettre cette réponse en cache pendant une durée supérieure à cette durée afin d'éviter les faux positifs.

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 logicielle indésirable.
POTENTIALLY_HARMFUL_APPLICATION Type de menace d'application potentiellement dangereuse.