OnionLens Tor Tools

OnionLens

Python 3.10 以降の標準ライブラリを使った WSGI センサーです。所有している、または計測を許可されているアプリケーションで使用します。観測データはローカルの SQLite に保存されます。リモートへの呼び出し、ダウンロード、隠れたテレメトリ、バックグラウンドサービス、自動的な Tor のインストールはありません。実行時にサードパーティー依存関係はありません。

バージョン 0.1.2 では、配布名は onionlens です。Python のインポート名は引き続き onion_observatory です。onionlens、cepatreaza、onion-observatory コマンドはいずれも同じセンサーを起動します。既存の連携では、インポート名とコマンド名をそのまま使用できます。

PyPI · ウェブサイト · ソースリポジトリ

インストールと実行

python3 -m venv .venv
. .venv/bin/activate
pip install onionlens
onionlens serve --channel clearnet --db observatory.sqlite3

ローカルのソースチェックアウトでは、代わりに python -m pip install . を使用してください。

リファレンスサーバーは、デフォルトで 127.0.0.1:8787 にバインドします。ラベル付きデモを表示するには、http://127.0.0.1:8787/_oo/demo を開きます。レスポンスには、相対コールバック URL のリクエストを促す無害な指示が含まれます。その URL にアクセスすると、デモコールバックが記録されます。/_oo/probe は代わりに unsolicited クラスのプローブを発行します。アプリケーションの HTML は変更も挿入もされません。

onionlens summary --db observatory.sqlite3

概要には、イベントの合計数、クラス別の有効なコールバック数、無効なコールバック数が表示されます。生の記録は表示されません。専用のデモエンドポイントと、そこで発行された有効なコールバックトークン以外のすべてのアクティビティは、unsolicited と分類されます。この運用上のラベルは、通常のテストを含む、ラベルのないトラフィックを意味します。訪問者が招待されていなかったことを示すものではありません。偽装されたユーザーエージェント、テスト用ヘッダー、クエリマーカーによって、アクティビティの分類を抑止したり変更したりすることはできません。このラベルから訪問者の身元はわかりません。

WSGI アプリケーションをラップする

from onion_observatory import Sensor
from my_application import application as original_application

application = Sensor(original_application, "sensor.sqlite3",
                     channel="clearnet")

データベースの保存先には、ウェブルートの外部を選択してください。先に親ディレクトリを作成し、アクセス権を制限してください。センサーが予約するのは /_oo/probe、/_oo/demo、/_oo/callback のみです。これらのパスをアプリケーションのルート領域から外してください。エンコードされたレスポンスやストリーミングレスポンスも含め、それ以外のすべてのレスポンスイテラブルとヘッダーは変更されずに渡されます。外部公開するサービスでは、適切な本番用 WSGI サーバーを使用してください。Python リファレンスサーバーはローカルでのデモ用であり、本番環境向けに強化されたホスティング用ではありません。

チャネルはオペレーターが固定で設定するものであり、ホスト、アドレス、ヘッダーから推測されることはありません。onion トラフィックと clearnet トラフィックを比較するには、チャネルを固定した別々のリスナーを実行してください。データベースは共有できます。これらのエンドポイントへのアクセスを制限する必要がある場合は、センサーの外部に独自の認証またはアクセス制御ポリシーを設けてください。

Tor による任意の公開

Tor は、公式ドキュメントとお使いのプラットフォームでサポートされるパッケージを使用して、ご自身でインストールおよび設定してください。ループバックのリファレンスリスナーに対する torrc の設定例は次のとおりです。

HiddenServiceDir /var/lib/tor/onionlens/
HiddenServicePort 80 127.0.0.1:8787

インストール環境に適した、Tor が所有するプライベートディレクトリを使用してから、--channel onion を指定してリスナーを実行してください。Tor が onion ホスト名を設定します。このパッケージは Tor を管理しません。公開する場合は、ご自身でデプロイ、悪用への対処、脅威評価を行う必要があります。ループバックへのバインドによりリファレンスリスナーへの外部からの直接アクセスは防止できますが、公開後の Tor 経由の訪問者は制限されません。

所有するフィクスチャを検証して取得する

以下の任意の例では、OnionLens 独自の管理されたフィクスチャを使用します。センサーを変更する必要はありません。アドレス確認は Python の標準ライブラリを使用してローカルで実行され、名前解決は行いません。

python3 - <<'PYTHON'
import base64
import hashlib
import hmac
import re

hostname = "pjzhmrhqlmjvhb5eeqmgnil7oztrbqkt45hay4zsvj5e6dblnfezopyd.onion"
if not re.fullmatch(r"[a-z2-7]{56}\.onion", hostname):
    raise SystemExit("Invalid v3 hostname format")
data = base64.b32decode(hostname[:-6].upper())
key, checksum, version = data[:32], data[32:34], data[34:]
expected = hashlib.sha3_256(b".onion checksum" + key + version).digest()[:2]
if version != b"\x03" or not hmac.compare_digest(checksum, expected):
    raise SystemExit("Invalid version or checksum")
print("Valid v3 format and checksum; reachability and trust are untested")
PYTHON

