Package google.security.safebrowsing.v5alpha1

インデックス

SafeBrowsing

Safe Browsing API を使用すると、クライアントはウェブリソース（ほとんどの場合 URL）を、Google が常に更新している安全でないウェブリソースのリストと照らし合わせてチェックできます。

BatchGetHashLists

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

複数のハッシュリストを一度に取得します。

クライアントが複数のハッシュリストを取得する必要があることは非常に一般的です。通常の Get メソッドを複数回使用するよりも、このメソッドを使用することをおすすめします。

これは、https://google.aip.dev/231 で定義されている標準のバッチ GET メソッドであり、HTTP メソッドも GET です。
GetHashList

rpc GetHashList(GetHashListRequest) returns (HashList)

ハッシュリストの最新のコンテンツを取得します。ハッシュリストは、脅威リストまたはグローバル キャッシュなどの脅威以外のリストのいずれかです。

これは https://google.aip.dev/131 で定義されている標準の Get メソッドであり、HTTP メソッドも GET です。
ListHashLists

rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)

ハッシュリストを一覧表示します。

V5 API では、このメソッドによって返されたハッシュリストは削除されません。これにより、クライアントは、このメソッドの使用をスキップし、必要なすべてのハッシュリストをハードコードできます。

これは、https://google.aip.dev/132 で定義されている標準の List メソッドであり、HTTP メソッドは GET です。
SearchHashes

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

指定されたプレフィックスに一致する完全なハッシュを検索します。

これは、https://google.aip.dev/136 で定義されているカスタム メソッドです（カスタム メソッドとは、Google の一般的な API 開発用語でカスタム名を持つこのメソッドを指し、カスタム HTTP メソッドの使用を指すものではありません）。

BatchGetHashListsRequest

複数のハッシュリストを同時に取得するリクエスト。

フィールド
names[]

string

必須。特定のハッシュリストの名前。このリストは脅威リストの場合もあれば、グローバル キャッシュの場合もあります。名前に重複がないようにしてください。重複があると、クライアントにエラーが表示されます。
version[]

bytes

クライアントがすでに持っているハッシュリストのバージョン。クライアントがハッシュリストを初めて取得する場合は、このフィールドを空のままにします。それ以外の場合は、クライアントはサーバから以前に受信したバージョンを提供する必要があります。クライアントはこれらのバイトを操作してはなりません。

クライアントは、対応するリスト名と同じ順序でバージョンを送信する必要はありません。クライアントは、リクエストで名前の数よりも少ないバージョンまたは多いバージョンを送信できます。ただし、同じ名前に対応する複数のバージョンをクライアントが送信することはできません。送信すると、クライアントにエラーが返されます。

歴史的な注記: API の V4 では、これは states と呼ばれていましたが、わかりやすくするために version に名前が変更されました。
size_constraints

SizeConstraints

各リストのサイズ制約。省略した場合、制約はありません。なお、ここでのサイズはリストごとであり、すべてのリストを合計したものではありません。

BatchGetHashListsResponse

複数のハッシュリストを含むレスポンス。

フィールド
hash_lists[]

HashList

リクエストされた順序と同じ順序のハッシュリスト。

FullHash

1 つ以上の一致で識別された完全なハッシュ。

フィールド
full_hash

bytes

一致する完全なハッシュ。これは SHA256 ハッシュです。長さは 32 バイトになります。
full_hash_details[]

FullHashDetail

順序なしリスト。この完全なハッシュに関連する詳細を識別する繰り返しフィールド。

FullHashDetail

一致する完全ハッシュの詳細。

将来の互換性に関する重要な注意事項: 新しい脅威タイプと脅威属性は、サーバーがいつでも追加できます。これらの追加は、マイナー バージョンの変更と見なされます。Google のポリシーでは、API でマイナー バージョン番号を公開しないことを定めています（バージョニング ポリシーについては、https://cloud.google.com/apis/design/versioning をご覧ください）。そのため、クライアントは、クライアントが無効とみなす ThreatType 列挙値または ThreatAttribute 列挙値を含む FullHashDetail メッセージを受信する準備をする必要があります。したがって、すべての ThreatType と ThreatAttribute 列挙型値の有効性を確認するのはクライアントの責任です。いずれかの値が無効と見なされた場合、クライアントは FullHashDetail メッセージをすべて無視する必要があります。

フィールド
threat_type

ThreatType

脅威の種類。このフィールドは空になりません。
attributes[]

ThreatAttribute

