セキュリティと責任ある利用

Scraping KDL は抽出のための道具である。他者のコンテンツへアクセスする権利や、それを再利用する権利を与えるものではない。個々の利用が許諾されたものか、適切なものかを判断するのは利用者である。このページは運用上の指針であり、法的助言ではない。

規範文書は security-model.md と responsible-use.md である。

仕様は信頼された資産である

KDL ドキュメントは実行可能な設定である。権限には三つの段階がある。

ドキュメントが含むもの	与える権限
HTTP ソース。外部トランスフォームなし	送信先 URL とセレクタを制御する。
ブラウザソース	ページとの操作も制御する。
`evaluate-js` ノード	ページのコンテキスト内で実行されるコードそのものになる。

したがってランタイムは、仕様がアプリケーションの信頼された資産であることを前提にする。信頼できない KDL のための安全なサンドボックスは提供しない。サービスの利用者が書いたドキュメントをコンパイルしてはならない。

ランタイムが備えるもの

JavaScript は既定で無効であり、明示的な opt-in を必要とする。
ケイパビリティの検証は、すべてのネットワーク操作とブラウザ操作より前に完了する。
レスポンスサイズと各操作に上限があり、上限はキャンセルに従う。
URL ポリシーのフックが、最初の対象と各 HTTP リダイレクトを検査する。PublicInternetURLPolicy と NewPublicInternetHTTPClient は公開インターネット向けに用意されており、Go CLI は既定でこれらを適用する。
JavaScript の結果が JSON 互換かどうかを検証する。
正規表現は RE2 を使い、実行時間は入力長に対して線形である。
アダプタは抽出全体にわたるリースを保持できる。これにより、二つの抽出の操作が一つのページ上で交錯しない。
構造化されたエラーコードにセッションの値は含まれない。

TypeScript の HTTP ランタイムも同じ順序を持つ。プログラム、セレクタ、入力、セッション、ケイパビリティ、外部トランスフォームの事前検査は、fetch を呼ぶ前に完了する。リダイレクトは自前で処理するため、リダイレクト後のリクエストの前にも URL ポリシーが実行される。オリジンをまたぐ際には認証ヘッダとホスト限定のクッキーヘッダを除去し、ストリームされたボディはデコードの前に上限を適用する。

利用者が備えるもの

ランタイムは層の一つである。ホスト側には次のものが必要になる。

送信先のアローリスト、または隔離されたネットワーク
リクエストとブラウザのタイムアウト
レスポンスサイズの上限
低権限のブラウザプロセスと、テナントごとに分離されたコンテキスト
ログ中の秘密情報の秘匿
JavaScript または外部トランスフォームを有効にする前の明示的なレビュー

注入されたソースローダは、利用者にとっての権限境界である。ローダは import の字句的に解決されたパスを受け取る。そのパスを意図したソースの集合に限定し、キャンセルに従い、ソースの内容や資格情報をエラーに含めないこと。コンパイラがローダにファイルシステム、ネットワーク、サブプロセスへのアクセスを与えることはない。

CompileFS と ValidateFS は、ルートと import 名を io/fs のパスに限定し、親への字句的な脱出を拒否する。それでも真の権限を決めるのは、渡された fs.FS である。 os.DirFS はディレクトリ外へのシンボリックリンクをたどり得る。封じ込めが必要なら os.Root.FS を使う。

秘密情報

CLI がヘッダとクッキーを受け取るのは、--session-file FILE または --session-file - からだけである。秘密情報を直接運ぶフラグは拒否する。コマンド引数はシェルの履歴に残り得るし、プロセス一覧から見え得るからである。

{
  "headers": {"Authorization": ["Bearer example"]},
  "cookies": [{"name": "session", "value": "example"}]
}

このファイルは、意図した利用者だけが読める権限にする。削除や更新は、秘密情報の管理方針に従って行う。

session policy="none" が止めるのは明示的なセッションだけである。利用者の http.Client のクッキージャーや、既存のブラウザコンテキストの状態は消去しない。資格情報を持たない実行が必要なら、隔離されたクライアントか隔離されたコンテキストを渡すこと。

有効な資格情報、セッションクッキー、認証ヘッダ、抽出した非公開のコンテンツを、issue、ログ、フィクスチャ、サンプルに残してはならない。

実サービスを対象にする前に

サービスを対象にする前に、次を行う。

現行の利用規約と自動化に関する方針を読む。
robots.txt の指示を確認する。
サービスまたは適用される規則が求める場合は許諾を得る。
文書化された API がそのデータを得る正式な手段であるなら、それを使う。

Robots Exclusion Protocol は、サイトの所有者が意向を表明するための標準的な手段を与える。 robots.txt 上の許可は、許諾を与えるものではなく、サイトの規約に優先するものでもなく、その利用が適法かどうかを決めるものでもない。

負荷を抑える

スケジュール、並列度、再試行、キャッシュを制御するのは呼び出し側のアプリケーションである。次を満たす必要がある。

リクエストを間隔をあけて送り、適切な場合は遅延に揺らぎを加える
並列度を、対象が受け入れる範囲に保つ
レスポンスをキャッシュし、変わっていない同じ内容を取得し直さない
ステータス 429 や 503、タイムアウト、その他の過負荷の兆候のあとは、停止するか待つ
ブラウザセッション、レスポンスサイズ、再試行、総実行時間に上限を設ける

Scraping KDL に全体的なレートリミッタはない。それがないことは、無制限に通信してよいという意味ではない。

クライアントを名乗る

自動化が許諾されている場合は、自分のクライアントを識別できる User-Agent を設定する。適切であれば、連絡先やプロジェクトの URL も添える。対象の方針を回避するために、別のクローラやブラウザを装ってはならない。二つの CLI は --user-agent オプションを持ち、ライブラリのホストも同等のオプションを設定できる。

抽出したコンテンツ

アプリケーションが必要とするデータだけを集める。コンテンツを保持または配布する前に、著作権、データベースの権利、プライバシー、秘密保持、契約上の制限、保持期間、アクセス制御、安全な削除を確認する。

要件は法域ごとに異なる。日本の利用者は、現行の著作権法と個人情報の保護に関する法律、そして適用される他の規則を読み、必要な場合は専門家の助言を得ること。

回避手段を扱わない

このプロジェクトは、CAPTCHA、アクセス制御、ペイウォール、レート制限、ボット検出、アカウントの制限を回避することを目的とした機能を提供せず、受け入れもしない。クレデンシャルスタッフィング、偽のブラウザフィンガープリント、方針違反を隠すステルス自動化も同様である。

セキュリティ研究と相互運用性のための作業は、テストの許諾を得たシステム上で行うこと。

次に読むもの

HTTP 実行：URL ポリシーと各種上限。
パターン：間隔制御と再試行を自分のコードのどこに置くか。