Bryn018/Semantic-Backdoor-Detector

# 语义 CPG 后门检测器     一个图神经网络 (GNN) 工具，它通过从 Code Property Graphs 中学习**语义数据流模式**来检测 Python 包中的供应链后门——而不仅仅是依靠特征码。 该工具的灵感来源于真实世界的攻击事件，例如 **[XZ Utils](https://en.wikipedia.org/wiki/XZ_Utils_backdoor)** (CVE-2024-3094)。在该事件中，供应链后门将混淆的命令执行隐藏在多层 base64 编码和条件触发器背后。传统的基于特征码的扫描器无法检测到它，而本工具可以将其捕获。 ## 工作原理 ``` Source Code → Code Property Graph (CPG) → 3-Layer GCN → Malicious / Benign ``` 1. **Code Property Graph (CPG)** — Joern 将 Python 源代码解析为统一的图表示，结合了 AST、控制流和数据流 2. **图卷积网络** — 一个 3 层 GCN (16→64→32→16) 用于学习后门代码特有的结构模式：base64 解码 → `os.system()`、reverse shell 设置、cron 持久化、数据外泄 3. **判定结论** — Sigmoid 输出给出一个概率值；≥0.5 即判定为 MALICIOUS（恶意） ## 架构 ``` ┌─────────────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ │ Python Source │────▶│ Joern │────▶│ PyG Data │────▶│ GCN │ │ (.py file) │ │ CPG │ │ Object │ │ Layers │ └─────────────────┘ └──────────┘ └────────────┘ └────┬─────┘ │ ┌────────────▼────┐ │ Sigmoid Output │ │ P(malicious) │ └─────────────────┘ ``` ## 安装说明 ### 前置条件 - **Python 3.10+** - **Java 11+**（Joern CPG 提取器必需） - **Joern CLI** (v4.0+) ### 快速开始 ``` # Clone 仓库 git clone https://github.com/yourusername/semantic-cpg-backdoor-detector.git cd semantic-cpg-backdoor-detector # 创建 virtual environment python3 -m venv .venv source .venv/bin/activate # 安装 Python 依赖 pip install -r requirements.txt # 安装 Joern（如果尚未安装） curl -L https://github.com/joernio/joern/releases/latest/download/joern-install.sh | bash ``` ### 手动安装 Joern ``` # 下载并解压到 ~/bin/joern mkdir -p ~/bin/joern cd /tmp curl -L -o joern-cli.zip https://github.com/joernio/joern/releases/latest/download/joern-cli.zip unzip joern-cli.zip -d ~/bin/joern chmod -R +x ~/bin/joern/ # 设置环境变量（添加到 ~/.bashrc） export JAVA_HOME=$HOME/.local/jdk/jdk-21.0.5+11 export PATH=$JAVA_HOME/bin:$PATH ``` ## 使用方法 ``` # 分析单个文件 python infer.py --target /path/to/suspicious_file.py # 使用自定义 threshold python infer.py --target /path/to/file.py --threshold 0.7 ``` ### 示例输出 — 恶意文件 ``` ╔══════════════════════════════════════════════════════════╗ ║ Semantic CPG Backdoor Detector v1.0 ║ ╚══════════════════════════════════════════════════════════╝ [+] Loaded vocabulary: 16 node types [+] Loaded model: model.pth (18097 bytes) [*] Extracting Code Property Graph from backdoor.py ... [+] CPG extracted: 79 nodes, 231 edges [*] Running GNN inference ... [!] Analyzing: backdoor.py [+] Nodes extracted: 79 | Edges: 231 [!!!] VERDICT: MALICIOUS (89.7% confidence) [!] The GNN detected semantic patterns consistent with obfuscated backdoor code (base64-encoded command execution, reverse shells, data exfiltration, or persistence mechanisms). ``` ### 示例输出 — 良性文件 ``` [✓] VERDICT: BENIGN (92.3% confidence) ``` ## 内置模型 该仓库包含一个预训练模型： | 文件 | 描述 | |------|-------------| | `model.pth` | 训练好的 GNN 权重 (3,713 个参数，18KB) | | `vocab.json` | 全局节点类型词表 (16 种 CPG 节点类型) | | `dataset.pt` | 完整训练数据集 (60 个图) | **开箱即用**，你可以对任何 Python 文件运行 `python infer.py --target `。 ## 训练 要在你自己的数据集上进行训练： ``` # 生成合成 dataset python generate_dataset.py # 重新训练 model python train.py --epochs 50 --lr 0.001 ``` ## 数据集 包含的训练集共有 60 个文件： - **30 个良性文件**：数学实用工具、字符串操作、文件 I/O、数据处理 - **30 个恶意文件**：`os.system` + base64、reverse shell、`subprocess.call`、数据外泄、cron 持久化 ## 依赖要求 参见 [requirements.txt](requirements.txt)： ``` torch>=2.0 torch_geometric>=2.0 networkx>=3.0 py4j>=0.10 ``` ## 许可证 本项目基于 [MIT License](LICENSE) 授权。 **负责任使用声明：** 本工具仅供防御性安全研究使用——用于检测依赖项中的供应链后门、审计你自己的代码库，以及经过授权的红蓝对抗演练。它**不**可用于逃避对恶意代码的检测、未经授权的扫描，或任何违反适用法律的活动。有关完整的条款和负责任使用声明，请参阅 [LICENSE](LICENSE)。

标签：DNS 反向解析, JS文件枚举, Python, 代码属性图, 凭据扫描, 后门检测, 图神经网络, 无后门, 特权检测, 网络信息收集, 逆向工具, 错误基检测, 静态代码分析