順序なしリスト。完全なハッシュに関する追加属性。空でもかまいません。

GetHashListRequest

ハッシュリストを取得するためのリクエスト。脅威リストまたはグローバル キャッシュなどの脅威以外のリストのいずれかです。

V5 の新機能: わかりやすくするため、V4 の states の名前を version に変更しました。リストに名前が付けられ、プラットフォーム タイプと脅威エントリ タイプが削除されました。複数のリストに同じ脅威タイプを設定したり、1 つのリストで複数の脅威タイプを指定したりできるようになりました。多くのクライアント実装で問題を引き起こしていた V4 の可変長ハッシュ接頭辞とは対照的に、リスト内のすべてのハッシュの長さが 1 つになり、クライアント実装を大幅に効率化できるようになりました。制約が簡素化され、圧縮タイプが削除されました（圧縮は常に適用されます）。

フィールド
name

string

必須。この特定のハッシュリストの名前。脅威リストまたはグローバル キャッシュのいずれかです。
version

bytes

クライアントがすでに持っているハッシュリストのバージョン。クライアントがハッシュリストを初めて取得する場合は、このフィールドを空にする必要があります。それ以外の場合は、クライアントはサーバーから以前に受信したバージョンを提供する必要があります。クライアントはこれらのバイトを操作してはなりません。

v5 の新機能: API の v4 では states と呼ばれていましたが、わかりやすくするために version に名前が変更されました。
size_constraints

SizeConstraints

リストのサイズ制限。省略した場合、制約はありません。制約は、処理能力、帯域幅、ストレージに制限があるすべてのデバイスに推奨されます。

HashList

名前で識別されるハッシュのリスト。

フィールド
name

string

ハッシュリストの名前。グローバル キャッシュもハッシュリストであり、ここで参照できることに注意してください。
version

bytes

ハッシュリストのバージョン。クライアントはこれらのバイトを操作してはなりません。
partial_update

bool

true の場合、これはクライアントがすでに持っている内容に基づく追加と削除を含む部分的な差分です。false の場合、これは完全なハッシュリストです。

false の場合、クライアントは、このハッシュリストのローカルに保存されているバージョンをすべて削除する必要があります。これは、クライアントが保持しているバージョンが非常に古いか、クライアント データが破損していると見なされていることを意味します。compressed_removals フィールドは空になります。

true の場合、クライアントは削除してから追加を行うことで、増分更新を適用する必要があります。
compressed_removals

RiceDeltaEncoded32Bit

削除インデックスの Rice-delta エンコード バージョン。各ハッシュリストには 2^32 個未満のエントリしかないため、インデックスは 32 ビットの整数として扱われ、エンコードされます。
minimum_wait_duration

Duration

クライアントは、この時間以上待ってからハッシュリストを再度取得する必要があります。省略またはゼロの場合、クライアントは直ちにフェッチする必要があります。これは、サーバーにクライアントに送信する追加の更新があるが、クライアント指定の制約により送信できなかったことを示します。
sha256_checksum

bytes

すべてのハッシュの並べ替えられたリスト。SHA256 で再度ハッシュ化されています。これは、指定された更新を適用した後、データベース内に存在するすべてのハッシュの並べ替えられたリストのチェックサムです。更新が提供されていない場合、サーバーは既存のチェックサムを使用する必要があることを示すために、このフィールドを省略します。
metadata

HashListMetadata

ハッシュリストに関するメタデータ。これは GetHashList メソッドによって設定されるのではなく、ListHashLists メソッドによって設定されます。
共用体フィールド compressed_additions。追加の Rice-delta エンコード バージョン。追加のハッシュ プレフィックスの長さは、リスト内のすべての追加で一律です。compressed_additions は次のいずれかになります。
additions_four_bytes

RiceDeltaEncoded32Bit

4 バイトの追加。
additions_eight_bytes

RiceDeltaEncoded64Bit

8 バイトの加算。
additions_sixteen_bytes

RiceDeltaEncoded128Bit

16 バイトの追加。
additions_thirty_two_bytes

RiceDeltaEncoded256Bit

32 バイトの追加。

HashListMetadata

特定のハッシュリストに関するメタデータ。

フィールド
threat_types[]

ThreatType

順序なしリスト。空でない場合、ハッシュリストが脅威リストの一種であることを指定し、このハッシュリスト内のハッシュまたはハッシュ プレフィックスに関連付けられている脅威の種類を列挙します。エントリが脅威を表していない場合（安全なタイプである可能性が高い場合）は空になります。
likely_safe_types[]

