TRINETRA936/sentinel-ai-security-platform
GitHub: TRINETRA936/sentinel-ai-security-platform
Sentinel AI 是一个集成 VirusTotal API 和 AI 威胁分析的 Web 恶意软件分析平台，帮助安全团队快速检测恶意文件并生成安全报告。
Stars: 0 | Forks: 0
# ================================================================================
SENTINEL AI 安全平台
企业级恶意软件分析系统
版本：1.0.0
发布日期：2024 年 7 月 10 日
作者：Sentinel AI Team
许可证：MIT
# ================================================================================
目录
1. 概述
2. 功能
3. 技术栈
4. 安装
5. 配置
6. 项目结构
7. 使用指南
8. API 文档
9. 测试
10. 故障排除
11. 安全最佳实践
12. 性能优化
13. 贡献
14. 许可证
15. 联系与支持
================================================================================
1. 概述
================================================================================
Sentinel AI 安全平台是一个全面的、生产就绪的基于 Web 的恶意软件分析系统，它结合了 VirusTotal API 集成与 AI 驱动的威胁检测。它通过直观的仪表板界面提供实时的文件扫描、威胁分类和详细的安全报告。
## 核心功能：
- 实时文件扫描：使用 VirusTotal 广泛的防病毒引擎数据库上传和分析文件
- AI 驱动的威胁分析：高级威胁分类和风险评估
- 综合报告：生成包含可操作安全建议的详细 PDF 报告
- 交互式仪表板：实时统计数据、威胁时间线和分布可视化
- 双模式操作：支持使用真实 API 或测试用的演示模式运行
# ================================================================================
2. 功能
## 仪表板分析：
- 实时统计：已扫描文件、检测到的威胁、风险细分
- 威胁时间线：扫描活动的可视化表示
- 威胁分布：显示威胁级别分布的饼图
- 自动刷新：仪表板每 30 秒更新一次
## 文件分析：
- 多文件支持：支持 EXE、DLL、PDF、DOC、ZIP、APK 等 30 多种格式
- 拖放：直观的文件上传界面
- 后台处理：带有任务队列的异步扫描
- 重复检测：基于哈希的自动去重
## 威胁检测：
- 风险评分：0-100% 风险评估
- 恶意软件分类：识别恶意软件家族（木马、勒索软件等）
- 检测统计：多个防病毒引擎检测结果的详细细分
- 行为分析：可疑模式检测
## 报告：
- PDF 报告：包含建议的综合安全报告
- 检测详情：防病毒引擎结果的完整细分
- 报告历史：访问以前的扫描报告
- 导出功能：下载报告以备存档
# ================================================================================
3. 技术栈
## 后端：
- Python 3.8+
- Flask 2.3.2 - Web 框架
- SQLAlchemy 3.0.5 - 用于数据库操作的 ORM
- Flask-CORS 4.0.0 - 跨域资源共享
- Python-dotenv 1.0.0 - 环境变量管理
- Requests 2.31.0 - 用于 API 调用的 HTTP 客户端
- ReportLab 4.0.4 - PDF 报告生成
## 前端：
- HTML5 - 结构
- CSS3 - 自定义暗色主题样式
- JavaScript - 交互功能
- Chart.js - 数据可视化
- Font Awesome - 图标
## 数据库：
- SQLite - 轻量级数据库
- SQLAlchemy ORM - 数据库抽象
# ================================================================================
4. 安装
## 前置条件：
- Python 3.8 或更高版本
- pip (Python 包安装器)
- Git（可选，用于克隆）
## 分步安装指南：
1. 克隆仓库：
git clone https://github.com/TRINETRA936/sentinel-ai-platform.git
cd sentinel-ai-platform
2. 创建虚拟环境：
Windows
python -m venv venv
venv\Scripts\activate
Linux/Mac
python3 -m venv venv
source venv/bin/activate
3. 安装依赖项：
pip install -r requirements.txt
4. 配置环境变量：
在项目根目录下创建一个 `.env` 文件，内容如下：
VirusTotal API Key（可选 - 演示模式无需此项即可运行）
VIRUSTOTAL_API_KEY=your_api_key_here
Flask 配置
SECRET_KEY=your-secret-key-here
DEBUG=True
HOST=0.0.0.0
PORT=5000
文件上传设置
MAX_CONTENT_LENGTH=104857600
ALLOWED_EXTENSIONS=exe,dll,doc,pdf,zip,rar,jar,apk,txt,com,bat,scr,ps1,py,js,vbs,docx,xlsx,ppt,pptx,7z,gz,tar,html,css,jpg,png,gif,iso,bin,msi
5. 创建所需目录：
mkdir uploads reports database
6. 运行应用程序：
python app.py
7. 访问仪表板：
打开浏览器并访问：http://localhost:5000
# ================================================================================
5. 配置
## 环境变量（.env 文件）：
VIRUSTOTAL_API_KEY
- 描述：用于真实扫描的 VirusTotal API key
- 默认值：None（演示模式）
- 必需：否
SECRET_KEY
- 描述：Flask 应用程序 secret key
- 默认值：default-secret-key-change-this
- 必需：是
DEBUG
- 描述：启用/禁用调试模式
- 默认值：True
- 选项：True, False
HOST
- 描述：要绑定服务器的 host 地址
- 默认值：0.0.0.0
- 选项：0.0.0.0, 127.0.0.1 等
PORT
- 描述：运行服务器的 port
- 默认值：5000
- 选项：任何有效的 port 号
MAX_CONTENT_LENGTH
- 描述：最大文件上传大小（以字节为单位）
- 默认值：104857600 (100MB)
- 选项：任何整数值
ALLOWED_EXTENSIONS
- 描述：允许的文件扩展名列表（以逗号分隔）
- 默认值：exe,dll,doc,pdf,zip,rar,jar,apk,txt,com,bat,scr,ps1,py,js,vbs
- 选项：任何有效的文件扩展名
DATABASE_PATH
- 描述：SQLite 数据库文件的路径
- 默认值：database/scans.db
- 选项：任何有效的文件路径
REPORT_PATH
- 描述：PDF 报告的目录
- 默认值：reports/
- 选项：任何有效的目录路径
# ================================================================================
6. 项目结构
sentinel-ai-platform/
├── app.py # Main Flask application
├── requirements.txt # Python dependencies
├── .env # Environment variables
├── backend/ # Backend modules
│ ├── __init__.py
│ ├── scanner.py # VirusTotal API integration
│ ├── threat_analyzer.py # AI-powered threat classification
│ └── report_generator.py # PDF report generation
├── frontend/ # Frontend files
│ ├── templates/
│ │ └── dashboard.html # Main dashboard HTML
│ └── static/
│ ├── css/
│ │ └── style.css # Custom styling
│ └── js/
│ └── dashboard.js # Interactive functionality
├── database/ # SQLite database
│ └── scans.db
├── uploads/ # Temporary upload directory
├── reports/ # Generated PDF reports
└── README.md # Project documentation
# ================================================================================
7. 使用指南
## 上传文件：
Web 界面：
1. 点击上传区域或拖放文件
2. 从您的计算机中选择一个文件
3. 等待上传完成
4. 该文件将被加入扫描队列
API (cURL)：
curl -X POST http://localhost:5000/api/upload \
-F "file=@/path/to/your/file.exe"
API (Python)：
import requests
files = {'file': open('file.exe', 'rb')}
response = requests.post('http://localhost:5000/api/upload', files=files)
print(response.json())
## 查看结果：
仪表板：
- 最近分析：查看所有已扫描的文件
- 统计数据：自动更新的实时指标
- 威胁时间线：查看一段时间内的扫描活动
- 威胁分布：威胁级别的可视化细分
详细视图：
1. 点击最近分析列表中的任何文件
2. 查看综合检测结果
3. 下载 PDF 报告
## 生成报告：
通过仪表板：
1. 点击任何报告旁边的下载图标
2. PDF 报告将自动下载
通过 API：
curl http://localhost:5000/api/report/1 --output report.pdf
# ================================================================================
8. API 文档
## ENDPOINTS：
GET /
- 描述：返回主仪表板 HTML 页面
- 身份验证：无
- 响应：HTML 页面
GET /api/dashboard/stats
- 描述：返回仪表板统计数据
- 身份验证：无
- 响应：JSON
{
"success": true,
"data": {
"total_scans": 150,
"threats_detected": 45,
"high_risk": 12,
"critical_risk": 3,
"recent_scans": [...],
"scan_timeline": [...],
"threat_distribution": [...]
}
}
POST /api/upload
- 描述：上传文件进行扫描
- 身份验证：无
- 参数：file (multipart/form-data)
- 响应：JSON
{
"success": true,
"message": "File queued for scanning",
"file_hash": "5e884898da280471...",
"filename": "example.exe"
}
GET /api/scan/
- 描述：获取特定扫描的详细信息
- 身份验证：无
- 参数：scan_id (integer)
- 响应：JSON
{
"success": true,
"result": {
"id": 1,
"filename": "example.exe",
"file_hash": "5e884898da280471...",
"risk_score": 89,
"malware_family": "Trojan",
"status": "High Risk",
"threat_level": "Critical",
"detections": {...},
"report_path": "reports/security_report_20260710.pdf"
}
}
GET /api/report/
- 描述：下载扫描的 PDF 报告
- 身份验证：无
- 参数：scan_id (integer)
- 响应：PDF 文件
DELETE /api/delete/
- 描述：删除扫描记录及其关联的报告
- 身份验证：无
- 参数：scan_id (integer)
- 响应：JSON
{
"success": true,
"message": "Scan deleted"
}
# ================================================================================
9. 测试
## 创建测试文件：
## Python 脚本 (create_test_files.py)：
test_files = {
'test.txt': 'This is a safe test file',
'test.exe': 'This simulates an executable',
'test.pdf': 'This simulates a PDF document',
'test.zip': 'This simulates a ZIP archive',
}
for filename, content in test_files.items():
with open(filename, 'w') as f:
f.write(content)
## EICAR 测试文件（防病毒检测）：
echo 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' > eicar.com
## GTUBE 测试文件（垃圾邮件检测）：
echo 'XJS*C4JDBQADN1.NSBN3*2IDNEN*GTUBE-STANDARD-ANTI-UBE-TEST-EMAIL*C.34X' > gtube.txt
## 测试上传：
基本上传：
curl -X POST http://localhost:5000/api/upload -F "file=@test.txt"
上传 EICAR：
curl -X POST http://localhost:5000/api/upload -F "file=@eicar.com"
上传 GTUBE：
curl -X POST http://localhost:5000/api/upload -F "file=@gtube.txt"
检查统计数据：
curl http://localhost:5000/api/dashboard/stats
下载报告（将 1 替换为实际的扫描 ID）：
curl http://localhost:5000/api/report/1 --output report.pdf
## 预期结果：
EICAR 测试文件：
- 检测计数：58/70 引擎
- 风险评分：45-55%
- 威胁级别：Medium
- 状态：Medium Risk
- 恶意软件家族：EICAR Test
GTUBE 测试文件：
- 检测计数：0/70 引擎
- 风险评分：0-10%
- 威胁级别：Safe
- 状态：Safe
- 恶意软件家族：Unknown
常规文件（例如，.txt）：
- 检测计数：0/70 引擎
- 风险评分：0-10%
- 威胁级别：Safe
- 状态：Safe
- 恶意软件家族：Unknown
#===============
10. 故障排除
## 常见问题及解决方案：
1. 数据库连接错误
错误：sqlite3.OperationalError: unable to open database file
解决方案：确保数据库目录存在并具有写入权限
mkdir -p database
chmod 755 database
2. 模块导入错误
错误：ModuleNotFoundError: No module named 'magic'
解决方案：移除 python-magic 依赖项或安装它
pip install python-magic-bin # Windows
pip install python-magic # Linux/Mac
3. 文件上传 400 错误
错误：400 Bad Request on file upload
解决方案：
- 检查文件扩展名是否在 ALLOWED_EXTENSIONS 中
- 确保文件大小在 MAX_CONTENT_LENGTH 限制内
- 验证文件不为空
4. 唯一约束错误
错误：UNIQUE constraint failed: scan_result.file_hash
解决方案：删除数据库并重启
rm database/scans.db
python app.py
5. 端口被占用
错误：OSError: [Errno 98] Address already in use
解决方案：更改 .env 文件中的 port
PORT=5001
6. CORS 错误
错误：Cross-Origin Request Blocked
解决方案：检查 app.py 中的 CORS 配置
7. 报告生成错误
错误：Report generation failed
解决方案：确保 reports 目录存在并具有写入权限
mkdir -p reports
chmod 755 reports
8. API Key 错误
错误：VirusTotal API key invalid
解决方案：在 .env 文件中验证您的 API key 或以演示模式运行
# ================================================================================
11. 安全最佳实践
## 推荐的安全措施：
1. API Key 安全：
- 切勿将您的 .env 文件提交到版本控制系统
- 对敏感数据使用环境变量
- 定期轮换 API key
2. 文件验证：
- 所有上传的文件都通过扩展名进行验证
- 强制执行文件大小限制
- 基于哈希的去重可防止重复扫描
3. 会话管理：
- 使用安全的会话处理
- 实施适当的会话超时
- 建议增加 CSRF 保护
4. CORS 配置：
- 出于安全考虑进行了正确配置
- 在生产环境中限制允许的来源
5. 数据库安全：
- 使用参数化查询 (SQLAlchemy ORM)
- 定期进行数据库备份
- 加密敏感数据
6. 生产环境部署：
- 禁用 DEBUG 模式
- 使用生产环境的 WSGI 服务器 (Gunicorn, uWSGI)
- 实施基于 SSL/TLS 的 HTTPS
- 设置适当的日志记录和监控
7. 文件存储：
- 自动清理临时文件
- 使用安全的文件权限
- 验证文件内容类型
# ================================================================================
12. 性能优化
## 优化技术：
1. 异步处理：
- 文件在后台线程中扫描
- 防止 Web 界面阻塞
- 用于处理的任务队列
2. 缓存：
- 扫描结果会被缓存以避免冗余处理
- 基于哈希的去重
- 针对频繁访问数据的内存缓存
3. 数据库优化：
- 对哈希字段进行索引以加快查找速度
- 查询优化
- 定期的数据库维护
4. 文件管理：
- 上传的文件在处理后被自动删除
- 高效的存储管理
- 清理旧报告
5. 前端优化：
- 缓存静态文件（304 响应）
- 压缩 CSS 和 JavaScript
- 数据的懒加载
# ================================================================================
13. 贡献
## 贡献指南：
1. Fork 该仓库
2. 创建一个功能分支
git checkout -b feature/AmazingFeature
3. 提交您的更改
git commit -m 'Add some AmazingFeature'
4. 推送到分支
git push origin feature/AmazingFeature
5. 发起一个 Pull Request
## 开发指南：
- 遵循 PEP 8 风格指南
- 编写有意义的提交信息
- 为复杂的逻辑添加注释
- 添加新功能时更新文档
- 为新功能编写单元测试
- 确保向后兼容性
## 代码审查清单：
- [ ] 代码遵循风格指南
- [ ] 文档已更新
- [ ] 测试已添加/通过
- [ ] 无安全漏洞
- [ ] 考虑了性能影响
- [ ] 实现了错误处理
# ================================================================================
14. 许可证
MIT 许可证
版权所有 (c) 2024 Sentinel AI Team
特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人不受限制地处置本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再授权和/或销售本软件副本的权利，并为被授权人提供在下列条件下行使上述权利：
上述版权声明和本许可声明应包含在本软件的所有副本或重要部分中。
本软件按“原样”提供，不提供任何明示或暗示的担保，包括但不限于对适销性、特定用途适用性和不侵权的担保。在任何情况下，作者或版权持有人均不对因本软件或本软件的使用或其他处理而引起的或与之相关的任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权行为还是其他诉讼中。
# ================================================================================
15. 联系与支持
## 支持渠道：
- 文档：https://github.com/yourusername/sentinel-ai-platform/wiki
- 问题：https://github.com/yourusername/sentinel-ai-platform/issues
- 电子邮件：support@sentinel-ai.com
- 网站：https://sentinel-ai.com
## 社区：
- Discord：https://discord.gg/sentinel-ai
- Twitter：https://twitter.com/sentinel_ai
- LinkedIn：https://linkedin.com/company/sentinel-ai
## 故障排除帮助：
联系支持之前：
1. 检查故障排除部分
2. 查看日志中的错误信息
3. 验证您的配置
4. 在 GitHub 上搜索现有问题
# ================================================================================
附录 A：VIRUSTOTAL API 使用
## VIRUSTOTAL API 速率限制：
免费层：
- 每分钟 4 次请求
- 每天 500 次请求
- 每月 1.55 万次请求
## 请求：
上传文件：
POST https://www.virustotal.com/api/v3/files
Headers: x-apikey: YOUR_API_KEY
获取分析结果：
GET https://www.virustotal.com/api/v3/analyses/{analysis_id}
Headers: x-apikey: YOUR_API_KEY
获取文件报告：
GET https://www.virustotal.com/api/v3/files/{file_hash}
Headers: x-apikey: YOUR_API_KEY
# ================================================================================
附录 B：响应示例
## 成功上传：
{
"success": true,
"message": "File queued for scanning",
"file_hash": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
"filename": "example.exe"
}
## 扫描结果：
{
"success": true,
"result": {
"id": 1,
"filename": "eicar.com",
"file_hash": "275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f",
"file_size": 68,
"scan_date": "2024-07-10T15:30:00",
"risk_score": 52,
"malware_family": "EICAR Test",
"status": "Medium Risk",
"threat_level": "Medium",
"detections": {
"McAfee": {"detected": true, "result": "EICAR.test", "category": "malicious"},
"Symantec": {"detected": true, "result": "EICAR Test File", "category": "malicious"}
},
"report_path": "reports/security_report_20260710_153000.pdf"
}
}
## 仪表板统计：
{
"success": true,
"data": {
"total_scans": 150,
"threats_detected": 45,
"high_risk": 12,
"critical_risk": 3,
"recent_scans": [...],
"scan_timeline": [
{"date": "2024-07-04", "count": 10},
{"date": "2024-07-05", "count": 15}
],
"threat_distribution": [
{"level": "Safe", "count": 80},
{"level": "Low", "count": 25},
{"level": "Medium", "count": 20},
{"level": "High", "count": 15},
{"level": "Critical", "count": 10}
]
}
}
# ================================================================================
附录 C：依赖项 (requirements.txt)
Flask==2.3.2
Flask-SQLAlchemy==3.0.5
Flask-CORS==4.0.0
python-dotenv==1.0.0
requests==2.31.0
reportlab==4.0.4
# ================================================================================
文档结束
获取最新更新和文档，请访问：
https://github.com/yourusername/sentinel-ai-platform
最后更新：2024 年 7 月 10 日
标签：AV绕过, DAST, FastAPI, YARA, 云资产可视化, 威胁情报, 开发者工具, 恶意软件分析, 数据可视化, 网络测绘, 请求拦截, 逆向工具