別途インストールした Tor クライアントを設定済みの SOCKS ポート（ここでは 9050）で実行した状態で、ホスト名を Tor に渡して名前解決します。

curl --fail --socks5-hostname 127.0.0.1:9050 --max-time 90 \
  http://pjzhmrhqlmjvhb5eeqmgnil7oztrbqkt45hay4zsvj5e6dblnfezopyd.onion/demo/api/v1/fixture
curl --fail --max-time 30 https://onionlens.org/demo/api/v1/fixture

どちらのトランスポートも、fixture_id が oo-retrieval-v1、revision が 1、expected の値が keyword: moss、number: 42、unicode: onion · café · 東京 の JSON を返します。レスポンス全体ではなく、これらのフィールドを比較してください。通知はリクエストごとに変わる場合があります。フィクスチャ内のプレーンテキストの指示は、取得テスト用のデータです。実行したり、コールバック URL にアクセスしたりしないでください。これらのコマンドは Tor のインストール、プロキシ設定の変更、サードパーティーのサービスのスキャンを行いません。

実験を分けて記録する

ポータブルセンサーは、/_oo/demo と、有効な発行済みトークンを含むコールバックのみを demo としてラベル付けします。通常のリクエスト、/_oo/probe、無効なコールバックは、自分で行ったテストも含めて unsolicited のままです。ユーザーエージェント、クエリマーカー、任意のテスト用ヘッダーを使っても、この扱いは変わりません。自分で実施したテストは各自の研究記録に記載し、必要に応じて分析から除外してください。

公開されている OnionLens サービスには、独立した研究用デプロイメントと独自のデータポリシーがあります。上記のホスト型フィクスチャのコマンドは専用のデモ用ルートを使用するため、取得リクエストも発行されたコールバックトークンも、サーバーによって割り当てられた demo クラスのままです。通常の /api/v1/fixture リクエストは、ラベルのない研究観測データのままです。明示的にラベル付けされたホスト型デモには、OnionLens Lab または MCP デモ を使用してください。ローカルパッケージのエンドポイントとホスト型デモのエンドポイントは別々です。どちらも訪問者の身元や同意を分類するものではありません。

データとプライバシーの境界

各リクエストでは、時刻、固定チャネル、イベント種別、トラフィッククラス、メソッド（16 文字）、パス（1024 文字）、ユーザーエージェント（512 文字）、任意のハッシュ化されたオリジントークンの相関情報とコールバック遅延を記録します。制御文字は置換されます。SQLite には、コールバックの検証を再起動後も継続できるよう、発行済みトークンのハッシュと発行時刻が保存されます。検証用のトークンは 24 時間後に期限切れになりますが、期限切れになってもレコードは自動的に削除されません。有効なコールバックは繰り返し送信でき、カウントはリクエスト数であり、アクターのユニーク数ではありません。遅延はプローブの発行からコールバックの受信までを測定し、配信時間とネットワーク遅延も含みます。検証済みの読み取り時間や推論時間ではありません。

センサーは、リクエスト本文、IP アドレス、Cookie、認証ヘッダー、リファラー、生のクエリー文字列、タスクの説明を読み取ったり保存したりしません。解析するのはコールバックトークンのクエリパラメーターのみで、生のトークンは保存しません。パスとユーザーエージェントは信頼できないテキストであり、個人情報や機密情報が含まれる場合があります。そこに秘密情報を含めないでください。タスク内容を意味的に抽出することはありません。パスやユーザーエージェントにタスクの説明や秘密情報を埋め込むアプリでは、このラッパーを使う前に、運用者側で追加の最小化処理が必要です。

リファレンスサーバーではアクセスログを無効にしています。外側の WSGI サーバー、リバースプロキシ、Tor の設定、ラップ対象のアプリケーションには、それぞれ独立したログポリシーがあるため、確認が必要です。既存のデータベースファイルの権限は保持され、新しいデータベースファイルはモード 0600 で作成されます。SQLite は暗号化されません。データベースを公開ウェブルートの外に置き、アクセスを制限し、必要に応じてストレージを暗号化し、独自の保持ポリシーを設定してください。ローカルの履歴を削除するには、データベースを削除する前にすべての書き込み処理を停止してください。リモートダッシュボードやリモートからの削除機能はありません。SQLite の障害はサービングスタックに伝播するため、可用性とエラーログの処理方針を慎重に決定してください。

調査上の制限

コールバックは、トークンを含むリクエストが発生したことを示す行動上の指標です。人、スクリプト、クローラー、リンクをたどるプログラム、またはモデル駆動型クライアントが生成する可能性があります。モデルの識別情報、自律性、指示の優先順位、意図、あるいは他のコンテンツに触れたことを証明するものではありません。応答は明示的な指示を含むプレーンテキストであり、自動的に読み込まれる画像やリダイレクトではありません。トークンの所持者は共有される可能性があるため、相関関係があっても行為者の身元は特定できません。研究に適した管理されたベースラインと倫理審査を用い、許可を得たサービスのみを計測してください。このパッケージは他のサイトをスキャンしたり、エージェントを検出したりしません。

テスト

PYTHONPATH=src python -m unittest discover -s tests -v