Method: hashes.search

Cerca hash completi corrispondenti ai prefissi specificati.

Si tratta di un metodo personalizzato come definito da https://google.aip.dev/136 (il metodo personalizzato si riferisce a questo metodo che ha un nome personalizzato nella nomenclatura di sviluppo generale delle API di Google; non si riferisce all'utilizzo di un metodo HTTP personalizzato).

Richiesta HTTP

GET https://safebrowsing.googleapis.com/v5alpha1/hashes:search

L'URL utilizza la sintassi di transcodifica gRPC.

Parametri di query

Parametri
hashPrefixes[]

string (bytes format)

Obbligatorio. I prefissi hash da controllare. I client NON DEVONO inviare più di 1000 prefissi hash. Tuttavia, in base alla procedura di elaborazione degli URL, i client NON DOVREBBERO inviare più di 30 prefissi hash.

Al momento, ogni prefisso hash deve essere lungo esattamente 4 byte. POTREBBE essere più rilassato in futuro.

Una stringa con codifica base64.
filter

string

(Facoltativo) È possibile specificare se il cliente è interessato ad applicare dei filtri, ad esempio recuperare solo tipi specifici di minacce. Se omesso, vengono restituite tutte le minacce corrispondenti. Ti consigliamo vivamente di omettere questa opzione per ottenere la protezione più completa che Navigazione sicura può offrire.

Il filtro viene specificato utilizzando Google Common Expression Language, disponibile all'indirizzo https://github.com/google/cel-spec insieme a esempi generici. Ecco alcuni esempi specifici che possono essere utilizzati qui:

Il filtro "threatType == ThreatType.SOCIAL_ENGINEERING" richiede che il tipo di minaccia all'interno di FullHashDetail sia SOCIAL_ENGINEERING. L'identificatore "threatType" si riferisce al tipo di minaccia attuale. L'identificatore "ThreatType" si riferisce alla raccolta di tutti i possibili tipi di minacce.

Il filtro "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" richiede che il tipo di minaccia sia UNWANTED_SOFTWARE o MALWARE.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

La risposta restituita dopo la ricerca negli hash delle minacce.

Se non viene trovato nulla, il server restituirà lo stato OK (codice di stato HTTP 200) con il campo fullHashes vuoto, anziché uno stato NOT_FOUND (codice di stato HTTP 404).

Novità della V5: è presente una separazione tra FullHash e FullHashDetail. Nel caso in cui un hash rappresenta un sito con più minacce (ad es. sia MALWARE che SOCIAL_ENGINEERING), non è necessario inviare l'hash completo il doppio rispetto alla versione V4. Inoltre, la durata della cache è stata semplificata in un singolo campo cacheDuration.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Campi
fullHashes[]

object (FullHash)

Elenco non ordinato. L'elenco non ordinato di hash completi trovati.
cacheDuration

string (Duration format)

La durata della cache lato client. Il client DEVE aggiungere questa durata all'ora corrente per determinare la data e l'ora di scadenza. La scadenza viene quindi applicata a ogni prefisso di hash sottoposto a query dal client nella richiesta, indipendentemente dal numero di hash completi restituiti nella risposta. Anche se il server non restituisce hash completi per un particolare prefisso hash, anche questo fatto DEVE essere memorizzato nella cache dal client.

Se e solo se il campo fullHashes è vuoto, il client POTREBBE aumentare il cacheDuration per determinare una nuova scadenza successiva a quella specificata dal server. In ogni caso, la durata aumentata della cache non deve essere superiore a 24 ore.

Importante: il client NON DEVE dare per scontato che il server restituisca la stessa durata della cache per tutte le risposte. Il server POTREBBE scegliere durate della cache diverse per risposte diverse a seconda della situazione.

Durata in secondi con un massimo di nove cifre frazionarie e termina con "s". Esempio: "3.5s".

FullHash

L'hash completo identificato con una o più corrispondenze.

Rappresentazione JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Campi
fullHash

string (bytes format)

L'hash completo corrispondente. Questo è l'hash SHA256. La lunghezza sarà esattamente di 32 byte.

Una stringa con codifica base64.
fullHashDetails[]

object (FullHashDetail)

Elenco non ordinato. Un campo ripetuto che identifica i dettagli relativi a questo hash completo.

FullHashDetail

Dettagli su un hash completo corrispondente.

Una nota importante sulla compatibilità diretta: il server può aggiungere nuovi tipi e attributi di minaccia in qualsiasi momento; queste aggiunte sono considerate modifiche minori alla versione. È prassi di Google non esporre numeri di versione minori nelle API (consulta la pagina https://cloud.google.com/apis/design/versioning per il criterio di controllo delle versioni), quindi i client DEVONO essere preparati a ricevere messaggi FullHashDetail contenenti valori enum ThreatType o ThreatAttribute valori enum considerati non validi dal client. Pertanto, è responsabilità del cliente verificare la validità di tutti i valori enum ThreatType e ThreatAttribute. Se un valore viene considerato non valido, il client DEVE ignorare l'intero messaggio FullHashDetail.

Rappresentazione JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Campi
threatType

enum (ThreatType)

Il tipo di minaccia. Questo campo non sarà mai vuoto.
attributes[]

enum (ThreatAttribute)

Elenco non ordinato. Attributi aggiuntivi relativi agli hash completi. Questo campo potrebbe essere vuoto.

ThreatAttribute

Attributi delle minacce. Questi attributi possono conferire un significato aggiuntivo a una particolare minaccia, ma non influiscono sul tipo di minaccia. Ad esempio, un attributo può indicare una confidenza più bassa, mentre un altro attributo può indicare una confidenza maggiore. In futuro potrebbero essere aggiunti altri attributi.

Enum
THREAT_ATTRIBUTE_UNSPECIFIED Attributo sconosciuto. Se viene restituito dal server, il client ignora del tutto il contenuto FullHashDetail che contiene.
CANARY Indica che il valore threatType non deve essere utilizzato per l'applicazione forzata.
FRAME_ONLY Indica che threatType deve essere utilizzato solo per l'applicazione forzata sui frame.