manu-j3400/Soteria

# Soteria [](https://github.com/manu-j3400/Soteria/actions/workflows/ci.yml) [](https://github.com/manu-j3400/Soteria/tree/main/tests) [](LICENSE) [](https://www.python.org) **Soteria** 是一个机器学习安全平台，通过分析源代码的*结构与行为 DNA* 来检测恶意代码、后门和注入的漏洞。Soteria 不依赖容易绕过的关键字搜索，而是叠加了四个独立的检测引擎：模式匹配、统计熵、基于抽象语法树的 Random Forest 集成，以及基于控制流图的 Graph Convolutional Network。所有这些都用于给出最终的判定结果。 检测核心代号为 **Kyber**。在它周围是一套研究级的安全引擎（蜜罐编排、APT 狩猎、SOC 响应、容器逃逸和内存漏洞利用检测），位于 `engines/` 下。 🔗 **在线站点：** [trysoteria.live](https://trysoteria.live) · **API：** [a-c-i-d-1.onrender.com](https://a-c-i-d-1.onrender.com) ## 工作原理 每次代码提交都会流经一个分层检测 pipeline。每一层都可以独立提出判定；严重程度最高的信号将具有最高优先级。 | # | 层级 | 检测内容 | 使用 Torch？ | |---|-------|-----------------|--------| | 1 | **Pattern scan** | 跨 13 种语言的 1,498 种漏洞模式（SQLi、RCE、硬编码密钥、依赖混淆、typosquatting） | 否 | | 2 | **Entropy profiler** | 通过字符串和字节字面量的 Shannon 熵检测加壳/混淆/加密的 payload | 否 | | 3 | **SNN temporal profiler** | 使用 spiking neural network 检测异常的执行节奏（解密循环、解包、网络探测） | 是 | | 4 | **RF ensemble** | 101 项特征的 Random Forest 投票（89 项 AST 节点计数 + 12 项工程特征） | 否 | | 5 | **GCN inference** | 通过基于控制流图的 Graph Convolutional Network 分析结构意图 | 是 | | 6 | **Semgrep** *(可选)* | 作为第四层深度扫描的 AST 级社区规则 | 否 | **Structural DNA.** 代码被解析为 AST，变量名和常量通过自定义的 `ast.NodeTransformer` 进行匿名化处理（从而使重命名混淆失效），然后被向量化为数值特征矩阵： | Function | `Assign` | `Call` | `BinOp` | `Attribute` | **Label** | |---|---|---|---|---|---| | `calculate_total` | 2.0 | 1.0 | 3.0 | 0.0 | **0 (Clean)** | | `backdoor_shell` | 1.0 | 4.0 | 0.0 | 2.0 | **1 (Malicious)** | 当验证 F1 ≥ 0.60 时，GCN 将融入到最终评分中，其自适应权重（0.2–0.6）根据模型置信度进行缩放。 ## 架构 ``` ┌──────────────┐ HTTPS ┌────────────────────┐ │ Frontend │ ───────────────▶│ Middleware │ │ React + Vite │ /analyze, /auth │ Flask (app.py) │ │ (Vercel) │◀─────────────── │ JWT · SQLite │ └──────────────┘ verdict JSON └─────────┬──────────┘ │ │ sys.path Supabase ▼ (auth) ┌────────────────────┐ │ backend/src/ │ │ AST · GCN · SNN │ │ entropy · patterns│ └────────────────────┘ ``` - **Frontend** — React 18, Vite 6, TypeScript, Tailwind CSS 4, Framer Motion。托管在 Vercel 上。通过 Supabase 进行身份验证。 - **Middleware** (`middleware/app.py`) — 生产级 Flask API：JWT 认证、SQLite 扫描历史、速率限制、24 小时结果缓存、webhook 通知、在线重训练、模型漂移检测。约 1,800 行代码。 - **Backend** (`backend/src/`) — middleware 在运行时导入的 ML/分析模块。 - **Engines** (`engines/`) — 独立的研究级安全引擎（见下文）。 ## 安全引擎 (`engines/`) 检测核心是 **Kyber**。其他引擎则针对不同的威胁面： | Engine | 用途 | |--------|---------| | **Kyber** | 多模态深层程序分析：TDA manifolds、Siamese GCN IR 验证、SNN 时间剖析 | | **DeceptiNet** | 自适应蜜罐编排器 — 超博弈 DRL（PPO + belief-state 粒子滤波） | | **SymbAPT** | 神经符号 APT 猎手 — 可微分的 MITRE ATT&CK 规则 + Kafka 流处理 | | **RLShield** | 多代理 MAPPO SOC 响应编排器，集成 Wazuh | | **AgentShield** | 针对浏览器使用代理的 DOM Merkle 哈希 TOCTOU 检测器 (Rust) | | **ContainerGuard** | 容器逃逸检测（基于 syscall 图的 GNN：`unshare`、`pivot_root`、`chroot`） | | **MemShield** | 内存漏洞利用检测（ROP 链检测、堆喷射分析、污点追踪） | | **Ruflo** | 将 Soteria 的扫描 API 作为工具公开给 Claude/Ruflo 代理的 MCP 服务器 | ## 技术栈 - **编程语言：** Python 3.13+、TypeScript、Rust - **ML / 分析：** scikit-learn、PyTorch、PyTorch Geometric (GCN)、`ast`、tree-sitter（支持 13 种语言）、pandas、joblib - **Backend：** Flask、PyJWT、bcrypt、FPDF2（报告生成）、flasgger (OpenAPI)、gunicorn - **Frontend：** React 18、Vite 6、Tailwind CSS 4、Framer Motion、Radix UI、Supabase - **基础设施：** Docker、GitHub Actions、Render (API)、Vercel (Frontend) ## 快速开始 ### 前置条件 - Python 3.13+ - Node.js 18+ (Frontend) - Rust 工具链（仅用于 AgentShield） ### 后端 / 中间件 ``` # 从 repo root pip install -r backend/requirements.txt # 运行生产环境 middleware API cd middleware python app.py # serves on http://localhost:5000 ``` ### 前端 ``` cd frontend npm install # 创建 frontend/.env.local，包含 VITE_SUPABASE_URL + VITE_SUPABASE_ANON_KEY npm run dev # http://localhost:5173 ``` 所需的前端环境变量： | Variable | 用途 | |----------|---------| | `VITE_SUPABASE_URL` | Supabase 项目 URL (身份验证) | | `VITE_SUPABASE_ANON_KEY` | Supabase anon key | | `VITE_POSTHOG_KEY` | *(可选)* PostHog 分析 — 省略以禁用 | ### Docker ``` docker compose up --build ``` ## API 参考 middleware 提供了 REST API。安装 `flasgger` 后，交互式文档位于 `/apidocs` (Swagger UI)。 **核心扫描** | Method | Endpoint | 描述 | |--------|----------|-------------| | `POST` | `/analyze` | 扫描单个代码片段 → 判定结果 + 漏洞 | | `POST` | `/batch-scan` | 扫描多个文件 | | `POST` | `/deep-scan` | 完整的多层深度扫描 | | `POST` | `/github-scan` | 扫描 GitHub 仓库 | | `POST` | `/generate-report` | PDF 执行摘要 | **身份验证与历史记录** | Method | Endpoint | 描述 | |--------|----------|-------------| | `POST` | `/api/auth/signup` · `/login` · `/logout` | JWT 身份验证 | | `GET` | `/scan-history` | 经过身份验证的扫描历史 | | `GET` | `/api/scan-history/export` | 导出为 CSV | | `POST` | `/github/pkce/state` · `/github/token` | GitHub OAuth (PKCE) | **模型运维 (管理员)** | Method | Endpoint | 描述 | |--------|----------|-------------| | `POST` | `/api/admin/retrain` | 触发在线重训练 | | `GET` | `/api/admin/retrain/status` · `/history` | 重训练状态 + 持久化日志 | | `GET` | `/api/model/drift` | KL 散度漂移检测 | | `GET` | `/model-stats` · `/api/engines/status` | 引擎 + 模型健康状态 | 示例： ``` curl -X POST https://a-c-i-d-1.onrender.com/analyze \ -H "Content-Type: application/json" \ -d '{"code": "import os\nos.system(input())"}' ``` ## 项目结构 ``` . ├── middleware/app.py # Production Flask API (JWT, SQLite, retraining, drift) ├── backend/ │ ├── src/ # AST/GCN/SNN/entropy/pattern modules │ ├── CSV_master/ # Training data │ └── ML_master/ # Serialized models (acidModel.pkl, acidModel_gcn.pt) ├── frontend/ # React + Vite dashboard ├── engines/ # Kyber + research security engines ├── tests/ backend/tests/ # 154 tests └── .github/workflows/ # CI: ci.yml, middleware-ci.yml, kyber-pr-check.yml ``` ## 测试 ``` # 完整测试套件（154 个测试） python3 -m pytest tests/ backend/tests/ # frontend type-check + build cd frontend && npx tsc --noEmit && npm run build ``` **CI** 会运行 middleware 测试套件、mypy 类型检查，并（在 PR 中）通过 GitHub Actions 运行 Kyber 污点分析检查。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：Apex, URL收集, XXE攻击, 凭据扫描, 可视化界面, 图神经网络, 文档安全, 机器学习, 请求拦截, 逆向工具, 静态应用安全测试