LikelySafeType

順序なしリスト。空でない場合、ハッシュリストは安全と思われるハッシュのリストを表し、安全と思われる理由を列挙します。このフィールドは、threat_types フィールドと相互に排他的です。
description

string

このリストに関する説明（人が読める形式）。英語で記述されている。
hash_length

HashLength

このハッシュリストでサポートされているハッシュの長さ。各ハッシュリストは 1 つの長さのみをサポートします。同じ脅威タイプまたは安全なタイプのセットに異なるハッシュ長が導入されている場合は、個別のリストとして導入され、それぞれ名前とハッシュ長が設定されます。

HashLength

ハッシュリスト内のハッシュの長さ。

列挙型
HASH_LENGTH_UNSPECIFIED 長さが指定されていません。
FOUR_BYTES 各ハッシュは 4 バイトのプレフィックスです。
EIGHT_BYTES 各ハッシュは 8 バイトのプレフィックスです。
SIXTEEN_BYTES 各ハッシュは 16 バイトのプレフィックスです。
THIRTY_TWO_BYTES 各ハッシュは 32 バイトの完全なハッシュです。

LikelySafeType

安全である可能性が高いサイトの種類。

SearchHashesResponse には意図的に LikelySafeType が含まれていません。

列挙型
LIKELY_SAFE_TYPE_UNSPECIFIED 不明。
GENERAL_BROWSING このサイトは、一般的なブラウジングには十分に安全であると考えられます。これはグローバル キャッシュとも呼ばれます。
CSD このサイトは安全である可能性が高いため、クライアントサイド検出モデルやパスワード保護チェックを実行する必要はありません。
DOWNLOAD このサイトは安全である可能性が高いため、サイトからのダウンロードを確認する必要はありません。

ListHashListsRequest

使用可能なハッシュリストを一覧表示するリクエスト。

フィールド
page_size

int32

返されるハッシュリストの最大数。サービスが返す値はこれよりも少ないことがあります。指定しない場合、サーバーはページサイズを選択します。このページサイズは、ハッシュリストの数よりも大きい場合があり、ページネーションが必要ありません。
page_token

string

前回の ListHashLists 呼び出しから受け取ったページトークン。後続のページを取得するにはこれを指定します。

ListHashListsResponse

ハッシュリストに関するメタデータを含むレスポンス。

フィールド
hash_lists[]

HashList

ハッシュは任意の順序でリストされます。ハッシュリストに関するメタデータのみが含まれ、コンテンツは含まれません。
next_page_token

string

次のページを取得するために page_token として送信できるトークン。このフィールドを省略すると、後続のページはなくなります。

RiceDeltaEncoded128Bit

RiceDeltaEncoded32Bit と同じですが、128 ビットの数値をエンコードします。

フィールド
first_value_hi

uint64

エンコードされたデータの最初のエントリの上位 64 ビット（ハッシュ）。フィールドが空の場合、上位 64 ビットはすべて 0 です。
first_value_lo

fixed64

エンコードされたデータの最初のエントリの下位 64 ビット（ハッシュ）。フィールドが空の場合、下位 64 ビットはすべて 0 になります。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは 99 ～ 126 の範囲内であることが保証されています。
entries_count

int32

エンコードされたデータでデルタ エンコードされるエントリの数。1 つの整数のみがエンコードされている場合、これは 0 になり、その値は first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダを使用してエンコードされたエンコード済みデルタ。

RiceDeltaEncoded256Bit

RiceDeltaEncoded32Bit と同じですが、256 ビットの数値をエンコードします。

フィールド
first_value_first_part

uint64

エンコードされたデータの最初のエントリの最初の 64 ビット（ハッシュ）。フィールドが空の場合、最初の 64 ビットはすべてゼロになります。
first_value_second_part

fixed64

エンコードされたデータの最初のエントリの 65 ～ 128 ビット（ハッシュ）。フィールドが空の場合、65 ～ 128 ビットはすべてゼロになります。
first_value_third_part

fixed64

エンコードされたデータ（ハッシュ）の最初のエントリの 129 ～ 192 ビット。フィールドが空の場合、129 ～ 192 ビットはすべてゼロになります。
first_value_fourth_part

fixed64

エンコードされたデータの最初のエントリの最後の 64 ビット（ハッシュ）。フィールドが空の場合、最後の 64 ビットはすべて 0 になります。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは 227 ～ 254 の範囲内にあることが保証されます。
entries_count

