TTMK7777/code-validator
GitHub: TTMK7777/code-validator
一款专为拦截 AI 生成代码中常见安全缺陷而设计的轻量级离线静态扫描工具，适合集成到 CI/CD 流水线。
Stars: 0 | Forks: 0
# code-validator
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](#)
[](#)
**项目背景：** AI 助手经常生成*看起来*正确但包含细微安全缺陷的代码——例如示例中硬编码的 API key、同时使用了 `allow_origins=["*"]` 和 `allow_credentials=True`、以及通过字符串拼接的 SQL。`code-validator` 是一个轻量级的 CI 门禁，可以在这些问题进入 `main` 分支*之前*将其拦截。
| | |
|---|---|
| 🎯 **适用场景** | 在 PR 阶段拦截不安全的 AI 生成代码 |
| ⚡ **速度** | 每个文件不到 1 秒，`--git-diff` 模式仅扫描更改过的文件 |
| 🔒 **隐私** | 100% 离线运行。代码不会离开你的机器。唯一的依赖项是：`pydantic` |
| 🧪 **检测规则** | 涵盖安全性、质量和依赖层的 20 条规则（SEC001–SEC013 不包含 SEC007，QUAL001–QUAL002，DEP001–DEP006） |
| 📦 **安装** | `pip install -r requirements.txt` —— 即装即用 |
## 功能
### 安全扫描
- 硬编码凭证：API key（OpenAI, Anthropic, Google, GitHub token）、密码、数据库 URL、Django/Flask `SECRET_KEY`、AWS 访问密钥以及嵌入的 PEM 私钥
- 危险的 CORS 配置：通配符 origin，以及通配符 origin 与 `allow_credentials=True` 结合使用
- SQL 注入模式：f-string 插值、`+` 拼接、`str.format()` 和 `%` 操作符
- 命令注入：`os.system` / `os.popen` / `subprocess(..., shell=True)`
- 不安全的反序列化：没有使用安全 loader 的 `pickle` / `marshal` / `shelve` / `yaml.load`
- 动态代码执行：`eval` / `exec`（排除了 `ast.literal_eval`）
### 代码质量检查
- 超过配置的最大长度限制的行（默认：120 个字符，通过 `quality_rules.max_line_length` 设置）
- 通过 Python 的 `ast` 检测未使用的 import，并通过文本使用情况检查来把关以避免误报。`__init__.py`、`from __future__ import`、通配符 import 和带有 `# noqa` 的行不受此限制
- 函数复杂度：**尚未实现**（为圈复杂度工具保留了存根）
### 依赖审计
- Python：在可用时委托给 `pip-audit`
- Node.js：在可用时委托给 `npm audit`
- **当审计无法运行时会醒目报错。** 解析错误、超时或崩溃将被报告为 `HIGH`（DEP005 / DEP006），而不是静默通过，因此“0 findings（未发现隐患）”绝不意味着“未进行任何检查”
### 抑制
对于故意包含漏洞的代码（测试夹具、已记录的例外情况），可以通过内联方式进行豁免：
```
API_KEY = "sk-..." # code-validator: ignore
API_KEY = "sk-..." # code-validator: ignore[SEC001]
# code-validator: ignore-file[SEC004] # 整个文件，选定的规则
# code-validator: ignore-file # 整个文件，所有规则
```
由于某些规则（如 CORS）是针对文件而不是单行报告的，因此存在文件级别的标记。
### 报告
- **HTML**：人类可读的浏览器报告，带有颜色编码的严重性提示卡
- **JSON**：用于 CI/CD 集成的机器可读输出
- **Console**：打印到 stdout 的摘要，包含每个严重级别的计数
### Git 集成
- `--git-diff` 模式：仅扫描自 `HEAD` 以来更改过的文件，保持 CI 运行快速
## 技术栈
| 组件 | 详情 |
|-----------|--------|
| 语言 | Python 3.9+ |
| 核心依赖 | `pydantic == 2.13.4` |
| 可选 | `pip-audit >= 2.6.0`（Python 依赖审计） |
| CI | GitHub Actions |
不进行任何外部 API 调用。完全离线运行。
## 设置
```
# 克隆或复制 repository
git clone https://github.com/TTMK7777/code-validator.git
cd code-validator
# 安装依赖（仅需要 pydantic）
pip install -r requirements.txt
# 可选：启用 Python 依赖审计
pip install pip-audit
```
需要 Python 3.9 或更高版本。
## 用法
### 扫描目录
```
python validator.py --path /path/to/project
```
### 仅扫描最新提交中更改的文件（推荐用于 CI）
```
python validator.py --git-diff
```
### 扫描特定的提交范围
```
python validator.py --git-diff --from HEAD~3 --to HEAD
```
### 生成 HTML 报告
```
python validator.py --path . --output report.html --format html
```
### 生成 JSON 报告
```
python validator.py --path . --output report.json --format json
```
### 使用自定义配置文件
```
python validator.py --path . --config config/validator_config.json
```
### CLI 参考
```
usage: validator.py [-h] [--path PATH] [--git-diff] [--output OUTPUT]
[--format {html,json}] [--config CONFIG]
optional arguments:
--path PATH Project path to scan (default: current directory)
--git-diff Scan only files changed since HEAD
--output OUTPUT Output file path for the report
--format Report format: html | json (default: html)
--config CONFIG Path to a custom JSON configuration file
```
**退出码：** `0` = 未发现 critical/high 问题，`1` = 检测到至少一个 critical 或 high 问题（可用于拦截 CI pipeline）。
## 配置
编辑 `config/validator_config.json` 以自定义行为：
```
{
"exclude_patterns": [
"**/node_modules/**",
"**/venv/**",
"**/__pycache__/**",
"**/.git/**"
],
"file_extensions": [".py", ".js", ".ts", ".tsx", ".json", ".yaml", ".yml"],
"security_rules": {
"check_credentials": true,
"check_cors": true,
"check_sql_injection": true,
"check_dangerous_calls": true
},
"quality_rules": {
"max_line_length": 120,
"check_unused_imports": true,
"check_complex_functions": true
},
"dependency_rules": {
"check_python": true,
"check_node": true
}
}
```
| 键 | 效果 |
|-----|--------|
| `exclude_patterns` | 从扫描中排除的 Glob 模式（同时匹配项目相对路径和绝对路径） |
| `file_extensions` | 扫描目录时收集的扩展名 |
| `security_rules.check_credentials` | SEC001–SEC003, SEC008–SEC010 |
| `security_rules.check_cors` | SEC004–SEC005 |
| `security_rules.check_sql_injection` | SEC006 |
| `security_rules.check_dangerous_calls` | SEC011–SEC013 |
| `quality_rules.max_line_length` | QUAL001 阈值 |
| `quality_rules.check_unused_imports` | QUAL002 |
| `quality_rules.check_complex_functions` | 保留字段；该检查仅为存根，不会输出任何内容 |
| `dependency_rules.check_python` | 委托给 `pip-audit`（DEP001, DEP002, DEP005） |
| `dependency_rules.check_node` | 委托给 `npm audit`（DEP003, DEP004, DEP006） |
只有通过 `--config` 显式传递时，才会应用配置文件。否则，将使用上面的默认值。
## CI/CD 集成
### GitHub Actions
将以下工作流添加到你的代码库中（`.github/workflows/code-validation.yml`）：
```
name: Code Validation
on:
push:
branches: [main, develop]
pull_request:
branches: [main, develop]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 2 # required for --git-diff
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
- name: Install dependencies
run: |
pip install -r requirements.txt
pip install pip-audit || echo "pip-audit not available"
- name: Run Code Validator
run: python validator.py --git-diff --output validation-report.json --format json
- name: Upload validation report
uses: actions/upload-artifact@v4
if: always()
with:
name: validation-report
path: validation-report.json
```
当发现 critical 或 high 严重性的问题时，验证器会以退出码 `1` 退出，这将自动拦截 CI 任务。
### GitLab CI
```
code-validation:
image: python:3.11-slim
script:
- pip install -r requirements.txt
- pip install pip-audit || true
- python validator.py --git-diff --output validation-report.json --format json
artifacts:
paths:
- validation-report.json
when: always
```
## 检测规则
| 规则 ID | 严重性 | 类别 | 描述 |
|---------|----------|----------|-------------|
| SEC001 | Critical | 安全性 | 检测到硬编码的 API key（OpenAI / Anthropic / Google / GitHub） |
| SEC002 | Critical | 安全性 | 检测到硬编码的密码 |
| SEC003 | Critical | 安全性 | 检测到硬编码的数据库凭证 |
| SEC004 | Critical | 安全性 | CORS 通配符 origin + 启用 credentials |
| SEC005 | High | 安全性 | CORS 通配符 origin（生产环境风险） |
| SEC006 | High | 安全性 | 通过 f-string、`+`、`.format()` 或 `%` 进行潜在 SQL 注入 |
| SEC008 | Critical | 安全性 | 硬编码的 `SECRET_KEY`（Django / Flask 会话签名） |
| SEC009 | Critical | 安全性 | 硬编码的 AWS 访问密钥或秘密访问密钥 |
| SEC010 | Critical | 安全性 | 源码中嵌入了 PEM 私钥 |
| SEC011 | High | 安全性 | 通过 shell 执行进行命令注入 |
| SEC012 | High | 安全性 | 不安全的反序列化（`pickle` / `marshal` / `yaml.load`） |
| SEC013 | High | 安全性 | 动态代码执行（`eval` / `exec`） |
| QUAL001 | Low | 质量 | 行超过最大长度限制 |
| QUAL002 | Low | 质量 | 未使用的 import |
| DEP001 | Info | 依赖 | 未安装 `pip-audit` |
| DEP002 | High | 依赖 | 带有已知 CVE 的 Python 包 |
| DEP003 | Variable | 依赖 | 带有已知 CVE 的 Node.js 包 |
| DEP004 | Info | 依赖 | 未安装 `npm` |
| DEP005 | **High** | 依赖 | **`pip-audit` 无法运行** —— 依赖审计未执行 |
| DEP006 | **High** | 依赖 | **`npm audit` 无法运行** —— 依赖审计未执行 |
## 示例输出
```
============================================================
Validation Summary
============================================================
Project: /home/user/my-project
Files scanned: 42
Execution time: 0.83s
Issues by severity:
Critical : 0
High : 1
Medium : 2
Low : 5
Info : 1
============================================================
```
## code-validator 对比
| 工具 | 目标 | 速度 | 离线 | 专注 AI 代码 | 无依赖 |
|------|--------|-------|---------|--------------|-----------------|
| **code-validator** | CI 中的 AI 生成代码 | <1s/文件 | ✅ 是 | ✅ 是（专门构建） | ✅ 仅 pydantic |
| Bandit | 通用 Python | 快 | ✅ 是 | ❌ 否 | ❌ 多个依赖 |
| Semgrep | 多语言模式 | 中等 | ⚠️ 混合 | ❌ 否 | ❌ 笨重 |
| GitGuardian | Git 历史记录中的机密 | 慢（API） | ❌ 否 | ❌ 否 | ❌ SaaS |
| TruffleHog | Git 历史记录中的机密 | 慢 | ✅ 是 | ❌ 否 | ❌ 多个依赖 |
**定位：** code-validator 是此列表中*唯一*专门针对 AI 生成代码的故障模式进行调优的工具（例如，LLM 极其容易输出 `CORS wildcard + allow_credentials=True` 模式，或者在模型生成的字符串上使用 `eval`）。
**关于范围的诚实声明：** 这是一个面向行的模式扫描器，而不是数据流分析器。它不执行污点追踪，因此它标记的是已知有风险的代码*形状*，而不是证明从不受信任的输入到接收器的路径。对于深度的数据流分析，请将其与 Semgrep 或 CodeQL 配合使用——这个工具的意义在于提供亚秒级的门禁，而不是替代品。
## 常见问题解答
### 问：为什么需要一个专门针对 AI 生成代码的单独工具？我不能直接用 Bandit 或 Semgrep 吗？
通用的 linter 是为人类编写的代码设计的。AI 助手表现出特定的故障模式——硬编码的示例凭证、为了演示而过度宽松的 CORS、因为模型“回忆起”了前 ORM 时代的模式而产生的字符串拼接 SQL。code-validator 的规则集是针对这些模式进行调优的，并相应地权衡了严重性。
### 问：code-validator 会把我的代码发送到任何地方吗？
不。扫描器完全离线运行。唯一可选的网络调用是用于 CVE 查询的 `pip-audit`，并且它只联系官方的 PyPA 公告数据库——绝不会发送你的源代码。
### 问：这与分别运行 Bandit + `truffleHog` + `pip-audit` 有什么不同？
code-validator 将它们统一到一个 CI 步骤中，具有连贯的严重性模型和统一的报告格式（HTML / JSON）。对于 `--git-diff` 模式，仅扫描当前 PR 中更改的文件，从而保持 CI 的快速运行。
### 问：我可以自定义检测规则吗？
可以——请参阅 `config/validator_config.json`，并使用 `--config` 传递。你可以禁用规则类别、更改行长度阈值以及添加排除模式。该文件中的每个键都会生效；请参阅[配置](#configuration)中的表格。
### 问：我该如何豁免故意包含漏洞的代码？
使用内联的 `# code-validator: ignore` 注释——请参阅[抑制](#suppression)。本代码库自身的测试夹具就是通过这种方式通过门禁的。
### 问：如果 `pip-audit` 运行失败会怎样？
你会收到一个 `HIGH` 级别的发现（DEP005），这将导致 CI 失败。这是故意的：无法执行的审计绝不能被报告为绿色（通过）。
### 问：它适用于 Claude Code、Cursor、GitHub Copilot 的输出吗？
是的。无论是由哪个 AI 助手生成的，它都会扫描生成的源文件。检测模式针对的是*输出*，而不是工具。
### 问：我需要哪个 Python 版本？
Python 3.9 或更高版本。
### 问：有 pre-commit hook 吗？
在 pre-commit hook 中使用 `python validator.py --git-diff` —— 当发现 critical/high 问题时，退出码 `1` 会拦截提交。
## 作者
由 **Taimu Tsuji (辻大夢)** 构建 —— [Tsuji Lab](https://github.com/TTMK7777) 创始人，专注于多 Agent AI 协调和大规模 AI 辅助软件开发的应用 AI 架构师。
- **经验：** 4 个并行项目中交付了约 140 万行 AI 辅助代码；通过 Claude Code 自动化每年节省了约 8,000 个工程小时。
- **专长：** Claude Agent SDK、MCP、多 Agent 编排、AI 安全门禁。
- **为什么开发这个工具：** 在多次看到 AI 生成的 PR 中包含 `allow_origins=["*"]` 之后，我需要一个能在 <1s 内运行且不将代码发送到外部的门禁。现有的工具要么太重，要么太吵，或者需要 SaaS。
GitHub：[@TTMK7777](https://github.com/TTMK7777)
## 结构化数据 (Schema.org)
用于 AI 搜索引擎和开发者工具索引：
```
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "code-validator",
"alternateName": "AI Code Security Scanner",
"applicationCategory": "DeveloperApplication",
"operatingSystem": "Linux, macOS, Windows",
"description": "Static security scanner for AI-generated code. Detects hardcoded credentials, CORS misconfigurations, SQL injection patterns, and dependency CVEs in under 1 second per file, fully offline.",
"url": "https://github.com/TTMK7777/code-validator",
"license": "https://opensource.org/licenses/MIT",
"programmingLanguage": "Python",
"softwareRequirements": "Python 3.9+",
"author": {
"@type": "Person",
"name": "Taimu Tsuji",
"alternateName": "辻大夢",
"jobTitle": "Founder, Tsuji Lab",
"url": "https://github.com/TTMK7777"
},
"keywords": "AI security, static analysis, code validation, AI-generated code, CI/CD security, secret detection, CORS validation, dependency audit, Claude Code, GitHub Copilot, LLM security"
}
```
## 许可证
MIT 许可证。详情请参阅 [LICENSE](LICENSE)。
## 贡献
欢迎提交 Issue 和 PR。有关安全相关的发现，请参阅 [SECURITY.md](SECURITY.md)。
标签：AI代码安全, DevSecOps, DOE合作, Python, 上游代理, 代码安全审计, 安全检查工具, 无后门, 静态代码扫描