PercevalFox/discord-sentinel

# 🛡️ Discord Sentinel **为 Discord 服务器提供自托管的安全分析与威胁检测。** [](https://opensource.org/licenses/MIT) [](https://www.python.org/) [](https://www.docker.com/) [](https://discordpy.readthedocs.io/) [English](README.md) · [Français](README.fr.md) Discord Sentinel 是一个注重隐私的安全机器人，搭配丰富的 React 仪表板。它会实时监控你的 Discord 服务器，检测钓鱼 URL、可疑账户、突袭、协调性垃圾邮件以及 IOCs（网络指标），并且默认不会存储明文消息。 ## ✨ 功能 - 🎣 **钓鱼 URL 检测**：通过 URLhaus、Google Safe Browsing 以及本地钓鱼模式匹配 - 👤 **可疑账户检测**（新注册账户、高熵名称、品牌冒充） - 🌊 **突袭检测**：基于加入频率的滚动 Z 分数检测 - 🗣️ **协调性垃圾邮件检测**：使用 MinHash LSH 进行近似重复匹配 - 🔍 **IOC 提取**：从自由格式的聊天中提取 IP、域名、CVE、哈希等 - 🎯 **实时告警**：将告警发布到 Discord 频道并附带跳转链接 - 📡 **实时 SIEM 风格推送**：通过 WebSocket 提供 - 🏆 **名人堂**：包含 13 个参与奖项（如 Novelist、Minimalist、Streak、Pioneer 等） - 📄 **GDPR 合规**：`/export-for @member` 生成成员数据的 PDF 导出，`/forget-member @member` 彻底删除数据 - 🔐 **取证模式**：管理员可在 30 天内解密触发内容（用于事件响应） - 🛡️ **隐私设计**：默认仅存储 SHA-256 哈希；仅告警触发消息以加密明文形式存储，30 天后自动清除 - 🎨 **深色/浅色主题**、Kiosk 模式、可配置时间窗口（24h / 7d / 30d / 全部） ## 🚀 快速安装 **要求**：一台已安装 Docker + Docker Compose 插件的 Linux 服务器（推荐 Ubuntu 22.04+ 或 Debian 12+）。 ``` git clone https://github.com/PercevalFox/discord-sentinel.git cd discord-sentinel chmod +x install.sh ./install.sh ``` 交互式安装程序将： 1. 检查前置条件 2. 提示输入 Discord 凭证（Token、群组 ID、管理员 ID、告警频道） 3. 询问如何暴露仪表板（回环 / VPN / 公网） 4. 生成带有随机管理员 API Token 的安全 `.env` 5. 构建并启动完整的 Docker 栈 6. 运行数据库迁移 7. 提供回填服务器历史数据（成员、频道、消息）的选项 8. 打印针对你环境的访问说明 ## 📋 设置 Discord 机器人 在运行安装程序之前，你需要准备一个 Discord 机器人 Token： 1. 前往 [https://discord.com/developers/applications](https://discord.com/developers/applications) → **New Application** 2. 命名（例如 `Sentinel`）→ **Create** 3. **Bot** 标签（左侧边栏）→ **Reset Token** → **Copy** 并保存 4. **启用全部 3 个特权网关意图**： - ✅ Presence Intent - ✅ Server Members Intent - ✅ Message Content Intent - 点击 **Save Changes** 5. **OAuth2 → URL Generator**： - **Scopes**：`bot` + `applications.commands` - **Bot Permissions**：`Send Messages`、`Read Messages/View Channels`、 `Read Message History`、`Embed Links`、`Attach Files`、`Use Slash Commands` 6. 打开生成的链接，邀请机器人加入你的服务器 7. 在 Discord 中开启 **Settings → Advanced → Developer Mode** 8. 右键服务器图标 → **Copy Server ID** 9. 右键你的用户名 → **Copy User ID** 10. 创建 `#sentinel-alerts` 频道 → 右键 → **Copy Channel ID** 你现在已拥有安装程序所需的 4 个 ID。 ## 🖥️ 仪表板访问模式 安装程序会询问你希望如何暴露仪表板。请根据你的威胁模型选择合适的模式： ### 模式 1 — 回环 + SSH 隧道（最安全，默认） 绑定到 `127.0.0.1`，不向互联网暴露任何内容。可通过以下方式从本机访问： ``` ssh -L 8082:127.0.0.1:8082 user@your-server ``` 然后访问 `http://127.0.0.1:8082`。这是推荐给大多数用户的模式。 ### 模式 2 — VPN（Tailscale、WireGuard、ZeroTier 等） 绑定到 VPN 接口 IP（例如 Tailscale 的 `100.x.x.x`）。仪表板仅对连接到该 VPN 的设备可见。 ### 模式 3 — 公网访问并配合反向代理 绑定到 `0.0.0.0`，并配置 Nginx 反向代理启用 HTTPS 和 HTTP 基础认证。完整指南请参考 [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md)。 ## 🔐 隐私与 GDPR Sentinel 采用 **分层数据最小化** 原则： | 事件 | 存储内容 | |-------|---------------| | 普通消息 | 仅元数据（作者、频道、时间戳、内容的 **SHA-256 哈希**） | | 告警触发消息 | 加密明文（AES-128 + HMAC-SHA256），**30 天后自动清除** | | 私信或语音 | 不监控、不存储 | ### GDPR 管理命令 - `/export-for @member` — 生成该成员所有数据的 PDF 并通过私信发送给管理员 - `/forget-member @member` — 删除该成员的所有数据（告警记录匿名化保留用于审计） ### 建议的法律依据 **正当利益**（GDPR 第 6-1-f 条）——保护服务器及其成员免受安全威胁。我们建议在服务器规则中发布一条信息性消息，说明 Sentinel 的数据收集行为。参考 [隐私模板](docs/PRIVACY_NOTICE_TEMPLATE.md) 可快速发布。 ## 🏗️ 架构 ``` ┌─────────────┐ │ Discord API │ └──────┬──────┘ │ Gateway events ▼ ┌─────────┐ ┌──────────────┐ ┌─────────────┐ │ redis │◄─────►│ bot │──────►│ postgres │ │ streams │ │ (discord.py) │ │ │ └────┬────┘ └──────────────┘ └──────┬──────┘ │ │ │ consumed by │ queried by ▼ ▼ ┌─────────┐ ┌─────────────┐ │ worker │──────────────────────────────►│ api │ │(analyze)│ │ (FastAPI) │ └─────────┘ └──────┬──────┘ │ HTTP + WebSocket ▼ ┌─────────────┐ │ web │ │(nginx+React)│ └─────────────┘ ``` - **bot** — discord.py；标准化网关事件并推送至 Redis 流 - **worker** — 消费流，运行分析器（URL 扫描、突袭检测、MinHash 重复、IOC 提取、账户信号），写入告警 - **api** — FastAPI + WebSocket 枢纽；提供仪表板 API - **web** — React + Vite + Tailwind；通过 Nginx 提供服务，并使用 DNS 感知的反向代理连接 API - **db** — Postgres 16，配合 asyncpg - **redis** — 7，使用 AOF 持久化存储流 ## 📦 手动安装（不使用 `install.sh`） ``` git clone https://github.com/PercevalFox/discord-sentinel.git cd discord-sentinel cp .env.example .env nano .env # fill in the REQUIRED fields at the top # 启动 db + redis docker compose -f docker/docker-compose.yml up -d db redis # 运行迁移 docker compose -f docker/docker-compose.yml run --rm api \ alembic -c /app/alembic.ini upgrade head # 启动所有服务 docker compose -f docker/docker-compose.yml up -d # 可选回填服务器历史记录 docker compose -f docker/docker-compose.yml run --rm bot \ python -m sentinel.bot.backfill --days 30 ``` ## 🛠️ 开发 ``` # 后端 pip install -e ".[dev]" pytest ruff check src tests # 前端 cd frontend npm install npm run dev # Vite dev server on port 5173 ``` ## 🧪 检测阈值调节 所有阈值均在 `.env` 中可配置： ``` RAID_JOIN_THRESHOLD_PER_MIN=8 # raise if raid false positives SUSPICIOUS_ACCOUNT_MAX_AGE_DAYS=7 # flag accounts younger than this USERNAME_ENTROPY_THRESHOLD=3.8 # Shannon entropy (higher = more random) WATCHED_BRANDS=["discord.com","github.com","..."] ALERT_MIN_LEVEL=medium # info | low | medium | high | critical ``` ## 📚 文档 - [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — 生产环境部署（Nginx + certbot + HTTP 基础认证） - [`docs/PRIVACY_NOTICE_TEMPLATE.md`](docs/PRIVACY_NOTICE_TEMPLATE.md) — 可直接发布的 GDPR 通知模板 - [`SECURITY.md`](SECURITY.md) — 漏洞披露、威胁模型、加密细节 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — 贡献指南 ## 🤝 贡献 欢迎提交问题和 Pull Request。请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 🔒 安全 若发现安全问题，**请勿公开创建 Issue**。请遵循 [`SECURITY.md`](SECURITY.md) 中的披露流程。 ## 📜 许可证 MIT — 参见 [`LICENSE`](LICENSE)。

标签：AMSI绕过, discord.py, Discord安全, Docker, GDPR, Google Safe Browsing, IOC提取, MinHash LSH, Python, Raid检测, React, Syscalls, URLhaus, WebSocket, 依赖分析, 加密存储, 品牌冒充检测, 垃圾信息检测, 威胁检测, 安全机器人, 安全防御评估, 开源安全工具, 数据导出, 数据遗忘, 无后门, 熵值检测, 网络安全, 自托管, 逆向工程平台, 钓鱼检测, 隐私保护