int32

エンコードされたデータでデルタ エンコードされるエントリの数。1 つの整数のみがエンコードされている場合、これは 0 になり、その値は first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダを使用してエンコードされたエンコード済みデルタ。

RiceDeltaEncoded32Bit

Rice-Golomb でエンコードされたデータ。ハッシュまたは削除インデックスに使用されます。ここでは、すべてのハッシュまたはインデックスの長さが同じであることが保証され、この長さは 32 ビットです。

一般に、すべてのエントリを辞書順に並べ替えると、上位ビットは下位ビットほど頻繁に変更されないことがわかります。つまり、エントリ間の隣接する差も取得すると、上位ビットはゼロになる可能性が高くなります。これは、基本的に一定数のビットを選択することで、ゼロの確率が高いことを利用します。これより上位のビットはすべてゼロである可能性が高いため、単一値エンコードを使用します。rice_parameter フィールドを確認します。

歴史的な注記: Rice-delta エンコードは、この API の V4 で初めて使用されました。V5 では、2 つの重要な改善が加えられました。1 つ目は、4 バイトを超えるハッシュ プレフィックスで Rice-delta エンコードを使用できるようになったことです。2 つ目は、コストのかかる並べ替えステップを回避するために、エンコードされたデータがビッグエンディアンとして扱われるようになったことです。

フィールド
first_value

uint32

エンコードされたデータ（ハッシュまたはインデックス）の最初のエントリ。1 つのハッシュ プレフィックスまたはインデックスのみがエンコードされている場合は、そのエントリの値。フィールドが空の場合、エントリはゼロになります。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは 3 ～ 30 の範囲内であることが保証されます。
entries_count

int32

エンコードされたデータでデルタ エンコードされるエントリの数。1 つの整数のみがエンコードされている場合、これは 0 になり、その値は first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダを使用してエンコードされたエンコード済みデルタ。

RiceDeltaEncoded64Bit

RiceDeltaEncoded32Bit と同じですが、64 ビット数をエンコードします。

フィールド
first_value

uint64

エンコードされたデータ（ハッシュ）の最初のエントリ。または、単一のハッシュ接頭辞のみがエンコードされている場合は、そのエントリの値。フィールドが空の場合、エントリはゼロになります。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは 35 ～ 62 の範囲内にあることが保証されます。
entries_count

int32

エンコードされたデータでデルタ エンコードされるエントリの数。1 つの整数のみがエンコードされている場合、これは 0 になり、その値は first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダを使用してエンコードされたエンコード済みデルタ。

SearchHashesRequest

特定のハッシュ プレフィックスを検索するためにクライアントが送信するリクエスト。

これは脅威リストのみを検索するように設計されており、グローバル キャッシュなどの脅威以外のリストは検索しません。

V5 の新機能: クライアントは、ローカル データベースに ClientInfo やハッシュリストの状態を指定する必要がなくなりました。これはプライバシー保護を目的としています。さらに、クライアントは、関心のある脅威の種類を送信する必要はありません。

フィールド
hash_prefixes[]

bytes

必須。検索するハッシュ プレフィックス。クライアントは 1,000 を超えるハッシュ接頭辞を送信してはなりません。ただし、URL 処理手順に従い、クライアントは 30 個を超えるハッシュ接頭辞を送信する必要はありません。

現在、各ハッシュ プレフィックスの長さは 4 バイトである必要があります。今後、この制限が緩和される可能性があります。
filter

string

省略可。クライアントがフィルタリング（特定の種類の脅威のみを取得するなど）を希望する場合は、これを指定できます。省略すると、一致するすべての脅威が返されます。セーフ ブラウジングが提供する最も包括的な保護を実現するには、この設定を省略することを強くおすすめします。

フィルタは Google Common Expression Language を使用して指定します。この言語の一般的な例については、https://github.com/google/cel-spec をご覧ください。次に、ここで使用できる具体的な例を示します。

フィルタ "threat_type == ThreatType.SOCIAL_ENGINEERING" では、FullHashDetail 内の脅威タイプが SOCIAL_ENGINEERING である必要があります。識別子 "threat_type" は、現在の脅威の種類を参照します。識別子 "ThreatType" は、考えられるすべての脅威の種類のコレクションを指します。

フィルタ "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" では、脅威の種類を UNWANTED_SOFTWARE または MALWARE にする必要があります。

SearchHashesResponse

脅威ハッシュの検索後に返されるレスポンス。

