ascarola/verdictmail

# VerdictMail    AI驱动的邮件威胁分析守护进程。通过IMAP IDLE监控收件箱，并对每封收到的邮件进行多阶段富化和AI分析管道处理——自动放行、标记或移动可疑邮件到垃圾邮件文件夹。 ## 功能特性 - **实时监控**：通过IMAP IDLE实现（推送方式，无需轮询） - **多阶段管道**：解析 → 白名单检查 → 富化 → AI → 决策 → 执行 → 审计 - **富化信号**：SPF、DKIM、DMARC、DKIM对齐（cousin-domain `d=` 不匹配检测）、DNSBL信誉、WHOIS域名年龄、显示名称欺骗、被动URL扩展（仅短链接——无信标）、[URLhaus](https://urlhaus.abuse.ch)恶意软件URL信誉、以及[VirusTotal](https://www.virustotal.com) URL和IP信誉（90+厂商） - **AI提供商**：OpenAI、Anthropic或本地[Ollama](https://ollama.com)实例 - **三种操作**：放行（无更改）、标记（IMAP关键字）、移动到配置的垃圾邮件文件夹（默认：`[Gmail]/Spam`） - **激进程度预设**：一键式灵敏度调整（保守/默认/激进/非常激进），支持在YAML中细粒度覆盖 - **白名单**：按邮箱、域名或主题模式免除可信发件人的分析 - **Web界面**：Flask管理界面——仪表板、审计日志、配置、白名单、凭据、手动测试、文档 - **审计日志**：完整的SQLite记录，包含每个决策的信号、推理和处理时间 - **备份与恢复**：从Web界面导出配置（仅YAML）或完整备份ZIP（YAML + 凭据）；通过ZIP上传一键恢复 ## 屏幕截图

Dashboard — live stats, threat distribution, 7-day action chart, and IMAP status
Audit log — full AI reasoning, signals, and raw model response per email	Whitelist — trusted sender rules by address, domain, or subject

