gideonagbavor8/PhishPhalanx
GitHub: gideonagbavor8/PhishPhalanx
一个基于 Node.js 和 MongoDB Atlas 的企业级 CLI 工具，用于报告、追踪和管理钓鱼事件及域名黑名单。
Stars: 0 | Forks: 0
# PhishPhalanx – 威胁情报与钓鱼事件库
## 概述
PhishPhalanx 是一个企业级的威胁情报和钓鱼事件管理系统。该 CLI 应用程序使安全分析师能够：
- **报告钓鱼事件** 并进行严重性分类（低/中/高）
- **管理域名黑名单**，采用 SHA-256 散列和 MITRE ATT&CK 消除危险（Defang）规范
- **查询未解决的事件**，按危险级别过滤
- **跟踪事件状态**，贯穿工作流状态（open → investigating → closed）
- **移除误报**，带有确认对话框
- **执行实时黑名单查询** 以进行域名验证
所有数据持久化存储在基于云的 MongoDB Atlas 集群中，支持多团队协作以及对钓鱼活动的历史分析。
## 云数据库
选择 **MongoDB Atlas** 的原因如下：
- **灵活的 Schema**：文档存储嵌套的事件元数据，无需严格的表定义
- **可扩展性**：随着威胁情报的增加，可跨多个节点进行水平扩展
- **全球分布**：MongoDB Atlas 集群可跨区域部署，实现低延迟访问
- **安全性**：内置身份验证、静态加密和网络访问控制
- **索引**：使用索引查询，在 domainHash (SHA-256) 和 incidentId 字段上实现快速查找
- **TTL 集合**（未来）：旧事件自动过期，以符合合规/保留策略
**集合：**
- `incidents` – 带有严重性和状态跟踪的钓鱼事件报告
- `blacklists` – 带有 SHA-256 散列和消除危险 URL 的恶意域名
## 开发环境
**运行时与语言：**
- **Node.js** (v16+) – JavaScript 运行时环境
- **ECMAScript 6 (ES2022)** – 支持 async/await 的现代 JavaScript
**核心依赖：**
- **mongodb** (v6.20.0+) – Node.js 官方原生 MongoDB 驱动程序
- **dotenv** (v16.6.1) – 针对敏感凭证的环境变量管理
- **readline**（内置）– 基于终端的交互式提示
**开发工具：**
- **npm** – 包管理器和任务运行器
- **eslint** (.eslintrc.json) – 强制执行代码质量和风格规范
**架构：**
- **MVC 模式** – 分离模型（schema）、业务逻辑（incidents.js, blacklist.js）和 UI（index.js）
- **Async/Await** – 用于数据库操作的非阻塞 I/O
- **Try/Catch 错误处理** – 贯穿全局的优雅错误恢复
## 关系图
```
┌─────────────────────────────────────────────────────────────────┐
│ MongoDB Atlas (Cloud) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────┐ ┌──────────────────────────┐ │
│ │ incidents Collection │ │ blacklists Collection │ │
│ ├────────────────────────────┤ ├──────────────────────────┤ │
│ │ _id (ObjectId) │ │ _id (ObjectId) │ │
│ │ incidentId (String) │ │ domainHash (String) │ │
│ │ [Unique, Indexed] │ │ [Unique, Indexed] │ │
│ │ │ │ │ │
│ │ targetDomain (String) │ │ originalDomain (String) │ │
│ │ [Required] │ │ [Defanged Format] │ │
│ │ [e.g. evil[.]com] │ │ [e.g. hxxp://...] │ │
│ │ │ │ │ │
│ │ dangerLevel (Enum) │ │ addedAt (Date) │ │
│ │ [low | medium | high] │ │ [Timestamp] │ │
│ │ │ │ │ │
│ │ status (Enum) │ │ ──────────────────────── │ │
│ │ [open | investigating │ │ │ │
│ │ | closed] │ │ Example Document: │ │
│ │ │ │ { │ │
│ │ reporterEmail (String) │ │ _id: ObjectId(...), │ │
│ │ [Optional] │ │ domainHash: "abc123...",
│ │ │ │ originalDomain: │ │
│ │ timestamp (Date) │ │ "hxxp://evil[.]com", │ │
│ │ [Created Date] │ │ addedAt: 2026-05-27... │ │
│ │ │ │ } │ │
│ │ ──────────────────────────│ │ │ │
│ │ Example Document: │ └──────────────────────────┘ │
│ │ { │ │
│ │ _id: ObjectId(...), │ SHA-256 Hashing: │
│ │ incidentId: "INC-1001", │ Input: "evil.com" │
│ │ targetDomain: "hxxp://...", │ Output: 64-char hex │
│ │ dangerLevel: "high", │ Lookup: O(1) indexed search │
│ │ status: "open", │ │
│ │ reporterEmail: "...@...",│ Defanging Convention: │
│ │ timestamp: 2026-05-27...│ http → hxxp │
│ │ } │ . → [.] │
│ │ │ │
│ └────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Node.js CLI Application
(index.js)
↓
┌──────────────┐
│ Readline Menu│
└──────┬───────┘
│
┌─────────────────┼─────────────────┐
↓ ↓ ↓
incidents.js blacklist.js db.js
(CRUD Ops) (Hash & Check) (MongoDB Connection)
↓ ↓ ↓
[incidents] [blacklists] [Atlas Cluster]
Collection Collection
```
## 视频演示
(https://www.loom.com/share/de14306bd973422e8a828d2e7ddcae98)
## 安装与设置
### 前置条件
- Node.js v16 或更高版本
- npm（包含在 Node.js 中）
- MongoDB Atlas 账户和连接字符串
### 步骤
1. **克隆仓库：**
git clone https://github.com/gideonagbavor8/PhishPhalanx.git
cd PhishPhalanx
2. **安装依赖：**
npm install
3. **创建包含 MongoDB URI 的 `.env` 文件：**
echo "MONGODB_URI=mongodb+srv://:@.mongodb.net/phishphalanx" > .env
4. **播种样本数据（可选）：**
npm run seed
5. **启动交互式菜单：**
npm start
## 用法
### 主菜单选项
```
╔══════════════════════════════════════════════════════════╗
║ PhishPhalanx — Threat Intelligence ║
╠══════════════════════════════════════════════════════════╣
║ 1. Report a new phishing incident ║
║ 2. Look up a domain in the blacklist ║
║ 3. View open incidents by severity ║
║ 4. Update an incident status ║
║ 5. Delete a false positive incident ║
║ 6. Exit ║
╚══════════════════════════════════════════════════════════╝
```
### 示例工作流
**报告高严重性事件：**
```
Choice: 1
Domain: malicious-paypal.com
Severity: high
Email: analyst@company.com
→ Creates INC-XXXXX in MongoDB
```
**检查域名是否被列入黑名单：**
```
Choice: 2
Domain: hxxps://evil[.]com/login
→ ✅ Found in blacklist or ✅ Clean
```
**查看所有高严重性的未解决事件：**
```
Choice: 3
Level: high
→ Lists all incidents with dangerLevel=high and status=open
```
## 项目结构
```
PhishPhalanx/
├── index.js # Interactive CLI menu
├── package.json # Dependencies and scripts
├── .env # Environment variables (git-ignored)
├── .eslintrc.json # Code quality rules
├── README.md # This file
├── SECURITY.md # Security policy
│
└── src/
├── db.js # MongoDB connection management
├── seed.js # Database seeding script
├── incidents.js # Incident CRUD operations
├── blacklist.js # Domain blacklist operations
│
└── models/
├── Incident.js # Incident schema
└── Blacklist.js # Blacklist schema
```
## API 函数
### incidents.js
- `createIncident(data)` – 创建新事件
- `getIncident(incidentId)` – 获取单个事件
- `listIncidents(filters)` – 使用可选过滤器查询事件
- `updateIncidentStatus(incidentId, newStatus)` – 更新工作流状态
- `deleteIncident(incidentId)` – 移除事件
- `getIncidentsBySeverity(level)` – 按严重性查询未解决的事件
### blacklist.js
- `checkBlacklist(domain)` – 检查域名是否被列入黑名单
- `addToBlacklist(domain)` – 添加带有 SHA-256 散列的域名
- `removeBlacklistEntry(domain)` – 从黑名单中移除
- `normalizeDomain(rawDomain)` – 规范化域名格式
- `defangHostname(input)` – 应用 MITRE ATT&CK 消除危险（Defang）处理
- `hashDomain(value)` – 生成 SHA-256 散列
### db.js
- `connectDB()` – 建立 MongoDB Atlas 连接
- `closeDB()` – 优雅地关闭连接
## 错误处理
所有函数均实现了全面的错误处理：
```
try {
// Database operation
const result = await operation();
console.log('✅ Success:', result);
} catch (error) {
console.error('❌ Error:', error.message);
throw error;
}
```
**控制台反馈：**
- ✅ 带有操作详细信息的成功消息
- ⚠️ 针对边缘情况（未找到、无效输入）的警告
- ❌ 带有上下文的错误消息
- ℹ️ 信息提示消息
## 实用网站
- [MongoDB Atlas 文档](https://www.mongodb.com/docs/atlas/)
- [MongoDB Node.js 驱动程序文档](https://www.mongodb.com/docs/drivers/node/current/)
- [Node.js 文档](https://nodejs.org/en/docs)
- [MITRE ATT&CK 框架](https://attack.mitre.org/)
- [Node.js Readline 模块](https://nodejs.org/api/readline.html)
- [SHA-256 散列](https://en.wikipedia.org/wiki/SHA-2)
## 未来工作
- [ ] 添加用户身份验证和基于角色的访问控制 (RBAC)
- [ ] 构建用于事件可视化的 Web 仪表板（React/Vue）
- [ ] 集成实时威胁情报 API 订阅源（VirusTotal、AlienVault）
- [ ] 实现事件升级工作流
- [ ] 为 CSV 事件日志添加批量导入/导出功能
- [ ] 针对高严重性事件的电子邮件通知
- [ ] 历史分析和趋势报告
- [ ] 与 SIEM 系统集成（Splunk、ELK Stack）
- [ ] 用于随时随地进行事件报告的移动应用程序
- [ ] 用于自动严重性检测的机器学习分类器
## 许可证
MIT 许可证
## 支持
如有问题、疑问或建议：
- 在 GitHub 上提 issue
- 联系方式：gideonagbavor8@gmail.com
- 安全问题：参见 [SECURITY.md](SECURITY.md)
**PhishPhalanx — 抵御钓鱼攻击，逐个击破事件** 🛡️
标签：GNU通用公共许可证, MITM代理, MongoDB, Node.js, PB级数据处理, 威胁情报, 安全运维, 开发者工具, 暗色界面, 自定义脚本