何も見つからない場合、サーバーは NOT_FOUND ステータス（HTTP ステータス コード 404）ではなく、full_hashes フィールドが空の OK ステータス（HTTP ステータス コード 200）を返します。

V5 の新機能: FullHash と FullHashDetail が分離されています。ハッシュが複数の脅威（MALWARE と SOCIAL_ENGINEERING の両方など）を含むサイトを表す場合、V4 のように完全なハッシュを 2 回送信する必要はありません。また、キャッシュの有効期間は単一の cache_duration フィールドに簡素化されました。

フィールド
full_hashes[]

FullHash

順序なしリスト。検出された完全なハッシュの順序なしリスト。
cache_duration

Duration

クライアントサイド キャッシュの存続期間。クライアントは、この期間を現在の時刻に加算して有効期限を決定する必要があります。有効期限は、レスポンスで返される完全なハッシュの数に関係なく、リクエストでクライアントがクエリしたすべてのハッシュ プレフィックスに適用されます。サーバーが特定のハッシュ プレフィックスの完全なハッシュを返さない場合でも、この事実もクライアントによってキャッシュに保存する必要があります。

フィールド full_hashes が空の場合に限り、クライアントは cache_duration を増やして、サーバーによって指定された有効期限よりも新しい有効期限を決定できます。いずれの場合も、キャッシュの保存期間を延長しても 24 時間を超えないようにしてください。

重要: サーバーがすべてのレスポンスで同じキャッシュ持続時間を返すと想定することはできません。サーバーは、状況に応じて、レスポンスごとに異なるキャッシュ時間を選択できます。

SizeConstraints

ハッシュリストのサイズに関する制約。

フィールド
max_update_entries

int32

エントリ数の最大サイズ。更新にはこの値を超えるエントリは含まれませんが、この値より少ないエントリが含まれることもあります。この値は 1,024 以上にする必要があります。省略または 0 に設定した場合、更新サイズの上限は設定されません。
max_database_entries

int32

クライアントがリストのローカル データベースに保持するエントリの最大数を設定します。（サーバーは、クライアントがこの数より少ないエントリを保存するようにすることがあります）。省略または 0 に設定した場合、データベースのサイズの上限は設定されません。

ThreatAttribute

脅威の属性。これらの属性は、特定の脅威に追加の意味を与えることができますが、脅威の種類には影響しません。たとえば、ある属性では信頼度が低く、別の属性では信頼度が高い場合があります。今後、さらに多くの属性が追加される可能性があります。

列挙型
THREAT_ATTRIBUTE_UNSPECIFIED 不明な属性。サーバーがこれを返した場合、クライアントは囲んでいる FullHashDetail を完全に無視します。
CANARY 適用に threat_type を使用しないことを示します。
FRAME_ONLY threat_type はフレームへの適用にのみ使用されることを示します。

ThreatType

脅威の種類。

列挙型
THREAT_TYPE_UNSPECIFIED 不明な脅威の種類。サーバーがこれを返した場合、クライアントは囲んでいる FullHashDetail を完全に無視します。
MALWARE

マルウェアの脅威の種類。マルウェアとは、ソフトウェアまたはモバイルアプリであり、特にパソコン、モバイル デバイス、それらで実行されているソフトウェア、パソコンやモバイル デバイスのユーザーに対して有害な影響を与えることを目的として設計されたものを指します。マルウェアは、ユーザーの同意なしにソフトウェアをインストールする、ウイルスなどの有害なソフトウェアをインストールするなど、悪意のある動作を示します。

詳細につきましては、こちらをご覧ください。
SOCIAL_ENGINEERING

ソーシャル エンジニアリングの脅威の種類。ソーシャル エンジニアリング ページは、視聴者を混乱させて、視聴者がその第三者の正当なエージェントだけを信頼するようなアクションを実行させる意図で、第三者の代理として行動していると偽って表示します。フィッシングは、閲覧者をだまして、ログイン認証情報などの情報を提供する特定のアクションを実行させるソーシャル エンジニアリングの一種です。

詳細につきましては、こちらをご覧ください。
UNWANTED_SOFTWARE 望ましくないソフトウェアの脅威の種類。望ましくないソフトウェアとは、Google のソフトウェア原則に準拠していないがマルウェアではないソフトウェアのことです。
POTENTIALLY_HARMFUL_APPLICATION Google Play ストア向けの Google Play プロテクトで使用される、有害な可能性があるアプリの脅威の種類。