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 则会发起一项非主动请求类别的探测。不会修改或注入任何应用 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")

请选择位于 Web 根目录之外的数据库位置。请先创建其父目录并限制其权限。传感器仅保留 /_oo/probe、/_oo/demo 和 /_oo/callback 这三个路径。请确保这些路径不与应用的路由空间重叠。其他所有响应可迭代对象和标头都会原样传递，包括经过编码的响应和流式响应。对外提供服务时，请使用合适的生产级 WSGI 服务器。Python 参考服务器仅用于本地演示，不适用于经过安全加固的生产托管。

通道是固定的运维配置，不会根据主机、地址或标头推断。要比较洋葱服务流量和明网流量，请运行使用不同固定通道的独立监听器。它们可以共用一个数据库。如果需要限制这些端点，请在传感器之外配置您自己的身份验证或访问策略。

可选的 Tor 暴露

请按照官方文档及平台支持的软件包自行安装和配置 Tor。以下是将回环参考监听器映射到 Tor 的 torrc 配置示例：

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

请使用适合您安装方式、由 Tor 管理的私有目录，然后通过 --channel onion 运行监听器。Tor 会配置洋葱主机名。此软件包不管理 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

两种传输方式都会返回 JSON，其中 fixture_id 等于 oo-retrieval-v1，revision 等于 1，且 expected 值为 keyword: moss、number: 42 和 unicode: onion · café · 東京。请比较这些字段，而不要比较完整响应：通知内容可能因请求而异。测试夹具中的纯文本指令是检索测试的数据。请勿执行它，也不要访问其回调 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 故障会向上传递到服务栈；请审慎决定可用性和错误日志处理方式。

研究限制

回调是发生过令牌请求的行为指标。个人、脚本、爬虫、链接跟随器或模型驱动的客户端都可能产生回调。它无法证明模型身份、自主性、指令层级、意图或是否接触过其他内容。响应是带有明确指令的纯文本，不是会自动加载的图像或重定向。令牌仍可能被共享，因此相关性并不能确认行为者的身份。请根据研究情况使用受控基线并进行伦理审查；仅对你获授权的服务进行检测。本软件包不会扫描其他网站或发现 Agent。

测试

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