MR-UNKNOWN8014/repo-security-scanner
GitHub: MR-UNKNOWN8014/repo-security-scanner
一款在克隆 Git 仓库前执行静态分析的安全扫描工具，用于检测恶意代码、后门、危险函数调用及易受攻击的依赖项。
Stars: 0 | Forks: 0
# 仓库安全扫描器
该扫描器对仓库文件执行静态分析，可检测：
- 加密货币挖矿程序特征
- 后门特征码
- 数据窃取代码
- 混淆技术
- 危险函数调用
- 易受攻击的依赖项
- 高熵（加密/混淆）文件
## 快速开始
```
# Clone 仓库
git clone https://github.com/MR-UNKNOWN8014/repo-security-scanner.git
cd repo-security-scanner
# 安装依赖
./setup.sh # Linux/macOS
setup.bat # Windows
# 扫描仓库
python run_scanner.py https://github.com/user/repo.git
```
## 1. 安装：
**需要 Python 3.8 或更高版本才能运行。**
### 1.2 Linux / macOS
```
# Linux/Mac
chmod +x setup.sh
# Windows
./setup.sh
```
**安装程序将会**：
- 验证 Python 版本
- 安装所有必需的依赖项
- 创建运行脚本
### 1.3 手动安装
```
# 创建 virtual environment (可选)
python -m venv venv
# Linux/Mac
source venv/bin/activate
# Windows
venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
```
## 2. 用法
### 2.1 基本命令
```
# 扫描远程仓库
python run_scanner.py https://github.com/user/repo.git
# 扫描本地仓库
python run_scanner.py /path/to/local/repo
# 快速扫描 (限制文件数)
python run_scanner.py https://github.com/user/repo.git --mode quick
# 详细输出的彻底扫描
python run_scanner.py https://github.com/user/repo.git --mode thorough --detailed
# 导出报告至 JSON
python run_scanner.py https://github.com/user/repo.git --output report.json
```
### 2.2 命令行参数
| 选项 | 简写 | 描述 | 默认值 |
| ---------------- | ----- | --------------------------------------------------------------------- | -------- |
| `--mode` | `-m` | 扫描模式：quick、balanced、thorough、smart（类型详见下文） | balanced |
| `--output` | `-o` | 将报告导出为 JSON 或 CSV 文件 | None |
| `--verbose` | `-v` | 显示详细的扫描进度 | False |
| `--detailed` | `-d` | 在报告中显示详细分类 | False |
| `--format` | - | 报告格式：simple、multi、categories、detailed、all（类型详见下文） | all |
| `--keep-repo` | - | 扫描后保留克隆的仓库 | False |
| `--auto-decision`| - | 根据风险评分自动做出决定 | False |
### 2.3 扫描模式
| 模式 | 描述 | 扫描的文件 |
| ------------ | ------------------------------ | ---------------------------------------------------------------------------- |
| **Quick** | 带有大小限制的快速扫描 | 文件 < 1MB，最多 10,000 个 |
| **Balanced** | 适度的覆盖范围和良好的速度 | 所有有效文件 |
| **Thorough** | 完全扫描 | 无限制地扫描所有文件（如果文件过多或过大，会花费一些时间） |
| **Smart** | 优先处理可执行文件/脚本文件 | 脚本、二进制文件、可执行文件 |
## 3. 报告格式
扫描器支持四种报告格式，外加一个按顺序显示它们的 "all" 选项。
### 3.1 Simple 格式
带有状态条和风险等级的单个百分比分数。
```
============================================================
REPOSITORY: awesome-project
RISK SCORE: 23.5% [████████░░░░░░░░░░░░] LOW RISK
============================================================
```
### 3.2 Multi-Factor 格式
将风险分为四个类别，并带有各自的分数。
```
============================================================
REPOSITORY: awesome-project
MULTI-FACTOR ANALYSIS
Code Quality: 76.3% [██████████░░░░░░]
Security: 76.5% [██████████░░░░░░]
Obfuscation: 16.5% [██░░░░░░░░░░░░░░]
Malicious: 11.8% [█░░░░░░░░░░░░░░░]
OVERALL: 23.5% LOW RISK
============================================================
```
### 3.3 Categories 格式
显示风险类别，包含文件细分和建议。
```
============================================================
REPOSITORY: awesome-project
[LOW] RISK
Risk Level: [LOW]
Score: 23.5%
Findings: 12 issues found
Files: 0 high, 3 medium, 9 low
Recommendation: REVIEW BEFORE CLONING
============================================================
```
### 3.4 Detailed 格式
包含所有发现和统计信息的完整报告。
```
============================================================
REPOSITORY: awesome-project
[LOW] RISK
Risk Level: [LOW]
Score: 23.5%
Findings: 12 issues found
Files: 0 high, 3 medium, 9 low
Recommendation: REVIEW BEFORE CLONING
============================================================
FILE BREAKDOWN:
Safe: 45
Low Risk: 9
Medium Risk: 3
High Risk: 0
STATISTICS:
Total Files: 57
Scan Duration: 4.32s
Findings Found: 12
TOP FINDINGS:
1. [MEDIUM] encoding: Multiple base64 strings: 8
2. [MEDIUM] vulnerable_dependency: NPM package 'lodash': Prototype pollution vulnerabilities
3. [LOW] dangerous_function: Dangerous function: eval
4. [LOW] network: Network activity: HTTP request
```
## 4. 风险评分
### 4.1 风险等级
|分数|等级|建议|
|---|---|---|
|0-9|SAFE|可安全克隆|
|10-24|LOW RISK|克隆前请审查|
|25-49|MEDIUM RISK|请谨慎操作|
|50-74|HIGH RISK|避免克隆|
|75-100|CRITICAL|严禁克隆|
### 4.2 评分因素
|因素|最高分|描述|
|---|---|---|
|恶意模式|100|加密货币挖矿程序、后门、数据窃取|
|危险函数|100|eval、exec、system、subprocess|
|熵分析|20|高熵表明存在加密/混淆|
|Base64 编码|10|大型 base64 字符串可能包含 payload|
|文件大小|10|大文件可能包含隐藏的 payload|
|易受攻击的依赖项|每个包 15 分|已知的易受攻击包|
## 5. 检测能力
### 5.1 恶意模式类别
|类别|示例模式|
|---|---|
|加密货币挖矿程序|cryptonight, stratum, xmrig, mining, cpuminer|
|后门|socket.bind, socket.connect, base64.b64decode|
|数据窃取|requests.post, discord webhook, smtplib, telegram|
|混淆|base64, zlib, exec(decode), String.fromCharCode|
|Shell 命令|subprocess, os.system, popen, eval|
|网络活动|socket, requests, urllib, websocket, ftp|
|文件操作|os.remove, shutil.rmtree, file.write, os.chmod|
### 5.2 特定语言检测
|语言|检测的函数|
|---|---|
|Python|exec, eval, compile, **import**, os.system, subprocess.call, subprocess.Popen, os.popen|
|JavaScript|eval, Function, setTimeout, setInterval, document.write, innerHTML|
|Bash|exec, eval, source, ., export, alias|
|PHP|eval, system, exec, passthru, shell_exec, assert|
|Ruby|eval, exec, system, ``, IO.popen, Open3|
|Go|os/exec, syscall, reflect, unsafe|
|Rust|std::process, std::fs, unsafe, std::mem|
|Java|Runtime.exec, ProcessBuilder, System.load, Class.forName|
### 5.3 易受攻击依赖项检测
| 包管理器 | 检测的包 |
| -------------- | ------------------------------------------------- |
| npm | crypto-js, node-fetch, axios, lodash, request |
| pip | requests, urllib3, paramiko, cryptography, pyyaml |
## 6. 项目结构
```
repo-security-scanner/
├── setup.sh # Linux/macOS installer
├── setup.bat # Windows installer
├── requirements.txt # Python dependencies
├── README.md # Documentation
├── LICENSE # MIT License
├── .gitignore # Git ignore file
├── run_scanner.py # Entry point
│
└── repo_scanner/ # Main package
├── __init__.py
├── config.py # Configuration and constants
├── main.py # Main entry point
├── cli/ # Command-line interface
│ ├── __init__.py
│ └── arguments.py # Argument parsing
│
├── scanner/ # Core scanning modules
│ ├── __init__.py
│ ├── core.py # Scanner orchestrator
│ ├── file_analyzer.py # Individual file analysis
│ ├── pattern_matcher.py # Pattern detection engine
│ ├── dependency_checker.py # Dependency scanning
│ └── entropy_calculator.py # Entropy analysis
│
├── report/ # Report generation
│ ├── __init__.py
│ ├── formatter.py # Output formatting
│ └── exporters.py # JSON/CSV export
│
├── models/ # Data models
│ ├── __init__.py
│ └── scan_result.py # Result data structures
│
└── utils/ # Utility functions
├── __init__.py
├── file_utils.py # File operations
└── git_utils.py # Git operations
```
## 7. 故障排除
|问题|检查|解决方案|
|---|---|---|
|未找到 Python|是否安装了 Python？|从 [python.org](https://python.org/) 安装 Python 3.8+|
|ModuleNotFoundError|是否安装了依赖项？|运行 `pip install -r requirements.txt`|
|Git clone 失败|是否安装了 Git？|从 [git-scm.com](https://git-scm.com/) 安装 Git|
|权限被拒绝|文件权限是否正确？|`chmod +x setup.sh` (Linux/macOS)|
|扫描耗时过长|是否为大型仓库？|使用 `--mode quick` 或 `--mode smart`|
|未生成报告|输出路径是否有效？|检查输出目录的写入权限|
|高熵警告|是否为误报？|手动审查文件，这可能是合法的正常现象|
## 8. 未来增强功能
- [ ] Git 历史记录分析 - 扫描提交历史中的机密信息和密钥
- [ ] 机密信息检测 - API key、密码、token、凭证
- [ ] 许可证检查器 - 检测不兼容或限制性的许可证
- [ ] 二进制签名分析 - 验证来自受信任来源的二进制文件
- [ ] 已知恶意仓库数据库
- [ ] Docker 镜像扫描
- [ ] 包注册表扫描 (PyPI, npm, RubyGems)
### 9.1 Pull Request 流程
1. Fork 该仓库
2. 创建功能分支：`git checkout -b feature/AmazingFeature`
3. 提交您的更改：`git commit -m 'Add some AmazingFeature'`
4. 推送到该分支：`git push origin feature/AmazingFeature`
5. 提交 Pull Request
### 9.2 报告问题
在 GitHub 上报告问题时，请包括：
- 问题描述
- 复现步骤
- 预期行为
- 实际行为
- 环境（OS、Python 版本）
- 日志或截图（如果有）
所有这些信息能让我修复这些 bug 并把工具做得更好。
标签：Git, Python, 安全专业人员, 无后门, 暗色界面, 网络安全研究, 逆向工具, 错误基检测, 静态代码分析