Yarix

由原生 YARA 规则、Anti-Spam、Honeypot 和 OCR 驱动的 Discord 审核。

## 概述 - [功能](#features) - [环境要求](#requirements) - [安装说明](#installation) - [配置说明](#configuration) - [Discord 设置](#discord-setup) - [规则模式](#rule-modes) - [OCR 流程](#ocr-flow) - [Honeypot](#honeypot) - [项目结构](#project-structure) - [开发指南](#development) - [故障排除](#troubleshooting) - [安全指南](#security-guide) ## 功能 - 基于原生 YARA 的消息检测 - 针对操作和审核阶段的逐规则配置 - 用于检测重复相同消息行为的 Anti-Spam 门控机制 - 针对重复图片活动的、由 OCR 支持的高级分析 - 具备 timeout、ban 或 quarantine 功能的 Honeypot 诱捕频道 - 豁免角色 - 成员审核概览 - quarantine 解除命令 - 基于Components V2 的审核面板和 embeds - 带有 schema 引导和迁移的 SQLite 数据库 - 可读或结构化的运行时日志 ## 环境要求 支持的平台： - Windows - Linux，包括 Debian 和 Ubuntu Python： - Python `3.11` 或更高版本 主要依赖项： - `discord.py` - `yara-python` - `rapidocr-onnxruntime` - `Pillow` - `aiosqlite` - `structlog` - `pydantic` - `pydantic-settings` - `python-dotenv` 可选开发工具： - `pytest` - `pytest-asyncio` - `ruff` ## 安装说明 ### 1. 创建虚拟环境 Windows PowerShell： ``` py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 ``` Linux： ``` python3.12 -m venv .venv source .venv/bin/activate ``` 如果 `3.12` 不可用，只要您安装的 Python 版本为 `3.11+` 即可使用。 ### 2. 安装 Yarix ``` python -m pip install --upgrade pip python -m pip install -e . ``` 安装开发工具： ``` python -m pip install -e .[dev] ``` ### 3. 准备配置 将 `.env.example` 复制到 `.env`。 必需项： ``` YARIX_DISCORD_TOKEN=your_bot_token ``` 推荐测试项： ``` YARIX_COMMAND_GUILD_ID=your_test_server_id ``` ### 4. 启动机器人 ``` python -m yarix ``` 预期的启动过程会包含类似这样的一行： ``` Connected to Discord as Yarix#8123 (application_id=...) ``` ## 配置说明 Yarix 从 `.env` 读取运行时配置。 核心键值： ``` YARIX_DISCORD_TOKEN= YARIX_APPLICATION_ID= YARIX_COMMAND_GUILD_ID= YARIX_DATABASE_PATH=data/yarix.sqlite3 YARIX_RUNTIME_LOG_PATH=data/logs/yarix.log YARIX_LOG_LEVEL=INFO YARIX_MODERATION_CONSOLE_LOG_MODE=complex ``` ### 日志 ``` YARIX_LOG_LEVEL=INFO YARIX_MODERATION_CONSOLE_LOG_MODE=complex YARIX_RUNTIME_LOG_PATH=data/logs/yarix.log ``` `YARIX_LOG_LEVEL` 控制常规应用程序日志记录。 可用值： - `INFO` - `WARNING` - `ERROR` `YARIX_MODERATION_CONSOLE_LOG_MODE` 控制审核流程的控制台输出。 可用值： - `off` - `simple` - `complex` `simple` 通常是日常使用的最佳选择。 `simple` 输出示例： ``` [01:53:11.409 28.06.2026] Queue: OCR job queued (1 waiting) [01:53:11.409 28.06.2026] Dispatcher: selected worker 0 (1 queued) [01:53:11.409 28.06.2026] Worker 0: accepted queued OCR job [01:53:11.637 28.06.2026] Worker 0: started OCR for 4 grouped messages ``` `YARIX_COMMAND_GUILD_ID` 仅在开发或受控部署期间作为 slash commands 的快速同步目标。它不控制审核范围或 OCR 容量。 ### 检测模式和受支持的文件 ``` YARIX_URL_DETECTION_PATTERN=https?:// YARIX_INVITE_DETECTION_PATTERN=(?:https?://)?(?:www\.)?(?:discord\.gg|discord(?:app)?\.com/invite)/[A-Za-z0-9-]+ YARIX_SUPPORTED_IMAGE_MIME_PREFIXES=image/ YARIX_SUPPORTED_IMAGE_EXTENSIONS=.png,.jpg,.jpeg,.gif,.webp,.bmp YARIX_SUPPORTED_VIDEO_EXTENSIONS=.mp4,.mov,.webm,.avi,.mkv YARIX_SUPPORTED_ARCHIVE_EXTENSIONS=.zip,.rar,.7z,.tar,.gz ``` ### OCR worker 和后端限制 ``` YARIX_OCR_GLOBAL_MAX_WORKERS=2 YARIX_OCR_PER_GUILD_MAX_WORKERS=1 YARIX_OCR_MAX_ATTACHMENT_TIMEOUTS_PER_JOB=1 YARIX_OCR_INTRA_OP_THREADS=2 YARIX_OCR_INTER_OP_THREADS=1 ``` 含义： - `YARIX_OCR_GLOBAL_MAX_WORKERS` 整个 bot 进程的总 OCR 任务并发数 - `YARIX_OCR_PER_GUILD_MAX_WORKERS` 单个 Discord guild 的 OCR 并发上限 - `YARIX_OCR_MAX_ATTACHMENT_TIMEOUTS_PER_JOB` 在达到这么多次单附件超时后，中止该 OCR cluster - `YARIX_OCR_INTRA_OP_THREADS` 单个 OCR runtime 可用于单次操作的 CPU 量 - `YARIX_OCR_INTER_OP_THREADS` 单个 OCR runtime 可使用的内部 OCR 并行度 推荐的 CPU OCR 起始配置： ``` YARIX_OCR_GLOBAL_MAX_WORKERS=2 YARIX_OCR_PER_GUILD_MAX_WORKERS=1 YARIX_OCR_MAX_ATTACHMENT_TIMEOUTS_PER_JOB=1 YARIX_OCR_INTRA_OP_THREADS=2 YARIX_OCR_INTER_OP_THREADS=1 ``` 调优指南： - 除非基准测试另有证明，否则保持 `INTER=1` - 在提高 `INTER` 之前先提高 `INTRA` - 在假定 OCR 需要更多并行度之前，先减少 worker 数量 ### Emoji 配置 Yarix 通过 `.env` 支持自定义 emoji 引用。 ``` YARIX_EMOJI_PIN=<:pin:...> YARIX_EMOJI_TIMEOUT=<:timeout:...> YARIX_EMOJI_TRASH=<:trash:...> YARIX_EMOJI_LIST=<:list:...> YARIX_EMOJI_INFO=<:info:...> YARIX_EMOJI_BAN=<:ban:...> YARIX_EMOJI_SETTINGS=<:settings:...> YARIX_EMOJI_ALERT=<:alert:...> YARIX_EMOJI_HONEY=<:honey:...> ``` 如果未配置自定义 emoji，Yarix 将回退到 `config.py` 中的默认值。 ## 首次启动行为 首次运行时，Yarix 将： - 如果 SQLite 数据库不存在，则创建它 - 创建缺失的表 - 运行迁移 - 同步 slash commands 您无需手动创建数据库。 ## Discord 设置 推荐的首次运行流程： 1. 打开 `/automod panel` 2. 配置日志频道 3. 如果需要，配置豁免角色 4. 如果需要诱捕频道审核，配置 Honeypot 5. 打开 `/rules panel` 6. 导入您的 YARA 规则 7. 配置或确认每个规则的模式和操作 主要命令： - `/automod panel` - `/rules panel` - `/rules import-file` - `/view` - `/quarantine-lift` ### OAuth scopes 生成邀请 URL 时请使用这些 scope： - `bot` - `applications.commands` ### Bot 权限 推荐的基础权限： - `View Channels` - `Send Messages` - `Embed Links` - `Attach Files` - `Read Message History` - `Manage Messages` 使用特定功能时所需： - `Moderate Members` 规则、Anti-Spam 和 Honeypot 执行 timeout 所需。 - `Ban Members` 如果 Honeypot 或某个规则需要 ban 用户时所需。 - `Manage Roles` 分配 quarantine 角色、创建 quarantine 角色以及解除 quarantine 所需。 - `Mention Everyone` 非必需。保持禁用。 - `Administrator` 非必需。除非您有意授予完全信任，否则请勿授予此权限。 实用建议： - 将 Yarix 的角色置于它可以 timeout 或分配 quarantine 的角色之上。 - 如果您使用托管的 quarantine 角色，也请将 Yarix 置于该角色之上。 - 如果日志或 Honeypot 操作不起作用，请首先检查频道覆盖权限和角色层级。 ## 规则模式 ### Immediate 匹配消息并立即采取行动。 ### Anti-Spam 仅在检测到重复的相同消息行为后才采取行动。 ### Advanced Signal 不直接进行处罚。它为可疑的重复图片活动贡献 OCR 风险。 ### Advanced Detect 在高级分析已经开始后，基于 OCR 输出运行。 ## OCR 流程 Yarix 的 OCR pipeline 工作原理如下： 1. 首先运行常规消息处理 2. Immediate 规则可能会立即采取行动 3. Anti-Spam 可能会在检测到重复相同消息行为时触发 4. Advanced signal 规则会增加可疑重复图片活动的风险 5. 成熟的可疑候选对象会根据基于内容的候选键被分组到 OCR 任务中 6. OCR 任务被放入 guild OCR 队列 7. 分配器将排队的任务分配给空闲的 worker 插槽 8. OCR 扫描该任务内受支持的图像 9. OCR 文本被送入 advanced-detect YARA 规则 10. 匹配的 OCR-detect 规则应用操作 重要注意事项： - OCR 使用 `rapidocr-onnxruntime` - OCR 超时通过 Discord AutoMod 面板配置 - worker 和后端线程限制来自 `.env` - 一个 OCR 任务按顺序扫描其自身的图像 - 来自同一用户的不同可疑图像集将成为独立的 OCR 任务 - 相同的可疑内容被分组到一个 OCR 任务中 - 如果某个 cluster 达到了配置的附件超时限制，Yarix 将中止该 cluster 的其余部分 ### OCR 调优 推荐的调优顺序： 1. 保持保守的 worker 数量 2. 如果较重的图像确实太慢，则增加 OCR 超时时间 3. 如果单个 OCR worker 需要更多 CPU，则增加 `INTRA` 4. 仅在已知稳定路径后才对 `INTER > 1` 进行基准测试 ## Honeypot Honeypot 系统是一个诱捕频道。 当用户在配置的 Honeypot 频道中发帖时，Yarix 可以： - 删除 Honeypot 消息 - 删除同一用户在其他频道中的匹配消息 - 应用配置的处罚 - 如果可能，发送 DM 通知 - 记录事件 可用的 Honeypot 操作： - timeout - ban - quarantine 角色 如果使用 `quarantine`，Yarix 可以： - 使用现有角色 - 创建托管的 quarantine 角色 - 为被 quarantine 的用户保留一个可见的申诉频道 ## 数据库 默认数据库路径： ``` data/yarix.sqlite3 ``` 相关文件： - [src/yarix/db/schema.sql](src/yarix/db/schema.sql) - [src/yarix/db/migrations.py](src/yarix/db/migrations.py) - [src/yarix/db/repository.py](src/yarix/db/repository.py) ## 运行时日志 Yarix 写入： - 将常规应用程序输出写入控制台 - 将运行时控制台输出写入配置的日志文件路径 默认运行时日志文件： ``` data/logs/yarix.log ``` ## 项目结构 重要文件和文件夹： - [src/yarix/bot.py](src/yarix/bot.py) - bot 启动和 Discord 事件流程 - [src/yarix/cogs/admin.py](src/yarix/cogs/admin.py) - 面板和 slash commands - [src/yarix/moderation.py](src/yarix/moderation.py) - 审核 pipeline 和操作流程 - [src/yarix/components_v2.py](src/yarix/components_v2.py) - Components V2 布局 - [src/yarix/ocr_engine.py](src/yarix/ocr_engine.py) - OCR 封装 - [src/yarix/pipeline.py](src/yarix/pipeline.py) - 附件分析 pipeline - [src/yarix/yara_engine.py](src/yarix/yara_engine.py) - YARA 验证和匹配 - [examples](examples) - 示例资源、图像和捆绑的规则引用 ## 开发指南 运行测试： ``` pytest ``` 使用 Ruff 进行 Lint： ``` ruff check . ``` ## 最简设置检查清单 1. 安装 Python `3.11+` 2. 创建并激活 `.venv` 3. 运行 `python -m pip install -e .` 4. 将 `.env.example` 复制到 `.env` 5. 设置 `YARIX_DISCORD_TOKEN` 6. 使用 `python -m yarix` 启动 bot 7. 打开 `/automod panel` 8. 设置日志频道 9. 打开 `/rules import-file` 或 `/rules panel` 10. 导入并配置您的规则 ## 故障排除 ### `python -m yarix` 提示 `No module named yarix` 项目未安装到活动的虚拟环境中。 运行： ``` python -m pip install -e . ``` ### OCR 超时 配置的 OCR 超时时间对于机器或图像批次来说太短。 从高级分析面板增加 OCR 超时时间，然后重试。 ### 命令未出现 请确保： - bot 正在运行 - slash commands 在启动时成功同步 - `YARIX_COMMAND_GUILD_ID` 已正确设置为测试 guild 同步 ### 数据库不存在 这在全新安装时是正常的。Yarix 会在首次启动时自动创建它。 ## 安全指南 有关 Yarix 特定的 YARA 规则设计、受支持的外部变量、import 预设和规则编写指南，请参阅 [SECURITY.md](SECURITY.md)。

标签：Discord机器人, DNS信息、DNS暴力破解, OCR图文识别, Python, SQLite, YARA规则, 内容审核, 反垃圾, 无后门, 逆向工具