Honcho92/scam-shield

# scam-shield [](https://github.com/Honcho92/scam-shield/actions/workflows/tests.yml) [](https://github.com/Honcho92/scam-shield/actions/workflows/js-parity.yml) [](https://www.python.org/downloads/) [](#tests) [](LICENSE) [](#design) `scam-shield` 是一个本地优先的工具包，用于识别、评分和报告诈骗。 它完全在你的机器上运行——除非你配置了可选的 Telegram bot 或本地 Ollama 第二意见，否则不会有任何数据流出。 ## 运行效果 | Telegram bot 回复 | Chrome 扩展弹窗 | |:------------------:|:----------------------:| |  |  | 左侧的 Telegram bot 使用启发式引擎和本地 Ollama LLM 在 1.3 秒内对一条钓鱼消息进行了评分。右侧的 Chrome 扩展在用户输入任何内容之前就标记了一个极其相似的 Microsoft 域名。 ## 功能说明 | 层级 | 内容 | 位置 | |------:|------|------| | **话术剧本** | 35+ 个诱导性问题，按诈骗类型手动调优，并附带原因 | 手机，任何地方 | | **检测器** | 启发式评分器 (0-100) + 结论 + 实体提取 | CLI / Python | | **LLM 裁决** | 本地 Ollama 第二意见（约 1.3 秒，可选） | CLI / Python | | **蜜罐** | 自动回复角色，浪费诈骗者的时间并记录证据 | CLI / Telegram | | **Telegram bot** | 以上所有功能，在你的手机上运行 | 手机 | | **`/quiet` 模式** | 单行回复，“转发即忘” | Telegram bot | | **Agent 循环** | 后台监控——自动生成报告包，发送私信 | cron / 定时任务 | | **每周摘要** | 周日晚上的活动汇总私信 | cron | | **Chrome 扩展** | 对你加载的每个页面进行离线评分，并在工具栏显示角标 | 浏览器 | | **报告包** | 自动生成 9 个准备好的文件，用于提交给 FTC/IC3/银行/平台 | CLI / Telegram | | **历史数据库** | 记录每个报告的 SQLite，支持全文搜索和统计 | CLI | 零外部 Python 依赖。Ollama 是唯一可选的外部服务（用于 LLM 裁决）。Chrome 扩展不使用任何 npm 包。 ## 快速开始 ### 安装 ``` git clone https://github.com/Honcho92/scam-shield cd scam-shield # 可选：安装为 package，以便 `python -m scam_shield` 可以在任何地方运行 python -m pip install -e . ``` ### 尝试演示 ``` PYTHONPATH=. python -m scam_shield demo ``` 你应该会看到 7 条已知的诈骗消息得分在 50 分以上，2 条合法消息得分为 0。 ### 对收到的消息进行评分 ``` PYTHONPATH=. python -m scam_shield analyze "URGENT: Microsoft Security has detected a virus. Call +1-888-555-0199 and download AnyDesk immediately. Pay 299 USD in gift cards." ``` 你将得到一个结论、评分、诈骗类型、每个起作用的信号、找到的电话/电子邮件/URL/索款要求，以及量身定制的建议。 ### 生成 FTC 就绪的报告包 ``` PYTHONPATH=. python -m scam_shield report "PASTE THE MESSAGE" --out ./my-case ``` 这会生成 9 个文件（FTC 投诉陈述、银行通知、平台滥用报告、执法 JSON、提交清单等），可以直接复制/粘贴到 ReportFraud.ftc.gov。 ### 运行 Telegram bot ``` export TELEGRAM_BOT_TOKEN=... # get one from @BotFather export SCAMSHIELD_LLM=on # optional, enables Ollama second opinion PYTHONPATH=. python -m scam_shield.telegram_bot ``` 将任何可疑的文本/电子邮件转发给该 bot。获取结论、应对话术，以及可选的蜜罐反制对话。 ### 安装 Chrome 扩展 1. 打开 `chrome://extensions` 2. 开启 **开发者模式** 3. 点击 **加载已解压的扩展程序**，选择 `chrome-extension/` 文件夹 4. 将 Scam-Shield 图标固定到你的工具栏 你加载的每个页面都会被评分。如果页面触发 `suspicious` 或更严重的级别，工具栏图标将显示彩色角标。点击查看完整详情。 ## 设计 检测器是**透明的**：每个触发的信号都会暴露出触发的代码片段、其贡献的权重以及它暗示的诈骗类型。这里没有黑盒评分。你可以阅读 `scam_shield/detector.py` 并理解每一个决策。 `detector.py` 顶部的模式库是纯数据——由 `(scam_type, category, weight, compiled_regex)` 元组组成。添加一个新模式只需一行代码。移除一个误报模式也只需一行代码。 Agent 循环和 Telegram bot 共享一个单一的事实来源：SQLite 历史数据库。Bot 负责写入报告；Agent 则提取报告，运行完整的流水线，并对其进行操作。两者都可以独立运行。 ## 结论分级 | 评分 | 结论 | 操作建议 | |----------|----------------|-------------------------------------------------------| | 0-24 | clean | 可能没问题。保持警惕。 | | 25-49 | suspicious | 放慢速度。在采取行动前进行核实。 | | 50-74 | likely_scam | 不要理睬。进行举报。 | | 75+ | scam | 拉黑，举报，可选择使用话术进行反制。 | ## 测试 ``` PYTHONPATH=. python -m unittest discover -s tests ``` 88 个测试通过：21 个检测器/话术剧本/蜜罐，14 个 telegram bot 命令，17 个 LLM 裁决及完整流水线，11 个报告包，9 个历史记录，1 个 JS-Python 一致性测试，17 个 Agent 循环/摘要/bot-agent 集成。外加 1 个用于无 token bot 启动路径的冒烟测试。 ## 布局 ``` scam_shield/ # 9 Python modules (detector, playbook, honeypot, # llm_judge, report_pack, history, agent_loop, # digest, telegram_bot, cli) chrome-extension/ # Manifest V3 extension, vanilla JS, no frameworks tests/ # 8 test files, 88 passing docs/ # Screenshots for the README + HTML mockups OPERATOR_GUIDE.md # One-page reference for every layer setup_scheduler.ps1 # One-time Windows Task Scheduler setup make_icons.py # Regenerate Chrome extension icons (stdlib only) LICENSE # MIT ``` ## Agent 循环（“后台 AI”组件） ``` # one-shot PYTHONPATH=. python -m scam_shield.agent_loop # forever，每 60s 轮询一次 PYTHONPATH=. python -m scam_shield.agent_loop --watch --interval 60 ``` 对于 `scam` 和 `likely_scam` 结论：自动生成报告包到 `~/.scam-shield/reports/auto--/`，并通过 bot 给你发送一条简短的私信。对于 `suspicious`：给你发送一条简短的私信。对于 `clean`：仅记录日志。 要接收来自 Agent 的 Telegram 私信，请将 `SCAMSHIELD_NOTIFY_CHAT_ID` 设置为你的聊天 ID（在 Telegram 上将任意消息转发给 `@userinfobot` 即可找到你的 ID）。 ## 每周摘要 ``` PYTHONPATH=. python -m scam_shield.digest --send ``` 通过你的 bot 发送过去 7 天的汇总（或通过 `--days N` 指定任意时间窗口）。按结论、热门诈骗类型、热门电话/电子邮件/URL 以及最严重的违规者进行统计。 ## 在 Windows 上自动定时任务 ``` # 以 Administrator 身份运行一次 .\setup_scheduler.ps1 ``` 创建两个 Windows 计划任务： - **ScamShield Agent** —— 每 5 分钟一次，处理未处理的报告 - **ScamShield Digest** —— 周日晚上 8 点，发送每周摘要 ## 隐私 一切均在本地进行。检测器绝不会联系它找到的 URL、电子邮件或电话号码。唯一会发生的网络调用是： - （可选）通过 HTTP 连接到你的本地 Ollama 进行 LLM 裁决 - （可选）如果你配置了 bot，通过 HTTPS 连接到 `api.telegram.org` 你可以一口气审查整个代码库——它包含约 3000 行纯 Python 代码和约 600 行原生 JS 代码。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。 ## 免责声明 本工具旨在帮助你识别诈骗。它不能代替你的判断、法律建议或向实际执法部门举报。模式库无法捕捉所有的诈骗——那些狡猾的骗局仍会漏网。如果觉得情况不对，请相信你的直觉，并通过独立渠道进行核实。

标签：AI风险缓解, 反诈骗, 启发式检测, 数据可视化, 本地优先, 机器人, 浏览器扩展, 网络钓鱼检测, 蜜罐, 证书利用, 逆向工具