ferasbusiness666/GuardianNode
GitHub: ferasbusiness666/GuardianNode
本地优先的个人安全与威胁情报中心，通过实时监控 Telegram 频道并基于多语言关键词评分发送私密警报，同时提供加密个人保险库与数据泄露检测功能。
Stars: 0 | Forks: 0
# GuardianNode
**本地优先的物理威胁监控。没有云端。没有中间商。您的数据仅保留在您的设备上。**
GuardianNode 实时监控 Telegram 频道，根据多语言威胁关键词库对传入消息进行评分，并在风险评分超过您的阈值时，通过您自己的 Telegram 机器人发送私密警报。
## 工作原理
```
Telegram channels (Arabic/EN/RU/HE/…)
│
▼
TelegramMonitor (Telethon — real-time socket)
│
▼
Arabic normalizer ── strips diacritics, alef variants, tatweel
│
▼
Risk Scorer ←── keyword weights × source reliability
│
├── score < threshold → silent log (SQLite)
│
└── score ≥ threshold → Bot API alert → your private Telegram
Personal Vault (AES-256-GCM encrypted at ~/.guardiannode/vault.enc)
│
├── Passwords → HIBP k-anonymity (SHA-1 prefix only sent, no Tor needed)
│
└── Emails → HIBP via Tor (your IP is never seen by HIBP)
▲
new Tor circuit per identity (stream isolation)
```
**风险评分** = `关键词基础分 × 来源可靠性乘数`
| 关键词级别 | 基础分 | 官方来源 | 可信来源 | 普通来源 |
|:-------------|:----------:|:--------------:|:--------------:|:--------------:|
| Critical | 90 | 90 | 72 | 45 |
| High | 70 | 70 | 56 | 35 |
| Medium | 45 | 45 | 36 | 22.5 |
## 环境要求
- Python 3.11+
- 一个 Telegram 账号
- 一个 Telegram 机器人（免费，通过 [@BotFather](https://t.me/BotFather) 创建）
- 来自 [my.telegram.org](https://my.telegram.org) 的 API 凭据
## 阿拉伯语支持
大多数频道消息使用阿拉伯语。GuardianNode 在匹配前会对阿拉伯语文本进行规范化处理，因此无论是否存在变音符号、Alef 变体或附加前缀，关键词匹配都能正常工作：
| 频道中的原始文本 | normalize() 处理后 | 关键词匹配 |
|:---------------|:-----------------|:-------------|
| `الإخلاءُ العاجل` | `الاخلاء العاجل` | `اخلاء` ✓ |
| `وإخلاء المنطقة` | `واخلاء المنطقه` | `اخلاء` ✓ |
| `تَحْذِيرٌ عاجل` | `تحذير عاجل` | `تحذير` ✓ |
| `غاراتٌ جوية` | `غارات جويه` | `غارات` ✓ |
规范化处理包括：移除 Tashkeel（变音符号）、`أإآ→ا`、`ة→ه`、`ى→ي`、移除 Tatweel（加长符）。
## 快速开始
```
# 1. Clone
git clone https://github.com/ferasbusiness666/guardiannode
cd guardiannode
# 2. 安装依赖
pip install -r requirements.txt
# 3. 首次设置（交互式向导）
python run.py --setup
# 4. 开始监控
python run.py
```
设置向导将：
1. 要求您设置一个**主密码**（用于加密所有存储的凭据）
2. 收集您的 Telegram API 凭据
3. 引导您创建并关联您的通知机器人
4. 让您添加带有可靠性评级的待监控频道
5. 仅进行一次身份验证并保存加密的会话
在随后的每次启动时，系统都会提示您输入主密码。没有任何内容会以明文形式存储。
## 数据存储位置
| 文件 | 用途 |
|:-----|:--------|
| `~/.guardiannode/config.enc` | AES-256-GCM 加密的配置文件（API 密钥、会话） |
| `~/.guardiannode/events.db` | 本地 SQLite 数据库，记录所有已评分的事件 |
`.guardiannode/` 目录在创建时使用 `chmod 700` 权限。配置文件使用 `chmod 600` 权限。这两个文件均不包含明文凭据。
## 安全设计
| 风险点 | 缓解措施 |
|:--------|:-----------|
| 凭据存储 | AES-256-GCM 加密；密钥通过 PBKDF2-SHA256（60 万次迭代）派生 |
| 主密码 | 绝不写入磁盘——仅在启动时输入，只保留在内存中 |
| Telegram 会话 | 作为加密字符串存储在 `config.enc` 内（Telethon `StringSession`） |
| 通知隐私 | 警报发送至**您自己的机器人**——没有任何 GuardianNode 服务器能看到它们 |
| 去重 | `(channel_id, message_id)` 的 SHA-256 哈希值可防止重复警报 |
## 配置说明
请查看 [`config.example.yaml`](./config.example.yaml) 了解所有选项。
关键设置：
```
monitoring:
alert_threshold: 60 # 0-100. Raise to reduce noise; lower for maximum sensitivity.
channels:
- username: "channel_name"
name: "Display Name"
reliability_label: official # official / trusted / general
```
可以在内置的多语言关键词集之上添加自定义关键词：
```
keywords:
critical:
- "nuclear alert"
- "تحذير نووي"
```
## 警报格式
```
🚨 CRITICAL ALERT
━━━━━━━━━━━━━━━━━━━━
Source: Civil Defense
Risk Score: 90/100
Triggers: `evacuation`, `immediate`
Time: 2025-01-15 14:32:11 UTC
━━━━━━━━━━━━━━━━━━━━
[original message text, up to 500 chars]
━━━━━━━━━━━━━━━━━━━━
⚡ Take immediate protective action. Move to shelter NOW.
```
## 数字防线 — 个人保险库
在设备上加密存储您的个人标识符，并扫描数据泄露：
```
python run.py --vault # Add emails, passwords, usernames, keywords
python run.py --scan # One-shot scan right now
python run.py # Includes automatic scan every 6 hours
```
**如何保持安全：**
| 标识符 | 检查方法 | 离开您设备的内容 | 对 HIBP 可见的 IP？ |
|:-----------|:------------|:------------------------|:-------------------|
| 密码 | HIBP k-anonymity | 仅 SHA-1 哈希值的前 5 个字符 | 否（此处使用 clearnet 是安全的） |
| 电子邮件 | 通过 Tor 访问 HIBP | 您的电子邮件地址 | 否 — 被 Tor 隐藏 |
**Tor 电路隔离：** 您保险库中的每个身份都会通过 SOCKS5 stream isolation 获得独立的 Tor 电路。搜索两个电子邮件是无法被网络观察者关联起来的。
**“反向黑客”防护：**
- `aiohttp` 发起 HTTP 请求 —— 没有浏览器，不执行 JavaScript，无指纹追踪
- 即使通过 Tor 也强制执行 HTTPS 证书验证
- 无请求日志，无查询缓存 —— 每次扫描都是干净的会话
- 如果 Tor 未运行，电子邮件检查将被静默跳过（密码的 k-anon 检查仍然有效）
**Tor 设置（一次性）：**
```
# Linux / Raspberry Pi
sudo apt install tor && sudo systemctl start tor
# macOS
brew install tor && brew services start tor
# Windows：从 torproject.org 下载 Tor Browser 或 Expert Bundle
```
## 项目结构
```
guardiannode/
├── run.py Entry point
├── requirements.txt
├── config.example.yaml Config reference
├── guardian/
│ ├── crypto.py AES-256-GCM + PBKDF2 key derivation
│ ├── config.py Encrypted config load/save
│ ├── keywords.py Multilingual keyword sets (EN/AR/RU/UK/HE)
│ ├── scorer.py Risk scoring engine
│ ├── storage.py SQLite event log + deduplication
│ ├── notifier.py Telegram Bot API alert sender
│ ├── monitor.py Telethon real-time channel monitor
│ ├── setup_wizard.py Interactive first-time setup
│ └── main.py Async service loop
└── docs/
├── ARCHITECTURE.md
├── THREAT_INTEL.md
├── TELEGRAM_INTEGRATION.md
├── DIGITAL_PERIMETER.md
└── ROADMAP.md
```
## 路线图
**阶段 1（当前）：** 实时 Telegram 监控、关键词评分、加密配置、本地事件日志。
**阶段 2：** 集成本地 LLM（Ollama）以进行消息摘要，进行地理解析以计算与安全区域的距离。
**阶段 3：** 暗网监控（HIBP k-anonymity、基于 Tor 的爬虫）、网络入侵检测。
**阶段 4：** 离线韧性（SDR 无线电、LoRa）、P2P 可信节点警报共享、声学警报器检测。
## 架构与设计文档
请查看 [`/docs`](./docs/) 目录以获取完整的系统设计、威胁情报策略和数字防线规范。
标签：Python, 代码示例, 信息监控, 威胁情报, 开发者工具, 数据分析, 无后门, 逆向工具