Diyaprg/Hack4IMPACTTrack2-DATA-DEFENDERS
GitHub: Diyaprg/Hack4IMPACTTrack2-DATA-DEFENDERS
面向印度 UPI 生态系统的自主网络威胁情报平台，通过实时监控诈骗渠道并结合多语言 NLP 与图神经网络，在资金损失前主动检测并预警金融欺诈活动。
Stars: 0 | Forks: 0
# SurakshAI — 自主网络威胁情报平台
## 👥 团队：Data Defenders
| 角色 | 姓名 | 邮箱 | 所属机构 |
|------|------|-------|-------------|
| 团队负责人 | Diya Pandey | 24051548@kiit.ac.in | KIIT Bhubaneswar |
| 成员 2 | Ankit Singh | 2430012@kiit.ac.in | KIIT Bhubaneswar |
| 成员 3 | Ayush Mishra | 23053036@kiit.ac.in | KIIT Bhubaneswar |
| 成员 4 | Shourya Bhardowaj | 2430121@kiit.ac.in | KIIT Bhubaneswar |
## 🏷️ 领域
网络安全与伦理 AI 系统
## 📌 问题陈述
**SurakshAI — 面向印度 UPI 生态系统的自主网络威胁情报平台**
印度每年因针对 UPI 用户的 AI 驱动金融诈骗损失超过 2000 亿卢比，这些诈骗手段包括深度伪造名人视频、语音克隆的家庭紧急情况以及协同的 WhatsApp 欺诈活动。超过 47% 的印度成年人曾亲身经历或认识受害者。
现有的网络安全基础设施 —— CERT-In、RBI 和银行欺诈团队 —— 完全是被动反应式的，仅在资金被转移后才检测到欺诈。目前不存在任何主动系统，能够实时监控诈骗协同渠道，绘制活动背后的犯罪运营者网络，并在攻击大规模波及受害者之前向金融机构发出警报。
议会通信与信息技术常设委员会在 2025 年 8 月指出了这一具体缺口 —— 且至今仍未解决。
## 💡 提议的解决方案
SurakshAI 是一个实时网络威胁情报平台，能够在欺诈活动触及受害者之前检测到它们。该系统分三层运行：
- **采集层 (Ingestion Layer)** — 使用 Telegram API 持续监控 Telegram 频道和 OSINT 来源，获取针对印度的诈骗内容。
- **AI 层 (AI Layer)** — 使用多语言 NLP 模型对威胁进行分类，利用图神经网络 (GraphSAGE) 绘制犯罪运营者网络，并使用 DBSCAN 将相关信息聚类为命名活动。
- **预警层 (Alert Layer)** — 当活动的严重程度超过阈值时，自动向 CERT-In 和 RBI 监管的银行发送结构化威胁情报。
公民可以通过公共门户验证任何可疑的电话号码、UPI ID 或视频链接，并在 2 秒内获得欺诈概率评分。
## 🏗️ 完整后端架构
### 概述
后端是一个由 8 个模块组成的 Python FastAPI 应用程序。每个组件具有单一职责。数据单向流动：采集 → 分类 → 图谱 → 检测 → 预警。
```
suraksh-ai-backend/
│
├── main.py ← FastAPI app entry point, lifespan, all routes mounted
│
├── core/
│ ├── config.py ← All env vars, constants, settings (single source of truth)
│ ├── database.py ← PocketBase wrapper — all DB reads/writes
│ └── scheduler.py ← APScheduler — campaign detection every 10min
│
├── ingestion/
│ ├── telegram_scraper.py ← Telethon async listener — monitors fraud channels live
│ ├── osint_scraper.py ← Scheduled OSINT scraper + demo threat injector
│ └── pipeline.py ← Normaliser — every message flows through here
│
├── ai/
│ ├── entity_extractor.py ← Regex + keyword — extracts phones, UPI IDs, handles
│ ├── classifier.py ← Multilingual BERT threat classifier (keyword fallback)
│ ├── groq_client.py ← Groq API wrapper — LLaMA 3.1 70B for edge cases
│ ├── graph_builder.py ← NetworkX operator network graph (in-memory + persisted)
│ ├── campaign_detector.py ← DBSCAN clustering — groups threats into campaigns
│ └── deepfake_detector.py ← EfficientNet-B4 video frame analyser
│
├── alerts/
│ ├── engine.py ← Severity threshold checker — fires alert at 0.82+
│ ├── bank_webhooks.py ← Async httpx — concurrent POST to bank endpoints
│ └── certin_reporter.py ← Generates CERT-In formatted incident reports
│
├── api/
│ └── routes/
│ ├── threats.py ← GET /threats, GET /threats/:id
│ ├── campaigns.py ← GET /campaigns, GET /campaigns/:id, GET /campaigns/:id/network
│ ├── alerts.py ← GET /alerts, GET /alerts/:id
│ ├── verify.py ← POST /verify (phone / UPI / video)
│ ├── network.py ← GET /network/graph, GET /network/stats
│ └── stats.py ← GET /stats (live dashboard counters)
│
├── models/
│ ├── threat.py ← Pydantic schemas for threat objects
│ ├── campaign.py ← Pydantic schemas for campaign objects
│ ├── alert.py ← Pydantic schemas for alert objects
│ └── verify.py ← Pydantic schemas for verify request/response
│
├── scripts/
│ └── seed_demo_data.py ← Seeds 3 campaigns, 25 threats, 2 alerts for demo
│
├── .env.example ← Environment variable template (safe to share)
├── requirements.txt ← All Python dependencies
└── Procfile ← Railway deployment config
```
### 数据流 —— 端到端
```
Telegram Channel / OSINT Source
│
▼
ingestion/telegram_scraper.py (Telethon async listener)
│
▼
ingestion/pipeline.py (normalise raw text → structured object)
│
├──► ai/entity_extractor.py (extract phones, UPI IDs, Telegram handles)
│
├──► ai/classifier.py (BERT → category + confidence score)
│ └── fallback: ai/groq_client.py (LLaMA 3.1 70B)
│
├──► ai/graph_builder.py (add entities as nodes, co-occurrence as edges)
│
└──► core/database.py (write threat to PocketBase)
│
▼ (every 10 minutes via APScheduler)
ai/campaign_detector.py (TF-IDF → DBSCAN → campaign objects)
│
▼
alerts/engine.py (score >= 0.82 → fire alert)
│
├──► alerts/bank_webhooks.py (async POST to SBI/HDFC/Paytm/PhonePe)
└──► alerts/certin_reporter.py (CERT-In formatted JSON report)
```
### API 端点 —— 完整参考
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/` | 健康检查 —— 确认服务器运行正常 |
| GET | `/stats` | 实时仪表板计数 —— 威胁、活动、警报、威胁等级 |
| GET | `/threats` | 分页威胁列表，支持筛选 (category, state, min_confidence) |
| GET | `/threats/:id` | 单个威胁的完整详情 |
| GET | `/campaigns` | 所有活动，支持筛选 (status, severity) |
| GET | `/campaigns/:id` | 单个活动的完整详情 |
| GET | `/campaigns/:id/threats` | 属于某活动的所有威胁 |
| GET | `/campaigns/:id/network` | 某活动的运营者网络子图 |
| GET | `/alerts` | 完整警报历史 |
| GET | `/alerts/:id` | 单个警报及完整 CERT-In 负载 |
| GET | `/network/graph` | 用于 D3 力导向图的完整节点-边 JSON |
| GET | `/network/stats` | 图谱统计信息（按类型节点计数） |
| POST | `/verify` | 公民验证 —— 电话 / UPI / 视频 URL |
| POST | `/ingest/manual` | 手动注入威胁消息 |
| POST | `/trigger/test` | 触发演示威胁 + 运行活动检测（评委演示） |
| POST | `/mock/bank/:name` | 模拟银行 webhook 接收器 |
| POST | `/mock/certin` | 模拟 CERT-In webhook 接收器 |
### AI 组件 —— 技术细节
#### 1. NLP 威胁分类器 (`ai/classifier.py`)
- 模型：通过 HuggingFace Transformers 加载的 `bert-base-multilingual-cased`
- 支持语言：印地语、英语、Hinglish
- 类别：`investment_scam` (投资诈骗), `voice_clone` (语音克隆), `fake_upi_refund` (虚假 UPI 退款), `phishing` (钓鱼), `mule_recruitment` (骡子账户招募), `deepfake_celebrity` (深度伪造名人), `lottery_scam` (彩票诈骗), `unknown` (未知)
- 回退机制：当 BERT 置信度 < 0.75 时使用基于关键字的分类器
- 边缘情况：使用 Groq API (LLaMA 3.1 70B) 处理模糊消息
- 推理时间：每条约 180ms（模型在启动时加载到内存中）
#### 2. 实体提取器 (`ai/entity_extractor.py`)
- 提取对象：印度电话号码（所有格式）、UPI ID、Telegram 账号、URL
- 位置检测：通过关键字映射识别 20 个印度邦
- 诈骗关键字映射：7 个类别 × 每个类别 10+ 个关键字（印地语 + 英语）
- 输出：包含原始消息文本中发现的所有实体的结构化字典
#### 3. 运营者网络图谱 (`ai/graph_builder.py`)
- 库：NetworkX DiGraph（内存中，每 5 分钟持久化到 PocketBase）
- 节点：电话号码、UPI ID、Telegram 账户、活动引用
- 边：同一消息中共现（权重 +1）、同一活动关联
- 中心性：在每次 check_entity 调用时计算度中心性
- 欺诈评分：`0.3 + (campaigns × 0.25) + (centrality × 0.5)`，上限为 0.99
#### 4. 活动检测器 (`ai/campaign_detector.py`)
- 算法：基于 TF-IDF 向量的 DBSCAN (eps=0.3, min_samples=2, cosine metric)
- 调度：通过 APScheduler 每 10 分钟运行一次
- 窗口：置信度高于 0.5 的最近 200 个威胁
- 输出：带有严重程度、目标邦、运营者数量的命名活动对象
- 严重程度评分：使用威胁数量、平均置信度、受影响邦的加权公式
#### 5. 深度伪造检测器 (`ai/deepfake_detector.py`)
- 模型：在 FaceForensics++ 数据集上微调的 EfficientNet-B4
- 视频摄取：yt-dlp（前 10 秒），通过 OpenCV 提取 30 帧
- 回退机制：当 PyTorch 不可用时使用启发式分析器（模糊方差 + 色彩饱和度）
- 输出：欺诈概率、可疑帧时间戳、人类可读原因
#### 6. Groq LLM 集成 (`ai/groq_client.py`)
- 模型：`llama-3.1-70b-versatile`
- 用途：边缘情况威胁分类、活动摘要生成、警报负载摘要
- 速率限制：免费层 30 请求/分钟 —— 仅用于回退和摘要，不用于每条消息
### 数据库 Schema —— PocketBase 集合
#### threats
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| raw_text | text | 原始消息内容（最多 2000 字符） |
| source | text | telegram / osint / manual |
| channel_id | text | Telegram 频道 ID |
| channel_name | text | 人类可读的频道名称 |
| category | text | 已分类的威胁类型 |
| confidence | number | 分类置信度 0.0–1.0 |
| target_states | json | 提及的印度邦列表 |
| entities | json | 提取的电话、UPI ID、账号 |
| campaign_id | text | 关联的活动 ID（如果已聚类） |
| ingested_at | text | 采集的 ISO 时间戳 |
#### campaigns
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| name | text | 自动生成的活动名称 |
| category | text | 主要威胁类别 |
| severity | text | critical / high / medium / low |
| status | text | active / monitoring / neutralised |
| target_states | json | 活动针对的所有邦 |
| threat_count | number | 聚类中的威胁数量 |
| score | number | 严重程度评分 0.0–1.0 |
| summary | text | LLM 生成的活动摘要 |
| alert_fired | bool | 是否已发送银行警报 |
| operator_count | number | 已识别的运营者实体数量 |
| first_detected | text | 首次检测到的 ISO 时间戳 |
#### alerts
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| campaign_id | text | 关联的活动 ID |
| campaign_name | text | 人类可读的活动名称 |
| risk_level | text | critical / high / medium / low |
| banks_notified | json | 接收警报的银行列表 |
| certin_notified | bool | 是否已通知 CERT-In |
| payload | json | 完整的 CERT-In 格式报告 |
| status | text | delivered / partial / failed |
| estimated_amount_protected_cr | number | 预估受保护金额（千万卢比） |
#### graph_snapshots
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| data | text | 完整 NetworkX 图谱的序列化 JSON |
#### operator_network
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| node_id | text | 唯一节点标识符 |
| type | text | phone / upi / telegram / campaign |
| value | text | 实际实体值 |
| degree | number | 连接数量 |
### 启动序列
当运行 `python main.py` 时，将按顺序发生以下情况：
```
1. PocketBase authenticates
2. BERT multilingual classifier loads into memory
3. EfficientNet deepfake model loads into memory
4. Operator network graph loads from PocketBase (or starts fresh)
5. APScheduler starts (campaign detection every 10min, graph persist every 5min)
6. Telegram client connects (asks for OTP on first run, session saved after)
7. FastAPI server starts on port 8000
8. All 17 API endpoints are live
```
### 环境变量
将 `.env.example` 复制为 `.env` 并填入您自己的值：
```
APP_NAME=SurakshAI
APP_ENV=development
APP_PORT=8000
FRONTEND_URL=http://localhost:5173
POCKETBASE_URL=http://127.0.0.1:8090
POCKETBASE_ADMIN_EMAIL=admin@suraksh.ai
POCKETBASE_ADMIN_PASSWORD=suraksh_admin_2026
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.1-70b-versatile
TELEGRAM_API_ID=your_telegram_api_id
TELEGRAM_API_HASH=your_telegram_api_hash
TELEGRAM_SESSION_NAME=suraksh_session
SEVERITY_THRESHOLD=0.82
ALERT_RETRY_ATTEMPTS=3
ALERT_RETRY_DELAY=2
BANK_SBI_WEBHOOK=http://localhost:8000/mock/bank/sbi
BANK_HDFC_WEBHOOK=http://localhost:8000/mock/bank/hdfc
BANK_PAYTM_WEBHOOK=http://localhost:8000/mock/bank/paytm
BANK_PHONEPE_WEBHOOK=http://localhost:8000/mock/bank/phonepe
CERTIN_WEBHOOK=http://localhost:8000/mock/certin
BERT_MODEL=bert-base-multilingual-cased
DEEPFAKE_MODEL_PATH=models/deepfake_efficientnet.pth
GNN_MODEL_PATH=models/graphsage.pth
```
## 🛠️ 前置条件 —— 先安装这些
| 工具 | 版本 | 下载地址 |
|------|---------|----------|
| Python | 3.12+ | python.org/downloads — 勾选 "Add to PATH" |
| Node.js | LTS | nodejs.org/en/download |
| Git | Latest | git-scm.com/downloads |
| PocketBase | Latest | pocketbase.io/docs |
## ⚙️ 设置指南
### 步骤 1 —— PocketBase 设置
```
# Windows
cd pocketbase
pocketbase.exe serve
# Mac/Linux
cd pocketbase
./pocketbase serve
```
打开 `http://127.0.0.1:8090` → 创建管理员账户：
- Email: `admin@suraksh.ai`
- Password: `suraksh_admin_2026`
在管理 UI 中创建这 5 个集合 (Collections → New collection)：
| 集合 | 字段 |
|---|---|
| `threats` | raw_text, source, channel_id, channel_name, category (text) · confidence (number) · target_states, entities (json) · campaign_id, ingested_at (text) |
| `campaigns` | name, category, severity, status (text) · target_states, (json) · threat_count, score, operator_count (number) · summary, first_detected (text) · alert_fired (bool) |
| `alerts` | campaign_id, campaign_name, risk_level, status (text) · banks_notified, payload (json) · estimated_amount_protected_cr (number) · certin_notified (bool) |
| `graph_snapshots` | data (text) |
| `operator_network` | node_id, type, value (text) · degree (number) |
**重要：** 将每个集合的所有 API rules 设置为空字符串（API Rules 选项卡 → 清除所有字段 → Save）。
### 步骤 2 —— 后端设置
```
cd backend
# 创建虚拟环境
python -m venv venv
# 激活
# Windows:
venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate
# 安装所有依赖
pip install fastapi uvicorn python-dotenv httpx pydantic apscheduler
pip install transformers torch scikit-learn pandas numpy
pip install networkx groq pocketbase loguru slowapi
pip install telethon yt-dlp opencv-python-headless Pillow
pip install spacy pydantic-settings
```
### 步骤 3 —— 获取您的 API Keys
**Groq API Key (免费):**
1. 访问 `console.groq.com`
2. 注册 → API Keys → Create API Key
3. 复制以 `gsk_...` 开头的密钥
**Telegram API 凭证 (免费):**
1. 访问 `my.telegram.org`
2. 使用您的手机号码登录
3. 点击 "API development tools"
4. 填写表单 → App title: SurakshAI, Platform: Other
5. 复制 `api_id` (数字 和 `api_hash` (长字符串)
### 步骤 4 —— 配置环境
```
# 复制模板
cp .env.example .env
# 打开 .env 并填写：
# GROQ_API_KEY=gsk_your_key_here
# TELEGRAM_API_ID=12345678
# TELEGRAM_API_HASH=abcdef1234567890
```
### 步骤 5 —— 运行后端
```
python main.py
```
仅首次运行 —— Telegram 将提示：
```
Please enter your phone (+91XXXXXXXXXX):
Please enter the code you received: 12345
```
输入您的手机号码和 Telegram 应用中的 OTP。将创建一个 `suraksh_session.session` 文件 —— 之后无需再次执行。
确认后端正在运行：
```
http://localhost:8000 → {"status": "operational"}
http://localhost:8000/docs → Interactive API documentation
```
### 步骤 6 —— 填充演示数据
打开第二个终端（激活 venv 后）：
```
python scripts/seed_demo_data.py
```
将填充 3 个活动、25 个威胁、2 个警报以及一个已填充的运营者网络图谱。您的仪表板看起来将像一个已运行生产环境 2 天的系统。
## 🧪 API 测试 (Postman)
用于验证一切正常运行的关键端点：
```
GET http://localhost:8000/ → health check
GET http://localhost:8000/stats → live counters
POST http://localhost:8000/ingest/manual → inject test threat
POST http://localhost:8000/trigger/test → fire full demo pipeline
GET http://localhost:8000/threats → list all threats
GET http://localhost:8000/campaigns → list all campaigns
GET http://localhost:8000/alerts → list all alerts
POST http://localhost:8000/verify → citizen verification
GET http://localhost:8000/network/graph → operator network JSON
```
前端说明即将推出
标签：AI安全, Apex, Chat Copilot, DBSCAN, ESC4, GraphSAGE, Hack4Impact, HTTP/HTTPS抓包, IP 地址批量处理, KIIT, NLP, OSINT, SurakshAI, Telegram监控, UPI支付安全, 人工智能, 凭据扫描, 印度数字支付, 反欺诈, 图神经网络, 多语言模型, 实时监测, 态势感知, 文本分类, 机器学习, 深度伪造检测, 特权检测, 犯罪网络图谱, 用户模式Hook绕过, 社会工程学防御, 系统调用监控, 网络威胁情报, 网络安全, 聚类分析, 自主防御平台, 自定义脚本, 语音克隆诈骗, 逆向工具, 金融科技, 隐私保护, 风险预警