Method: hashes.search

Suche nach vollständigen Hashes, die den angegebenen Präfixen entsprechen.

Dies ist eine benutzerdefinierte Methode gemäß der Definition in https://google.aip.dev/136. Die benutzerdefinierte Methode bezieht sich darauf, dass diese Methode einen benutzerdefinierten Namen innerhalb der allgemeinen API-Entwicklungsnomenklatur von Google hat. Sie bezieht sich nicht auf die Verwendung einer benutzerdefinierten HTTP-Methode.

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Abfrageparameter

Parameter
hashPrefixes[]

string (bytes format)

Erforderlich. Die Hash-Präfixe, nach denen gesucht werden soll. Clients DÜRFEN NICHT mehr als 1.000 Hash-Präfixe senden. Bei der URL-Verarbeitung sollten Clients jedoch NICHT mehr als 30 Hash-Präfixe senden müssen.

Derzeit muss jedes Hash-Präfix genau 4 Byte lang sein. KANN in Zukunft entspannt werden.

Ein base64-codierter String.
filter

string

Optional. Wenn der Client an Filtern interessiert ist, um z. B. nur bestimmte Arten von Bedrohungen abzurufen, kann dies angegeben werden. Wenn keine Angabe gemacht wird, werden alle übereinstimmenden Bedrohungen zurückgegeben. Es wird dringend empfohlen, diese Option wegzulassen, um den bestmöglichen Schutz von Safe Browsing zu erhalten.

Der Filter wird mithilfe der Google Common Expression Language definiert, die Sie unter https://github.com/google/cel-spec zusammen mit allgemeinen Beispielen finden. Hier einige konkrete Beispiele:

Für den Filter „"threatType == ThreatType.SOCIAL_ENGINEERING"“ muss unter FullHashDetail der Bedrohungstyp SOCIAL_ENGINEERING sein. Die Kennung "threatType" bezieht sich auf den aktuellen Bedrohungstyp. Die Kennung "ThreatType" bezieht sich auf die Sammlung aller möglichen Bedrohungstypen.

Für den Filter „"threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]"“ muss der Bedrohungstyp UNWANTED_SOFTWARE oder MALWARE sein.

Anfragetext

Der Anfragetext muss leer sein.

Antworttext

Die Antwort, die nach der Suche nach Bedrohungs-Hashes zurückgegeben wurde.

Wenn nichts gefunden wird, gibt der Server den Status „OK“ (HTTP-Statuscode 200) ohne das Feld fullHashes zurück, anstatt den Status NOT_FOUND (HTTP-Statuscode 404).

Neu in Version 5: Es gibt eine Trennung zwischen FullHash und FullHashDetail. Wenn ein Hash eine Website mit mehreren Bedrohungen darstellt (z.B. sowohl MALWARE als auch SOCIAL_ENGINEERING), muss der vollständige Hash nicht zweimal gesendet werden wie in V4. Außerdem wurde die Cache-Dauer zu einem einzigen cacheDuration-Feld vereinfacht.

Bei Erfolg enthält der Antworttext Daten mit der folgenden Struktur:

JSON-Darstellung 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Felder
fullHashes[]

object (FullHash)

Unsortierte Liste. Die ungeordnete Liste der gefundenen vollständigen Hashes.
cacheDuration

string (Duration format)

Die clientseitige Cache-Dauer. Der Kunde MÜSSEN diese Dauer zur aktuellen Uhrzeit hinzufügen, um die Ablaufzeit zu bestimmen. Die Ablaufzeit gilt dann für jedes Hash-Präfix, das vom Client in der Anfrage abgefragt wird, unabhängig davon, wie viele vollständige Hashes in der Antwort zurückgegeben werden. Auch wenn der Server keine vollständigen Hashes für ein bestimmtes Hash-Präfix zurückgibt, MUSS dies ebenfalls vom Client im Cache gespeichert werden.

Wenn und nur wenn das Feld fullHashes leer ist, KANN der Client den cacheDuration erhöhen, um einen neuen Ablauf zu bestimmen, der nach dem vom Server angegebenen Zeitpunkt liegt. Die Cache-Dauer darf in jedem Fall nicht länger als 24 Stunden sein.

Wichtig: Der Client DARF NICHT davon ausgehen, dass der Server für alle Antworten dieselbe Cache-Dauer zurückgibt. Der Server KANN für unterschiedliche Antworten je nach Situation unterschiedliche Cache-Daueren wählen.

Die Dauer in Sekunden mit bis zu neun Nachkommastellen und am Ende mit "s". Beispiel: "3.5s".

FullHash

Der vollständige Hash, der mit einer oder mehreren Übereinstimmungen identifiziert wurde.

JSON-Darstellung 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Felder
fullHash

string (bytes format)

Entspricht dem vollständigen Hashwert. Das ist der SHA256-Hash. Die Länge beträgt genau 32 Byte.

Ein base64-codierter String.
fullHashDetails[]

object (FullHashDetail)

Unsortierte Liste. Ein wiederkehrendes Feld zur Angabe der für diesen vollständigen Hash relevanten Details.

FullHashDetail

Details zu einem übereinstimmenden vollständigen Hash.

Wichtiger Hinweis zur Aufwärtskompatibilität: Der Server kann jederzeit neue Bedrohungstypen und Bedrohungsattribute hinzufügen. werden diese Ergänzungen als geringfügige Versionsänderungen betrachtet. Gemäß den Richtlinien von Google werden Nebenversionen in APIs nicht offengelegt (siehe https://cloud.google.com/apis/design/versioning für die Richtlinie zur Versionsverwaltung). Clients MÜSSEN also darauf vorbereitet sein, FullHashDetail-Nachrichten mit ThreatType-Enum-Werten oder ThreatAttribute-Enum-Werten zu erhalten, die vom Client als ungültig angesehen werden. Daher ist der Client dafür verantwortlich, die Gültigkeit aller ThreatType- und ThreatAttribute-enum-Werte zu prüfen. Wenn ein Wert als ungültig betrachtet wird, MUSS der Kunde die gesamte FullHashDetail-Nachricht ignorieren.

JSON-Darstellung 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Felder
threatType

enum (ThreatType)

Die Art der Bedrohung. Dieses Feld wird nie leer sein.
attributes[]

enum (ThreatAttribute)

Unsortierte Liste. Zusätzliche Attribute zu diesen vollständigen Hashes. Dieses Feld ist möglicherweise leer.

ThreatAttribute

Attribute von Bedrohungen. Diese Attribute können einer bestimmten Bedrohung zusätzliche Bedeutung geben, wirken sich jedoch nicht auf den Bedrohungstyp aus. Beispielsweise kann ein Attribut einen niedrigeren Konfidenzwert angeben, während ein anderes Attribut eine höhere Konfidenz angeben kann. In Zukunft werden möglicherweise weitere Attribute hinzugefügt.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED Unbekanntes Attribut. Wenn dies vom Server zurückgegeben wird, muss der Client das umschließende FullHashDetail vollständig ignorieren.
CANARY Gibt an, dass der ThreatType nicht für die Erzwingung verwendet werden soll.
FRAME_ONLY Gibt an, dass der ThreatType nur für die Erzwingung von Frames verwendet werden soll.