IoTinkers-com/watchi
GitHub: IoTinkers-com/watchi
Watchi 是一个基于 AI 大模型和多源威胁情报的移动端反欺诈检测系统，帮助普通用户实时识别短信、邮件和图片中的钓鱼与欺诈威胁。
Stars: 0 | Forks: 0
# Watchi
**基于 AI 的欺诈检测与威胁分析系统**
[](https://opensource.org/licenses/MIT)
[](https://php.net)
[](https://laravel.com)
一款先进的移动优先安全应用程序，利用人工智能实时检测欺诈、网络钓鱼和恶意内容。Watchi 集成了多个威胁情报源，为市民提供可操作的安全洞察。
## 📋 目录
- [概述](#overview)
- [功能](#features)
- [架构](#architecture)
- [安装说明](#installation)
- [API 文档](#api-documentation)
- [使用场景](#use-cases)
- [开发](#development)
- [贡献](#contributing)
- [行为准则](#code-of-conduct)
- [许可证](#license)
## 🎯 概述
Watchi 是一个全面的欺诈检测平台，旨在保护用户免受各种形式的数字威胁。该系统使用先进的 AI 模型 分析消息、图像和内容中的欺诈模式，同时交叉引用多个威胁情报数据库。
### 核心能力
- **基于 AI 的分析**：使用机器学习进行实时欺诈检测
- **多源情报**：集成 CMF、CSIRT、PhishTank 和 URLhaus
- **移动优先设计**：通过 NativePHP 实现的原生移动应用
- **推送通知**：使用 Firebase Cloud Messaging 进行主动预警
- **风险评分**：定量风险评估（0-100 分制）
- **适老化的消息提示**：针对不同人群量身定制的解释说明
## ✨ 功能
### 核心功能
- **欺诈检测引擎**
- 分析短信和图像中的欺诈内容
- 使用 OCR 从图像中提取和处理文本
- 提供带有详细信号分析的风险评分
- **威胁情报集成**
- CMF (Chilean Financial Market Commission) 预警
- CSIRT (Computer Security Incident Response Team) 报告
- PhishTank 钓鱼数据库
- URLhaus 恶意 URL 存储库
- **移动应用程序**
- 相机抓拍用于实时分析
- 二维码扫描用于可疑链接检测
- 共享面板集成用于分析共享内容
- 离线分析历史记录
- **警报系统**
- 针对严重威胁的实时推送通知
- 基于严重程度的分类（低、中、高、严重）
- 基于过期时间的警报管理
- 面向市民的友好建议
### 技术特性
- **RESTful API**：版本化的 API 端点 (v1)
- **速率限制**：分析端点每分钟 30 个请求
- **安全的 Token 存储**：对 FCM token 进行 SHA256 哈希处理
- **分析历史**：所有分析的完整审计追踪
- **处理指标**：以毫秒为单位的性能跟踪
## 🏗️ 架构
### 技术栈
- **后端**：Laravel 13.7 (PHP 8.3+)
- **AI/ML**：Laravel AI 与 Anthropic Claude (claude-sonnet-4-5)
- **移动端**：NativePHP 3.2
- **推送通知**：Firebase Cloud Messaging (kreait/firebase-php)
- **数据库**：MySQL
- **前端**：Vite + TailwindCSS
### 系统组件
```
┌─────────────────┐
│ Mobile App │
│ (NativePHP) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Laravel API │
│ (v1 Endpoints)│
└────────┬────────┘
│
▼
┌─────────────────┐
│ AI Agent Layer │
│ (Claude + │
│ Tools) │
└────────┬────────┘
│
┌────┴────┬──────────┬──────────┬──────────┐
▼ ▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ CMF │ │ CSIRT │ │PhishTank│ │Urlhaus │ │ Manual │
│ Alerts │ │Reports │ │ │ │ │ │ Context│
└────────┘ └────────┘ └────────┘ └────────┘ └────────┘
```
### 数据模型
- **AnalysisRecord**：存储包含风险评分、信号和建议的分析结果
- **ThreatAlert**：管理来自各种来源的威胁情报
- **DeviceToken**：处理用于推送通知的 FCM token 注册
## 🚀 安装说明
### 前置条件
- PHP 8.3 或更高版本
- Composer
- Node.js 18+ 和 npm
- MySQL 8.0+
- Firebase 项目（用于推送通知）
### 安装步骤
```
# 克隆仓库
git clone https://github.com/yourusername/watchi.git
cd watchi
# 安装依赖
composer install
npm install
# 配置环境
cp .env.example .env
php artisan key:generate
# 在 .env 中配置数据库
# DB_DATABASE=watchi
# DB_USERNAME=your_username
# DB_PASSWORD=your_password
# 运行 migrations
php artisan migrate
# 填充演示数据（可选）
php artisan db:seed --class=DemoThreatAlertSeeder
# 构建 assets
npm run build
# 启动开发服务器
composer run dev
```
### 环境配置
关键环境变量：
```
APP_NAME=Watchi
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=watchi
DB_USERNAME=your_username
DB_PASSWORD=your_password
# Firebase 配置
FIREBASE_CREDENTIALS=path/to/service-account.json
FIREBASE_PROJECT_ID=your-project-id
# AI 配置
ANTHROPIC_API_KEY=your-anthropic-api-key
```
## 📚 API 文档
### Base URL
```
http://localhost:8000/api/v1
```
### 认证
目前，API 使用速率限制进行保护。未来版本将包含 JWT 认证。
### 端点
#### 1. 分析内容是否存在欺诈
分析文本或图像中的欺诈模式。
**端点：** `POST /api/v1/analyze`
**速率限制：** 每分钟 30 个请求
**请求体：**
```
{
"input": "URGENT: Your account has been compromised. Click here to verify: http://suspicious-site.com",
"source": "manual",
"age_group": "general"
}
```
**参数：**
| 参数 | 类型 | 是否必填 | 描述 |
|-----------|------|----------|-------------|
| input | string | 是 | 要分析的文本内容或 Base64 编码的图像 |
| source | string | 否 | 输入来源 (manual, camera, scan, share)。默认值：manual |
| age_group | string | 否 | 目标受众 (general, senior, teen)。默认值：general |
**响应 (200 OK)：**
```
{
"data": {
"verdict": "dangerous",
"risk_score": 85,
"signals": [
{
"type": "urgency_language",
"description": "Message uses urgent language to create panic",
"confidence": 0.9
},
{
"type": "suspicious_url",
"description": "Contains URL that doesn't match legitimate domain",
"confidence": 0.95
}
],
"sources": [
{
"name": "PhishTank",
"found": true,
"reference": "PT-2025-789"
},
{
"name": "CMF",
"found": false,
"reference": null
}
],
"citizen_message": "This message appears to be a phishing attempt. It uses urgent language and contains a suspicious link. Do not click on any links or provide personal information.",
"recommended_action": "block"
},
"meta": {
"processing_time_ms": 1247,
"analyzed_at": "2025-05-06T19:41:00.000000Z"
}
}
```
**响应 (500 Error)：**
```
{
"message": "Analysis failed",
"error": "AI service unavailable"
}
```
**cURL 示例：**
```
curl -X POST http://localhost:8000/api/v1/analyze \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"input": "URGENT: Your account has been compromised. Click here to verify",
"source": "manual",
"age_group": "general"
}'
```
**JavaScript 示例：**
```
const response = await fetch('http://localhost:8000/api/v1/analyze', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
},
body: JSON.stringify({
input: 'URGENT: Your account has been compromised',
source: 'manual',
age_group: 'general'
})
});
const result = await response.json();
console.log(result.data.verdict); // "dangerous"
console.log(result.data.risk_score); // 85
```
**Python 示例：**
```
import requests
response = requests.post(
'http://localhost:8000/api/v1/analyze',
json={
'input': 'URGENT: Your account has been compromised',
'source': 'manual',
'age_group': 'general'
},
headers={'Accept': 'application/json'}
)
result = response.json()
print(f"Verdict: {result['data']['verdict']}")
print(f"Risk Score: {result['data']['risk_score']}")
```
#### 2. 注册推送通知 Token
注册用于接收推送通知的设备 token。
**端点：** `POST /api/v1/push-token`
**请求体：**
```
{
"token": "fcm_device_token_here",
"platform": "ios"
}
```
**参数：**
| 参数 | 类型 | 是否必填 | 描述 |
|-----------|------|----------|-------------|
| token | string | 是 | FCM 设备 token |
| platform | string | 是 | 平台 (ios, android) |
**响应 (200 OK)：**
```
{
"registered": true
}
```
**cURL 示例：**
```
curl -X POST http://localhost:8000/api/v1/push-token \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"token": "fcm_device_token_here",
"platform": "ios"
}'
```
**JavaScript 示例：**
```
const response = await fetch('http://localhost:8000/api/v1/push-token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
},
body: JSON.stringify({
token: 'fcm_device_token_here',
platform: 'ios'
})
});
const result = await response.json();
console.log(result.registered); // true
```
### Verdict 值
| 值 | 描述 |
|-------|-------------|
| `safe` | 未检测到欺诈指标 |
| `suspicious` | 发现了一些可疑模式 |
| `dangerous` | 欺诈可能性较高 |
| `FRAUDE` | 已确认的欺诈内容 |
| `unknown` | 无法确定 |
### 建议操作
| 操作 | 描述 |
|--------|-------------|
| `none` | 无需采取任何行动 |
| `block` | 拉黑发送者/内容 |
| `report` | 向有关部门举报 |
| `verify` | 通过官方渠道进行核实 |
## 💡 使用场景
### 1. 短信钓鱼检测
**场景**：用户收到一条声称来自其银行的短信，要求其采取紧急行动。
**解决方案**：用户将消息分享给 Guachiman，系统会分析内容，对照威胁数据库进行检查，并提供带有明确建议的风险评估。
```
{
"input": "BANK ALERT: Your account will be blocked in 24h. Verify now: http://bank-security-verify.com",
"source": "share",
"age_group": "senior"
}
```
### 2. 二维码安全检查
**场景**：用户遇到一个承诺提供折扣或奖品的二维码。
**解决方案**：用户通过应用程序扫描二维码，系统会分析目标 URL 并与已知的恶意域名进行比对。
### 3. 电子邮件钓鱼分析
**场景**：企业安全团队需要分析可疑电子邮件。
**解决方案**：与电子邮件系统集成，自动分析传入的消息，为安全团队提供风险评分和详细的信号分析。
### 4. 基于图像的欺诈检测
**场景**：用户收到一张据称是官方通讯的截图。
**解决方案**：应用程序捕获图像，通过 OCR 提取文本，并在保留原始图像上下文的同时分析内容是否存在欺诈模式。
### 5. 主动威胁预警
**场景**：CSIRT 检测到针对老年用户的新型网络钓鱼活动。
**解决方案**：系统自动向受影响人群中已注册的用户发送推送通知，提供详细的指导和预防提示。
## 🔧 开发
### 运行测试
```
# 运行所有测试
composer test
# 运行特定 test suite
php artisan test --testsuite=Feature
# 运行并生成覆盖率
php artisan test --coverage
```
### 代码风格
```
# 使用 Laravel Pint 格式化代码
./vendor/bin/pint
# 运行静态分析
composer require larastan/larastan --dev
./vendor/bin/phpstan analyse
```
### 数据库迁移
```
# 创建新 migration
php artisan make:migration create_new_table
# 运行 migrations
php artisan migrate
# 回滚上一个 migration
php artisan migrate:rollback
# 带数据填充的全新 migration
php artisan migrate:fresh --seed
```
### 添加新的威胁源
要添加新的威胁情报源：
1. 在 `app/Ai/Tools/` 中创建一个新工具
2. 实现工具接口
3. 在 `FraudAnalysisAgent.php` 中注册该工具
4. 将枚举值添加到 `AlertSource.php`
示例：
```
namespace App\Ai\Tools;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Attributes\Description;
#[Description('Check custom threat database')]
class CheckCustomThreatTool implements Tool
{
public function execute(string $query): array
{
// Implementation
return ['found' => false, 'reference' => null];
}
}
```
### AI Agent 自定义
可以针对不同的用例自定义欺诈分析 Agent：
```
$agent = new FraudAnalysisAgent(
userAgeGroup: 'senior', // Tailored for elderly users
inputSource: 'camera', // Camera-captured content
externalContext: [ // Additional context
'location' => 'CL',
'language' => 'es'
]
);
$result = $agent->prompt($input);
```
## 🤝 贡献
我们欢迎对 Guachiman 的贡献！请遵循以下准则：
### 开发工作流
1. Fork 本仓库
2. 创建一个特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交带有明确提交信息的更改
4. 为新功能添加测试
5. 确保所有测试通过 (`composer test`)
6. 运行代码格式化 (`./vendor/bin/pint`)
7. 提交 Pull Request
### 提交信息格式
请遵循约定式提交：
```
feat: add new threat intelligence source
fix: resolve rate limiting issue
docs: update API documentation
test: add integration tests for analysis endpoint
```
### Pull Request 指南
- 描述更改及其动机
- 关联相关问题
- 确保代码符合项目风格指南
- 为新功能包含测试
- 根据需要更新文档
## 📜 行为准则
### 我们的承诺
为了营造一个开放和热情的环境，我们作为贡献者和维护者承诺：让每个人参与我们的项目和社区都能免受骚扰。
### 我们的标准
有助于营造积极环境的行为示例：
- 使用热情和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事物
- 对其他社区成员表现出同理心
不可接受的行为示例：
- 使用性暗示的语言或图像
- 人身攻击或侮辱性评论
- 捣乱、侮辱或贬损性评论
- 公开或私下骚扰
- 未经许可发布他人的私人信息
- 其他不道德或不专业的行为
### 责任
项目维护者有责任明确可接受行为的标准，并应在出现任何不可接受的行为时，采取适当和公平的纠正措施。
### 范围
本行为准则适用于所有项目空间，也适用于个人在公共空间代表项目或其社区时。
### 执行
可以通过向项目团队发送电子邮件至 [your-email@example.com] 来报告虐待、骚扰或其他不可接受的行为。所有投诉都将被审查和调查，并将根据具体情况做出必要的、适当的回应。
### 鸣谢
本行为准则改编自 [Contributor Covenant](https://www.contributor-covenant.org) 1.4 版。
## 📄 许可证
本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
### MIT 许可证摘要
特此免费授予任何获得本软件和相关文档文件（“软件”）副本的人不受限制地处理本软件的权利，
包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本的权利，
并允许向其提供本软件的人员在以下条件下这样做：
上述版权声明和本许可声明应包含在本软件的所有副本或主要部分中。
本软件按“原样”提供，不提供任何形式的保证，
无论是明示的还是暗示的，包括但不限于适销性、特定用途的适用性和非侵权的保证。
在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，
无论是在合同诉讼、侵权行为还是其他方面，由本软件或本软件的使用或其他交易所引起，
或与之相关。
## 📦 版本控制
Guachiman 遵循 [语义化版本 2.0.0](https://semver.org/)。
### 版本格式
给定版本号 MAJOR.MINOR.PATCH：
- **MAJOR**：不兼容的 API 更改
- **MINOR**：向后兼容的功能新增
- **PATCH**：向后兼容的错误修复
### 当前版本：0.1.0
该项目目前处于预发布阶段 (v0.x.x)，在发布 v1.0.0 之前，可能会在没有主版本号递增的情况下引入破坏性更改。
**用 ❤️ 构建以保护市民免受数字欺诈**
[GitHub](https://github.com/yourusername/watchi) •
[问题](https://github.com/yourusername/watchi/issues) •
[文档](https://github.com/yourusername/watchi/wiki)
标签：AI安全, Anthropic Claude, Apex, APP安全, Chat Copilot, CSIRT, DLL 劫持, ffuf, Firebase, Laravel, NativePHP, NLP, OCR文字识别, OpenVAS, PhishTank, PHP, URLhaus, 人工智能, 企业安全, 反诈骗, 图像分析, 大语言模型, 威胁分析, 威胁情报, 安全防护, 实时风控, 开发者工具, 恶意内容分析, 情报源整合, 推送通知, 搜索语句（dork）, 数字化防护, 智能风控, 机器学习, 欺诈检测, 深度学习, 用户模式Hook绕过, 目录枚举, 移动优先, 移动安全, 移动应用开发, 网络安全, 网络资产管理, 自动化侦查工具, 钓鱼检测, 隐私保护, 风控系统, 风险评分