## 架构 ``` IMAP IDLE (main thread) │ └─▶ ThreadPoolExecutor (worker threads) │ ├── message_parser — RFC 822 parsing, URL extraction ├── whitelist — bypass enrichment/AI for trusted senders ├── enrichment — SPF/DMARC/DKIM/DKIM alignment/DNSBL/WHOIS/URL expansion/URLhaus/VirusTotal ├── ai_analyzer — OpenAI / Anthropic / Ollama via httpx ├── decision_engine — threshold logic → PASS / FLAG / MOVE_TO_JUNK ├── imap_actions — set $VerdictMail-Suspect keyword or copy+delete └── audit_logger — SQLite + rotating log file ``` ## 环境要求 - Ubuntu 24.04 LTS（推荐）或 22.04 LTS，安装时以root用户运行 - Python 3.11+ — Ubuntu 24.04默认包含；在22.04上可能需要手动安装（`apt-get install python3.11 python3.11-venv`） - 一个已启用IMAP访问的IMAP邮件账户。对于Gmail：生成[Gmail应用密码](https://support.google.com/accounts/answer/185833)（Gmail设置 → 查看所有设置 → 转发和POP/IMAP → 启用IMAP，然后在Google账户 → 安全 → 应用密码）。对于其他提供商，请参阅下面的[其他IMAP提供商](#other-imap-providers)。 - 主机上80端口空闲（Web界面使用） - 以下任一： - OpenAI API密钥 - Anthropic API密钥 - 一个运行中的[Ollama](https://ollama.com)实例（本地或远程），已拉取模型（例如 `ollama pull qwen2.5-coder:14b`）。支持带有思考/推理模式的模型（Qwen3、DeepSeek-R1等）——思考模式会为延迟敏感的管道使用自动禁用。 ## 安装 ### 快速安装（推荐） 下载并检查安装脚本，然后以root身份运行： ``` curl -sSL https://raw.githubusercontent.com/ascarola/verdictmail/main/install.sh -o install.sh less install.sh # review before running sudo bash install.sh ``` 脚本会自动处理以下所有步骤，并交互式提示输入凭据、AI提供商、模型和时区。如果中途出现问题，可以安全地重新运行。 ### 手动安装 如果您喜欢逐步安装，请按照以下说明操作。 ### 1. 安装系统依赖 ``` apt-get update apt-get install -y git python3 python3-venv python3-dev python3-pip \ build-essential libssl-dev sqlite3 ``` ### 2. 创建服务用户和目录 ``` useradd -r -s /bin/false -M -d /opt/verdictmail verdictmail mkdir -p /opt/verdictmail /var/log/verdictmail chown verdictmail:verdictmail /opt/verdictmail /var/log/verdictmail ``` ### 3. 克隆仓库 ``` git clone https://github.com/ascarola/verdictmail.git /opt/verdictmail chown -R verdictmail:verdictmail /opt/verdictmail ``` ### 4. 创建虚拟环境并安装依赖 ``` python3 -m venv /opt/verdictmail/venv /opt/verdictmail/venv/bin/pip install --upgrade pip /opt/verdictmail/venv/bin/pip install -r /opt/verdictmail/requirements.txt chown -R verdictmail:verdictmail /opt/verdictmail/venv ``` ### 5. 配置凭据 ``` cp /opt/verdictmail/.env.example /opt/verdictmail/.env chown verdictmail:verdictmail /opt/verdictmail/.env chmod 600 /opt/verdictmail/.env ``` 编辑 `/opt/verdictmail/.env` 并填写您的IMAP凭据和AI提供商API密钥。还可以添加两个可选的威胁情报密钥：`URLHAUS_API_KEY`（从[abuse.ch](https://abuse.ch/)免费获取）用于恶意软件URL查询，以及`VIRUSTOTAL_API_KEY`（从[virustotal.com](https://www.virustotal.com)免费获取）用于针对90+安全厂商的URL和IP信誉检查。如果未设置，两者都会被静默跳过。 ### 6. 配置应用程序 ``` cp /opt/verdictmail/config/verdictmail.yaml.example /opt/verdictmail/config/verdictmail.yaml chown verdictmail:verdictmail /opt/verdictmail/config/verdictmail.yaml ``` 编辑 `/opt/verdictmail/config/verdictmail.yaml` 并至少设置： - `ai.provider` 和 `ai.model` - `timezone`（IANA名称，例如 `America/New_York`） ### 7. 安装systemd单元 ``` cp /opt/verdictmail/systemd/verdictmail.service /etc/systemd/system/ cp /opt/verdictmail/systemd/verdictmail-web.service /etc/systemd/system/ systemctl daemon-reload ``` ### 8. 安装sudoers规则（允许Web界面重启守护进程） ``` cp /opt/verdictmail/systemd/verdictmail-sudoers /etc/sudoers.d/verdictmail chmod 440 /etc/sudoers.d/verdictmail ``` ### 9. 启用并启动 ``` systemctl enable --now verdictmail verdictmail-web systemctl status verdictmail verdictmail-web ``` ### 10. 通过Web界面验证安装 打开浏览器并导航到： ``` http:// ``` 首次访问时，VerdictMail会提示您设置Web界面密码。此密码保护所有管理页面。scrypt哈希值存储在 `verdictmail.yaml` 中——明文密码永远不会保存。 登录后，验证守护进程在**仪表板**上运行，并使用**手动测试**页面确认完整管道正常工作，然后再依赖它处理实时邮件。 ## 配置 所有非机密设置都在 `/opt/verdictmail/config/verdictmail.yaml` 中。 请参阅 `config/verdictmail.yaml.example` 获取完整注释的模板。 更改需要重启守护进程：`systemctl restart verdictmail`。 | 键 | 默认值 | 描述 | |-----|---------|-------------| | `ai.provider` | `openai` | AI后端：`openai`、`anthropic` 或 `ollama` | | `ai.model` | `gpt-4o-mini` | 传递给提供商的模型名称 | | `ai.timeout_seconds` | `120` | 每个请求的AI超时时间 | | `ai.ollama_base_url` | `http://localhost:11434` | Ollama基础URL（仅限ollama提供商） | | `thresholds.flag` | `0.55` | 标记中/高威胁的最低置信度。通过激进程度预设或直接设置。 | | `thresholds.junk` | `0.80` | 将高威胁移动到垃圾邮件的最低置信度。通过激进程度预设或直接设置。 | | `imap.host` | `imap.gmail.com` | IMAP服务器 | | `imap.port` | `993` | IMAP SSL端口 | | `imap.folder` | `INBOX` | 监控的文件夹 | | `imap.junk_folder` | `[Gmail]/Spam` | MOVE_TO_JUNK操作的目标文件夹（例如Fastmail/Outlook上的 `Junk`） | | `worker_threads` | `4` | 并发消息处理器数量 | | `startup_scan_limit` | `20` | 启动时处理的最大未读邮件数量 | | `whitelist.enabled` | `true` | 白名单的总开关 | | `whitelist.rules` | `[]` | 白名单规则对象列表 | | `timezone` | `UTC` | 仪表板和审计日志的IANA时区 | ## 其他IMAP提供商 VerdictMail针对Gmail进行开发和测试，但底层IMAP代码仅使用标准RFC兼容操作（IMAP IDLE、COPY、DELETE、EXPUNGE），应该适用于任何支持IDLE的IMAP服务器。 在 `.env` 中设置 `IMAP_USERNAME` 和 `IMAP_PASSWORD` 为您的账户凭据，然后在 `verdictmail.yaml` 中更新IMAP设置： | 提供商 | `imap.host` | `imap.port` | `imap.junk_folder` | |----------|-------------|-------------|-------------------| | Gmail | `imap.gmail.com` | `993` | `[Gmail]/Spam` | | Fastmail | `imap.fastmail.com` | `993` | `Junk` | | Outlook / Hotmail | `outlook.office365.com` | `993` | `Junk` | | Apple iCloud | `imap.mail.me.com` | `993` | `Junk` | ## 操作 | 操作 | 何时 | 效果 | |--------|------|--------| | `pass` | 干净邮件、低威胁或已列入白名单 | 无IMAP更改 | | `flag` | 中/高威胁且置信度足够 | 设置 `$VerdictMail-Spect` IMAP关键字；邮件保留在收件箱 | | `move_to_junk` | 高/严重威胁且置信度高 | 复制到配置的垃圾邮件文件夹（`imap.junk_folder`，默认 `[Gmail]/Spam`），删除原邮件 | ## 白名单 白名单绕过可信发件人的富化和AI分析。规则按顺序评估；第一个匹配获胜。 每个规则匹配以下一项或多项： - `sender` — 精确邮箱地址（不区分大小写） - `sender_domain` — 某个域名的所有地址 - `subject_contains` — 主题的不区分大小写子字符串 一个规则中的多个字段需要**全部**匹配（AND逻辑）。通过Web界面或直接编辑 `verdictmail.yaml` 管理规则（需要重启）。 ## Web界面 Flask管理界面与守护进程一起运行在80端口。 | 页面 | 路径 | 描述 | |------|------|-------------| | 仪表板 | `/` | 统计、威胁图表、最近邮件、服务状态；启动/停止/重启守护进程 | | 审计日志 | `/audit` | 分页、可搜索的表格，带完整详情模态框 | | 配置 | `/config` | 浏览器内YAML编辑器 + AI提供商快速配置 | | 白名单 | `/whitelist` | 添加、编辑和删除白名单规则 | | 凭据 | `/credentials` | IMAP凭据和API密钥管理 | | 手动测试 | `/test` | 对提交的邮件进行管道试运行 | | 文档 | `/docs` | 应用内参考手册 | | 配置（备份） | `/config/export` | 下载 `verdictmail.yaml` | | 配置（完整备份） | `/config/export/full` | 下载包含 `verdictmail.yaml` + `.env` 的ZIP文件 | | 关于 | `/about` | 版本和技术栈信息 | 首次访问时设置Web界面密码。密码哈希存储在 `verdictmail.yaml` 中；明文密码永远不会存储。 ## 验证 ### 从Web界面启动/停止/重启守护进程 仪表板提供**停止**、**启动/恢复**和**重启**按钮。 VerdictMail自动检测其环境并选择适当的控制策略： | 环境 | 策略 | 停止行为 | |-------------|----------|----------------| | 裸机/特权容器 | `sudo systemctl` | 守护进程完全停止；单元标记为非活动 | | 非特权LXC（例如Proxmox） | 信号 + 暂停标志 | 守护进程保持运行但跳过新邮件；邮件保持UNSEEN状态直到恢复 | ### 检查Ollama连接性（如果使用Ollama提供商） ``` curl http://localhost:11434/api/tags ``` ### 测试IMAP连接性 ``` python3 -c " import imapclient c = imapclient.IMAPClient('imap.example.com', ssl=True) # replace with your IMAP host c.login('YOUR_IMAP_USERNAME', 'YOUR_IMAP_PASSWORD') print(c.list_folders()) c.logout() " ``` ### 运行单元测试 ``` # 安装 dev dependencies（包括 pytest） /opt/verdictmail/venv/bin/pip install -r /opt/verdictmail/requirements-dev.txt PYTHONPATH=src /opt/verdictmail/venv/bin/python -m pytest tests/ -v ``` 测试套件涵盖： | 文件 | 测试内容 | |------|---------------| | `test_message_parser.py` | RFC 2822解析、头部提取、URL提取、DKIM签名解析 | | `test_decision_engine.py` | 所有7条决策规则、两个阈值的边界条件、阈值配置变体、大小写不敏感 | | `test_ai_analyzer.py` | 从纯文本/带围栏/嵌入文本中提取JSON、响应模式验证、所有 `_build_user_prompt` 部分和条件块（URLhaus、VirusTotal、DKIM对齐、PBL说明、正文截断） | ### 观看实时日志 ``` journalctl -u verdictmail -f tail -f /var/log/verdictmail/verdictmail.log ``` ### 检查审计数据库 ``` sqlite3 /var/log/verdictmail/verdictmail.db \ "SELECT id, subject, threat_level, printf('%.0f%%', confidence*100), action_taken, reasoning FROM audit_log ORDER BY id DESC LIMIT 10;" ``` ## 故障排除 | 症状 | 检查 | |---------|-------| | 服务无法启动 | `journalctl -u verdictmail -n 50` — 查找配置或凭据错误 | | AI超时 | 验证提供商连接性和 `ai.timeout_seconds` | | IMAP认证失败 | 确认凭据正确（Gmail的应用密码；其他提供商的具体密码）且已在提供商设置中启用IMAP | | 没有处理邮件 | 守护进程处理新邮件/未读邮件；使用**手动测试**页面验证管道工作正常 | | DNSBL慢 | DNS解析超时为每个列表3秒；检查网络连接 | | URLhaus测试超时 | 验证防火墙允许到 `urlhaus-api.abuse.ch` 的出站HTTPS。如果没有密钥，URLhaus查询会被静默跳过，因此守护进程仍然可以正常工作。 | ## 升级 ### v0.3.2 — 快速关闭修复 非破坏性错误修复。除了拉取和重启外无需操作： ``` git -C /opt/verdictmail pull systemctl restart verdictmail ``` 修复了当守护进程在指数退避期间（例如在具有虚拟凭据的新安装上导入备份ZIP后）重启时发生的150秒强制关闭延迟。现在关闭是即时的。 ### v0.3.1 — 备份与恢复 非破坏性功能添加。从v0.3.0升级时无需操作。 配置页面上现在提供**备份与恢复**卡片： - **导出配置** — 下载 `verdictmail.yaml`（无凭据） - **导出完整备份** — 下载包含 `verdictmail.yaml` + `.env` 的带日期ZIP文件（包含凭据——安全存储） - **导入配置** — 上传 `verdictmail.yaml` 替换实时配置 - **导入完整备份** — 上传备份ZIP一步恢复 `verdictmail.yaml` 和 `.env` ### v0.3.0 — IMAP凭据变量重命名 环境变量已重命名以提高提供商无关的清晰度： | 旧版（v0.2.x） | 新版（v0.3.0+） | |-----------------------|--------------------| | `GMAIL_USERNAME` | `IMAP_USERNAME` | | `GMAIL_APP_PASSWORD` | `IMAP_PASSWORD` | **需要操作：** 编辑 `/opt/verdictmail/.env` 并重命名这两个变量。 旧名称在v0.3.0中仍然有效（日志中会出现弃用警告） 但将在v0.4.0中移除。 ## 日志轮换 旋转文件处理器将每个日志文件限制在10 MB，保留5个备份。 系统级轮换使用 `logrotate` 不是必需的，但可以添加到 `/etc/logrotate.d/verdictmail`。 ## 开发说明 VerdictMail由A. Scarola设计和架构。实现过程得到了[Claude Code](https://claude.ai/code)（Anthropic的AI编程助手）的大量帮助，该助手根据作者的详细规格、需求和迭代方向编写了大部分代码。所有设计决策、安全架构、功能选择和测试都由作者指导和验证。 ## 许可证 MIT — 参见 [LICENSE](LICENSE)。

标签：AI助手, AI安全分析, AI风险缓解, AMSI绕过, Anthropic, Ask搜索, CIS基准, DKIM验证, DMARC验证, DNSBL, Flask, IMAP IDLE, LLM评估, Ollama, OpenAI, Python, SMTP安全, SOC工具, SPF验证, URLhaus, VirusTotal, whitelist, 内存规避, 域名信誉, 威胁情报, 威胁检测, 审计日志, 开发者工具, 恶意URL检测, 无后门, 漏洞发现, 网络安全, 邮件安全, 邮件归档, 邮件监控, 邮件网关, 钓鱼防护, 隐私保护