ar-io/ar-io-content-scanner

# ar.io 内容扫描器 一个为 [ar.io 网关](https://github.com/ar-io/ar-io-node) 准备的内容审核 Sidecar。检测并自动拦截托管在 Arweave 上的钓鱼 HTML 内容，保持网关清洁，并避免被 Netcraft 和 Google Safe Browsing 等黑名单收录。 ## 工作原理 ``` ar-io-node Content Scanner ---------- --------------- User request ──> Cache miss ──> Fetch from Arweave | Cache write | DATA_CACHED ──────────────────> POST /scan | | Serve content Enqueue scan (no delay) | Worker picks up | GET /raw/:id ──> Fetch HTML | Parse HTML Run 4 rules + ML | ┌── malicious? ──┐ | | yes no | | PUT block-data Cache clean | Future requests ──> 404 ``` **权衡：** 第一个访问恶意内容的用户会看到该内容。所有后续请求都会被拦截。这是可以接受的，因为钓鱼页面需要重复受害者，而在首次访问后进行拦截可以消除攻击面。 ## 快速开始 ### 1. 网关配置 添加到您的 ar-io-node `.env` 中： ``` WEBHOOK_TARGET_SERVERS=http://content-scanner:3100/scan WEBHOOK_EMIT_DATA_CACHED_EVENTS=true ``` 如果您的网关启用了 `ENABLE_RATE_LIMITER=true`，请将 Docker 网络加入允许列表： ``` RATE_LIMITER_IPS_AND_CIDRS_ALLOWLIST=172.17.0.0/16 ``` 需要带有 `DATA_CACHED` Webhook 事件支持的 ar-io-node。 ### 2. 运行扫描器 克隆此仓库，将 `.env.example` 复制为 `.env`，并设置您的 `ADMIN_API_KEY`： ``` cp .env.example .env # 编辑 .env — 设置 ADMIN_API_KEY 以匹配您的 gateway key docker compose up -d ``` 包含的 `docker-compose.yml` 会自动加入 ar-io-node 的 `ar-io-network`。 ### 3. 观察，然后执行 以 `SCANNER_MODE=dry-run`（默认值）开始，观察日志中的检测结果而不进行拦截。当对准确性满意时，在 `.env` 中设置 `SCANNER_MODE=enforce` 并重启。 ## 检测引擎 ### 第一层规则 (自动拦截) 每条规则需要 2 个以上独立信号（合取逻辑），以确保近乎零的误报。 | 规则 | 信号 A | 信号 B | |------|----------|----------| | **助记词窃取** | 8+ 个文本输入框 | 可见文本中包含助记词术语 | | **外部凭证表单** | 密码输入框 | 表单 action 为绝对 URL，或带有外部 URL 的 JS 窃取模式 | | **钱包冒充** | 标题/标题/图片 alt 中包含加密品牌 | 密码输入框 | | **混淆加载器** | DOM 注入 + 脚本中的编码函数 | 长 base64、十六进制转义或 charcode 链 | ### ML 模型 (参考性) 一个在钓鱼与合法 HTML 上训练的 XGBoost 分类器提供辅助信号。ML 模型可以将 CLEAN（清洁）判定升级为 SUSPICIOUS（可疑，记录以供审查），但**其本身永远不会触发自动拦截**。 ``` Rule verdict ML score Final verdict ----------- -------- ------------- MALICIOUS any MALICIOUS (auto-block in enforce mode) CLEAN >= 0.95 SUSPICIOUS (log only) CLEAN < 0.95 CLEAN ``` ### 为什么这不会误伤合法 DApps Arweave 内容是静态的——没有服务器端后端。发布到外部 URL 的密码表单没有合法的用例。真正的 Arweave dApps 通过钱包签名（`window.ethereum.request()`）进行身份验证，而不是 HTML 密码表单。合取规则利用了这一 Arweave 特有的上下文。 ## 配置 | 变量 | 必需 | 默认值 | 描述 | |----------|----------|---------|-------------| | `GATEWAY_URL` | 是 | -- | ar-io-node 内部 URL (例如 `http://core:4000`) | | `ADMIN_API_KEY` | 是 | -- | 必须与网关的 `ADMIN_API_KEY` 匹配 | | `SCANNER_MODE` | 否 | `dry-run` | `dry-run` (仅记录) 或 `enforce` (自动拦截) | | `SCANNER_PORT` | 否 | `3100` | HTTP 服务器端口 | | `SCANNER_WORKERS` | 否 | `2` | 并发扫描 Worker 数量 | | `ML_MODEL_ENABLED` | 否 | `true` | 启用 XGBoost ML 评分 | | `LOG_LEVEL` | 否 | `info` | 日志级别 (debug, info, warning, error) | | `MAX_SCAN_BYTES` | 否 | `262144` | 最大扫描 HTML 字节数 (256KB) | | `SCAN_TIMEOUT` | 否 | `10000` | 网关获取超时（毫秒） | | `DB_PATH` | 否 | `/app/data/scanner.db` | SQLite 数据库路径 | | `RULE_SEED_PHRASE` | 否 | `true` | 启用助记词窃取规则 | | `RULE_EXTERNAL_CREDENTIAL_FORM` | 否 | `true` | 启用外部凭证表单规则 | | `RULE_WALLET_IMPERSONATION` | 否 | `true` | 启用钱包冒充规则 | | `RULE_OBFUSCATED_LOADER` | 否 | `true` | 启用混淆加载器规则 | | `BACKFILL_ENABLED` | 否 | `false` | 启用对缓存内容的主动文件系统扫描 | | `BACKFILL_DATA_PATH` | 否 | -- | 网关的连续数据目录（如果启用回填则为必需） | | `BACKFILL_GATEWAY_DB_PATH` | 否 | -- | 网关的 `data.db` 路径（只读，用于哈希→TX ID 查找） | | `BACKFILL_RATE` | 否 | `5` | 回填期间每秒扫描的最大文件数 | | `BACKFILL_INTERVAL_HOURS` | 否 | `24` | 回填扫描间隔小时数（0 = 一次性） | ## HTTP 端点 | 端点 | 方法 | 描述 | |----------|--------|-------------| | `/scan` | POST | 接收 `DATA_CACHED` Webhook 事件 (返回 202) | | `/health` | GET | 健康检查 (模式, 版本) | | `/metrics` | GET | 扫描统计 (判定, 缓存命中, 拦截, 队列深度) | ## Docker 镜像 预构建镜像在每次推送到 `main` 和版本标签时发布到 GHCR。 ``` # 拉取最新 image docker pull ghcr.io/ar-io/ar-io-content-scanner:main # 或固定到特定版本 docker pull ghcr.io/ar-io/ar-io-content-scanner:0.1.0 ``` ### CI/CD GitHub Actions 工作流 (`.github/workflows/build-and-push.yml`) 运行测试，然后自动构建并推送： | 触发条件 | 镜像标签 | |---------|------------| | 推送到 `main` | `:main`, `:sha-` | | 标签 `v1.0.0` | `:1.0.0`, `:1.0`, `:sha-` | | Pull request | 仅测试，不推送镜像 | ### 创建发布 ``` git tag v0.1.0 git push origin v0.1.0 ``` 这将发布操作员可以固定使用的版本化镜像。 ## 开发 ``` # 安装 dependencies pip install -r requirements.txt -r requirements-dev.txt # 运行 tests python3 -m pytest tests/ -v # 本地构建 Docker image docker build -t content-scanner . # 本地运行 GATEWAY_URL=http://localhost:3000 ADMIN_API_KEY=secret python3 -m src.server ```

标签：Apex, Arweave, HTML 分析, Naabu, Sidecar 模式, TCP/UDP协议, Web3 安全, 云计算, 内容安全, 内容审核, 内容扫描, 区块链内容监管, 去中心化存储, 反钓鱼, 威胁情报, 开发者工具, 恶意检测, 机器学习, 漏洞缓解, 缓存安全, 网关安全, 网络安全, 自动拦截, 规则引擎, 请求拦截, 逆向工具, 钓鱼防护, 隐私保护