AbdullahMaqbool22/FalconScan

# 🦅 FalconScan - 高级 APK 安全分析平台 ## 📋 目录 1. [🎯 概述](#overview) 2. [✨ 功能](#features) 3. [🏗️ 架构](#architecture) 4. [🛠️ 技术栈](#technology-stack) 5. [📋 前置条件](#prerequisites) 6. [🛠️ 安装说明](#installation) 7. [📖 用户指南](#user-guide) 8. [🤖 AI 分析](#ai-analysis) 9. [🔒 安全分析](#security-analysis) 10. [🔌 API 文档](#api-documentation) 11. [📁 目录结构](#directory-structure) 12. [📄 页面](#pages) 13. [🌍 环境变量](#environment-variables) 14. [🚀 部署](#deployment) 15. [🐛 故障排除](#troubleshooting) 16. [📄 许可证](#license) ## 🎯 概述 ### 核心亮点 | ⚡ 快速分析 | 🔒 安全检查 | 📊 专业报告 | 🎨 现代 UI | |:---:|:---:|:---:|:---:| | 几秒钟内完成分析 | 涵盖密钥、加密、权限、网络风险等 | 提供附带修复指导的 PDF 和 JSON 报告 | 带有实时反馈的网络安全主题界面 | | 🤖 AI 辅助 | 📱 专注 APK | 🚀 实时更新 | 🛡️ 生产就绪 | |:---:|:---:|:---:|:---:| | 可选的 Gemini 驱动的分析和摘要 | 专为 Android 包工作流打造 | 进度跟踪和通知 | JWT 身份验证、感知角色的仪表板以及部署指导 | ## ✨ 功能 - 🔍 **实时 APK 分析** - 即时威胁检测和漏洞扫描 - 🛡️ **高级安全检查** - 检测硬编码的密钥、弱加密、危险权限 - 🤖 **AI 安全智能** - 按需进行的 AI 分析，提供攻击链、严重性重新评分以及代码级修复建议 - 📊 **动态风险评分** - 基于行业标准的 CVSS 启发式加权评分系统 - 📈 **综合报告** - 附带修复指导的详细漏洞报告 - 🔐 **权限分析** - 识别危险权限和风险行为 - 📉 **威胁可视化** - 用于漏洞分解的交互式图表和图形 - 📜 **PDF 导出** - 用于文档记录的专业安全报告 - 🔔 **实时通知** - 随时了解扫描完成情况和威胁信息 - 👤 **用户管理** - 安全的 JWT 身份验证和个人资料管理 - 🎨 **现代 UI** - 采用毛玻璃效果的专业暗色网络安全主题 ## 🛠️ 技术栈 ### 后端 - **框架**: Django 4.2 + Django REST Framework - **APK 分析**: Androguard 4.x，用于反编译和静态分析 - **AI 引擎**: google-genai 1.0+，用于智能安全报告 - **身份验证**: JWT (djangorestframework-simplejwt) - **数据库**: SQLite (开发环境) / PostgreSQL (生产环境) - **服务器**: Daphne (ASGI) - **PDF 生成**: ReportLab - **API**: 带有全面端点的 RESTful ### 前端 - **框架**: Next.js 16 和 TypeScript 5 - **UI 库**: React 19 - **组件**: shadcn/ui + Radix UI - **样式**: Tailwind CSS 和自定义网络安全主题 - **图表**: Recharts 用于数据可视化 - **HTTP 客户端**: Axios - **日期处理**: date-fns ## 🏗️ 架构 ### 高层系统架构 应用程序分为用于分析和持久化的 Django 后端，以及用于仪表板、报告和上传的 Next.js 前端。  ### 数据流架构  ### 组件架构  ### 核心模块 - 后端 API 和分析引擎位于 `backend/` 下 - 前端仪表板和用户流程位于 `app/` 下 - 共享的 UI、身份验证和通知组件位于 `components/` 下 - API 访问和辅助工具位于 `lib/` 下 ## 📋 前置条件 - Python 3.8 或更高版本 - Node.js 18 或更高版本 - npm 或 pnpm - Git ## 🛠️ 安装说明 ### 1. 克隆仓库 ``` git clone https://github.com/yourusername/falconscan.git cd falconscan ``` ### 2. 后端设置 ``` cd backend # 创建虚拟环境 python -m venv venv # 激活虚拟环境 # 在 Windows 上： venv\Scripts\activate # 在 macOS/Linux 上： source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 运行 migrations python manage.py migrate # 创建 superuser（可选） python manage.py createsuperuser # 启动 development server python manage.py runserver ``` 后端将运行在 `http://localhost:8000` ### 3. 前端设置 ``` # 在一个新的终端中，从项目根目录开始 pnpm install # 或者 npm install # 复制 environment file cp .env.example .env.local # 使用你的设置更新 .env.local： # NEXT_PUBLIC_API_URL=http://localhost:8000/api # 启动 development server pnpm dev # 或者 npm run dev ``` 前端将运行在 `http://localhost:3000` ## 📖 用户指南 ### 上传 APK 进行分析 1. 访问 `http://localhost:3000` 2. 注册或登录您的账户 3. 进入 **Upload** 页面 4. 拖放或浏览选择 APK 文件 5. 输入应用名称（可选 - 如果为空，将使用文件名） 6. 点击 **Start Analysis** 7. 等待分析完成（约 1.5-2 秒） 8. 查看详细的安全报告 ### 查看分析结果 - **Dashboard**: 所有扫描的统计概览 - **Reports**: 每次扫描的详细漏洞发现 - **History**: 所有先前扫描的时间轴 - **Download PDF**: 导出专业的安全报告 ### 其他页面 - **Upload**: 提交 APK 以进行静态分析和评分 - **Documentation**: 阅读内置的 API 和使用帮助 - **Profile**: 管理您的账户设置和首选项 ## 🤖 AI 分析 FalconScan 可以使用配置的 Gemini 模型为已完成的扫描生成 AI 辅助分析。 ### 附加功能 - 攻击链式摘要 - 严重性重新评分和优先级排序 - 修复建议 - 面向合规性的观察结果 ### 用法 1. 打开已完成的扫描报告。 2. 选择 **AI** 标签页。 3. 点击 **Generate AI Report**。 4. 查看生成的发现和建议。 ### 注意事项 - AI 分析需要在后端环境中配置 `AI_API_KEY`。 - 模型选择和回退行为在后端进行配置。 ## 🔒 安全分析 ### 漏洞检测 - 硬编码的 API 密钥和机密（AWS, Google, Firebase, GitHub, Stripe 等） - 弱加密实现（DES, ECB, MD5, SHA-1） - 不安全的网络配置（HTTP，明文流量） - 危险权限的使用（CAMERA, LOCATION, SMS, CONTACTS 等） - SQL 注入漏洞 - 路径遍历问题 - 未受权限保护的导出组件 - 生产环境中的调试证书 - 15 项以上的额外安全检查 ### 风险评分算法 基于行业标准的加权评分系统： - **Critical（严重）**: 每个 25 分 - **High（高）**: 每个 15 分 - **Medium（中）**: 每个 8 分 - **Low（低）**: 每个 3 分 对以下情况应用乘数： - 危险权限（5 个以上）: +20% - 可调试标志: +15% - 明文流量: +15% - 硬编码密钥: +15% - 允许备份: +10% ### 威胁等级 | 等级 | 分数范围 | 颜色 | 所需操作 | |-------|------------|-------|-----------------| | **Critical（严重）** | ≥ 80 | 🔴 | 需要立即关注 | | **High（高）** | ≥ 60 | 🟠 | 重大安全隐患 | | **Medium（中）** | ≥ 35 | 🟡 | 需要审查的显著问题 | | **Low（低）** | ≥ 15 | 🟢 | 次要问题或建议 | | **Safe（安全）** | < 15 | ✅ | 未检测到威胁 | ### 分析范围 - Manifest 和权限检查 - 组件暴露和导出表面审查 - 证书和签名检查 - 密钥、token 和凭据模式检测 - 网络和明文流量审查 - 弱加密和不安全存储检查 ## API 文档 ### 身份验证 ``` POST /api/accounts/users/register/ # Create account POST /api/token/ # Login → returns access + refresh JWT POST /api/token/refresh/ # Refresh access token GET /api/accounts/users/me/ # Current user profile ``` ### 扫描 ``` POST /api/scans/upload/ # Upload APK (multipart/form-data) GET /api/scans/ # List all scans (paginated) GET /api/scans/{id}/ # Full scan details + analysis results GET /api/scans/{id}/report/ # Security report (JSON) GET /api/scans/{id}/download_pdf/ # Download PDF report POST /api/scans/{id}/rescan/ # Retry a failed scan DELETE /api/scans/{id}/ # Delete scan + all associated data GET /api/scans/statistics/ # Dashboard stats POST /api/scans/ai_report/ # Generate AI security report POST /api/scans/cleanup_failed/ # Bulk retry all failed scans ``` 所有扫描端点都需要 `Authorization: Bearer `。 ## 目录结构 ``` falconscan/ ├── backend/ │ ├── falconscan_backend/ │ │ ├── settings.py # Django configuration │ │ ├── urls.py │ │ └── wsgi.py / asgi.py │ ├── apps/ │ │ ├── accounts/ # User management (JWT auth) │ │ │ ├── models.py │ │ │ ├── views.py │ │ │ └── serializers.py │ │ └── scans/ # Core scan engine │ │ ├── models.py # Scan, Vulnerability, Report models │ │ ├── analyzer.py # Androguard APK wrapper │ │ ├── static_analyzer.py # String & artifact extraction │ │ ├── vulnerability_scanner.py # 15+ security checks │ │ ├── ai_analyzer.py # AI security intelligence engine │ │ ├── pdf_generator.py # ReportLab PDF builder │ │ └── views.py # REST API endpoints │ └── manage.py ├── app/ # Next.js app router │ ├── dashboard/ │ │ ├── upload/ # APK upload interface │ │ ├── reports/[id]/ # Detailed scan report viewer │ │ ├── history/ # Scan history timeline │ │ ├── settings/ # User settings │ │ └── documentation/ # In-app documentation viewer │ ├── login/ │ ├── register/ │ └── page.tsx # Landing page ├── components/ # Shared React components ├── lib/ │ └── api.ts # Centralised Axios API client └── public/ # Static assets ``` ## 页面 ### 公共页面 - `/` - 包含功能和统计数据的着陆页 - `/login` - 带 JWT 身份验证的用户登录 - `/register` - 新用户注册 ### 仪表板页面（受保护） - `/dashboard` - 包含统计数据和最近扫描的概览 - `/dashboard/upload` - 上传 APK 进行扫描 - `/dashboard/history` - 查看所有以前的扫描 - `/dashboard/reports` - 生成并下载详细报告 - `/dashboard/documentation` - 完整的 API 和使用文档 - `/dashboard/settings` - 用户设置和首选项 - `/dashboard/profile` - 用户资料管理 ## 环境变量 ### 后端 (`backend/.env`) ``` DEBUG=True DJANGO_SECRET_KEY=your-secret-key-here ALLOWED_HOSTS=localhost,127.0.0.1 CORS_ALLOWED_ORIGINS=http://localhost:3000 DATABASE_URL=sqlite:///db.sqlite3 AI_API_KEY=your-ai-api-key-here ``` ### 前端 (`.env.local`) ``` NEXT_PUBLIC_API_URL=http://localhost:8000/api NEXT_PUBLIC_APP_NAME=FalconScan ``` ## 部署 ### 生产环境检查清单 - [ ] 在 Django 设置中将 `DEBUG=False` - [ ] 生成新的 `DJANGO_SECRET_KEY` - [ ] 切换到 PostgreSQL 用于生产环境 - [ ] 将 `ALLOWED_HOSTS` 设置为您的生产环境域名 - [ ] 配置 HTTPS / TLS 终止 - [ ] 将 `CORS_ALLOWED_ORIGINS` 设置为生产前端 URL - [ ] 设置用于 AI 分析功能的 `AI_API_KEY` - [ ] 运行 `python manage.py collectstatic` - [ ] 设置适当的日志记录和监控 ## 故障排除 ### 后端无法启动 ``` # 检查端口 8000 是否被占用 lsof -i :8000 # macOS/Linux netstat -ano | findstr :8000 # Windows ``` ### 前端无法启动 ``` # 清除缓存并重新安装 rm -rf node_modules .next pnpm install ``` ### 数据库问题 ``` # 重置数据库（仅限开发环境！） python manage.py flush --no-input python manage.py migrate ``` ### 缺少 Python 模块 ``` pip install androguard pip install -r requirements.txt ``` **CORS 错误：** 验证 `backend/falconscan_backend/settings.py` 中的 `CORS_ALLOWED_ORIGINS` 是否包含您的前端来源。 ## 📄 许可证 MIT — 查看 [许可证](LICENSE)。

标签：Android安全, APK扫描, Django, Python, 云安全监控, 人工智能, 指令注入, 无后门, 测试用例, 用户模式Hook绕过, 网络测绘, 自动化攻击, 逆向工具, 静态分析