Method: hashes.search

Nach vollständigen Hashes suchen, die den angegebenen Präfixen entsprechen.

Dies ist eine benutzerdefinierte Methode, wie in https://google.aip.dev/136 definiert. Die benutzerdefinierte Methode bezieht sich auf diese Methode, die einen benutzerdefinierten Namen innerhalb der allgemeinen API-Entwicklungsnommenklatur von Google hat. Sie bezieht sich nicht auf die Verwendung einer benutzerdefinierten HTTP-Methode.

HTTP-Anfrage

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

Die URL verwendet die Syntax der gRPC-Transcodierung.

Abfrageparameter

Parameter
hashPrefixes[]

string (bytes format)

Erforderlich. Die Hash-Präfixe, die nachgeschlagen werden sollen. Clients DÜRFEN NICHT mehr als 1.000 Hash-Präfixe senden. Nach dem URL-Verarbeitungsverfahren sollten Kunden jedoch NICHT mehr als 30 Hash-Präfixe senden müssen.

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

Ein base64-codierter String.

Anfragetext

Der Anfragetext muss leer sein.

Antworttext

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

Wird nichts gefunden, gibt der Server den Status „OK“ (HTTP-Statuscode 200) zurück, wobei das Feld fullHashes leer ist, statt den Status NOT_FOUND (HTTP-Statuscode 404).

Neuerungen 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 doppelt gesendet werden wie in V4. Außerdem wurde die Cache-Dauer auf ein einzelnes 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 aller vollständigen Hashes, die gefunden wurden.
cacheDuration

string (Duration format)

Die clientseitige Cache-Dauer. Der Client MUSS diese Dauer zur aktuellen Zeit 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. Selbst 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.

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

Eine Dauer in Sekunden mit bis zu neun Nachkommastellen, die auf „s“ endet. 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)

Der übereinstimmende vollständige Hash. Das ist der SHA256-Hash. Die Länge beträgt genau 32 Byte.

Ein base64-codierter String.
fullHashDetails[]

object (FullHashDetail)

Unsortierte Liste. Wiederkehrendes Feld, das die für diesen vollständigen Hash relevanten Details angibt.

FullHashDetail

Details zum übereinstimmenden vollständigen Hash.

Wichtiger Hinweis zur Aufwärtskompatibilität: Neue Bedrohungstypen und Bedrohungsattribute können jederzeit vom Server hinzugefügt werden; diese Hinzufügungen gelten als geringfügige Versionsänderungen. Gemäß den Google-Richtlinien müssen in APIs keine Nebenversionsnummern offengelegt werden. Weitere Informationen zur Richtlinie zur Versionsverwaltung finden Sie unter https://cloud.google.com/apis/design/versioning. Daher MÜSSEN Clients auf den Empfang von FullHashDetail-Nachrichten vorbereitet sein, die ThreatType- oder ThreatAttribute-Enum-Werte enthalten, die vom Client als ungültig eingestuft werden. Daher liegt es in der Verantwortung des Clients, die Gültigkeit aller ThreatType- und ThreatAttribute-Enum-Werte zu prüfen. Wird ein Wert als ungültig betrachtet, MUSS der Client 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 kann leer sein.

ThreatType

Arten von Bedrohungen.

Enums
THREAT_TYPE_UNSPECIFIED Unbekannter Bedrohungstyp. Wird dies vom Server zurückgegeben, muss der Client die einschließende FullHashDetail vollständig ignorieren.
MALWARE

Malware-Bedrohungstyp. Malware ist eine Software oder mobile App, die speziell dazu entwickelt wurde, einem Computer, einem Mobilgerät, der darauf ausgeführten Software oder deren Nutzern zu schaden. Malware weist bösartiges Verhalten auf und installiert unter anderem Software ohne das Einverständnis des Nutzers sowie schädliche Software wie Viren.

Weitere Informationen finden Sie hier.
SOCIAL_ENGINEERING

Bedrohungstyp des Social Engineering. Social-Engineering-Seiten geben vor, im Namen eines Dritten zu handeln, um Zuschauer zu einer Aktion zu bewegen, bei der sie nur einem wahren Vertreter dieses Dritten vertrauen würden. Phishing ist eine Art von Social Engineering, bei der Zuschauer dazu verleitet werden, eine bestimmte Aktion auszuführen, bei der Informationen wie Anmeldedaten angegeben werden.

Weitere Informationen finden Sie hier.
UNWANTED_SOFTWARE Bedrohungstyp "Unerwünschte Software" Unerwünschte Software ist Software, die nicht den Prinzipien in Bezug auf Software entspricht, aber keine Malware ist.
POTENTIALLY_HARMFUL_APPLICATION Potenziell schädlicher Anwendungsbedrohungstyp, wie von Google Play Protect für den Play Store verwendet.

ThreatAttribute

Attribute von Bedrohungen. Diese Attribute verleihen einer bestimmten Bedrohung möglicherweise eine zusätzliche Bedeutung, wirken sich aber nicht auf die Art der Bedrohung aus. Beispielsweise kann ein Attribut eine niedrigere Konfidenz 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. Wird dies vom Server zurückgegeben, muss der Client die einschließende FullHashDetail vollständig ignorieren.
CANARY Gibt an, dass „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.