hzj-Jeff-07/AI-CodeGuard
GitHub: hzj-Jeff-07/AI-CodeGuard
一款结合 Tree-sitter AST 静态预过滤与 LLM 智能确认的两阶段 AI 代码安全扫描工具，旨在精准发现多语言代码中的漏洞并降低误报率。
Stars: 1 | Forks: 0
# AI-CodeGuard
## 当前状态
AI-CodeGuard 目前处于 **Phase 1** 阶段，但 runtime pipeline 已不再仅限于 Stage 1。
目前已实现的功能：
- CLI 命令：`scan`、`init`、`rules` (`--list`、`validate`、`create`、`test`)
- 本地扫描支持 **JavaScript、TypeScript、Python、Go 和 Java (MVP)**
- **13 条内置基于 OWASP 的规则**
- 可选的 YAML 自定义规则加载，通过 `rules.custom` 实现
- 通过 **`rules validate/create/test`** 实现自定义规则 CLI 工作流
- 支持 **text、JSON、SARIF** 格式的报告输出
- 当 `scan` 在不带 `--dry-run` 参数运行时，通过 **Claude** 或 **OpenAI** 进行 Stage 2 LLM 分析
- 通过 `--fix` 提供可选的修复建议
- 通过 `.codeguard.yml` / 环境变量加载配置
- 用于 Stage 2 LLM 结果的磁盘缓存（`cache.enabled`），已接入扫描 pipeline
- GitHub composite Action (`action.yml`) 以及 CI / SARIF 上传工作流
- 自动化验证，包含 **10 个测试文件中的 225 个通过测试**（2026 年 7 月 4 日的 `npm run test:run` 结果）
目前**尚未**完成的内容：
- 超出 2 条规则 MVP 范围的 Java 覆盖（计划加入凭据 / 路径遍历 / SSRF）
- npm 发布 / 版本化发布（目前还没有 `v0.2.0` 标签）
### 完成情况快照
| 里程碑 | 状态 | 含义 |
|----------|--------|---------|
| M0 Phase 1 CLI 基线 | 已完成 | `scan` / `init` / `rules --list` 可用 |
| M1 Stage 2 Analyzer | 已完成 | 非 `--dry-run` 扫描可运行 LLM 确认 |
| M2 `--fix` 建议 | 已完成 | 确认的 Stage 2 扫描结果可包含 `fix` |
| M3 Tree-sitter 解析器 | 已完成 | 主解析器现在使用基于 Tree-sitter 的规范化 AST |
| M4 自定义规则 runtime | 已完成 | `rules.custom` 已接入 `scan()`，且 `rules validate/create/test` 可用 |
| M5 GitHub / CI 集成 | 已完成 | 存在 composite `action.yml`、`ci.yml` 和 `security-scan.yml`（将 SARIF 上传至 Code Scanning）且通过测试 |
| M6 更多语言 | 已完成 (MVP 范围) | Go：5 条规则；Java：2 条规则的 MVP (SQL + 命令注入) |
### 术语
为保证文档的一致性：
- **Phase 1** = 当前发布的产品阶段：可用的本地 CLI 基线
- **Stage 1** = runtime pipeline 的静态预过滤阶段
- **Stage 2** = runtime pipeline 的 LLM 确认 / 增强阶段
当前事实：代码库仍处于 **Phase 1**，且 `scan()` 现在支持 **Stage 1 + Stage 2**。使用 `--dry-run` 可在 Stage 1 之后停止。
## 目前可用的功能
### CLI 命令
```
# 构建 CLI
npm install
npm run build
# 在当前项目中初始化 config
node dist/index.js init
# 仅 Stage 1
node dist/index.js scan ./src --dry-run
# 包含 Stage 2 的完整扫描
export CODEGUARD_API_KEY="..."
node dist/index.js scan ./src
# 在 Stage 2 期间请求修复建议
node dist/index.js scan ./src --fix
# 输出 JSON 或 SARIF
node dist/index.js scan ./src --output json
node dist/index.js scan ./src --output sarif --output-file report.sarif
# 列出内置规则
node dist/index.js rules --list
# 创建一个起始自定义规则文件
node dist/index.js rules create ./custom-rules/example.yml
# 验证自定义规则 YAML
node dist/index.js rules validate ./custom-rules
# 运行仅 Stage 1 的自定义规则冒烟测试
node dist/index.js rules test ./custom-rules ./src --output json
```
### 作为 GitHub Action 使用
添加一个工作流，扫描每个 Pull request 并将结果上传到 GitHub Code Scanning（Security 标签页）：
```
name: security-scan
on: [pull_request]
permissions:
contents: read
security-events: write
jobs:
codeguard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: AI-CodeGuard scan
id: scan
uses: hzj-Jeff-07/AI-CodeGuard@main
with:
paths: ./src
output-file: ai-codeguard.sarif
# dry-run: 'false' # enable Stage 2 LLM confirmation
# api-key: ${{ secrets.CODEGUARD_API_KEY }}
- name: Upload SARIF to Code Scanning
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: ai-codeguard.sarif
category: ai-codeguard
```
默认行为：仅运行 Stage 1（无需 API key），遇到 critical/high 级别的发现时将使任务失败。所有输入参数和更多方案请见：[docs/dev/GITHUB-ACTION.md](./docs/dev/GITHUB-ACTION.md)。
### 支持的语言
| 语言 | 扩展名 | 规则覆盖范围 |
|----------|------------|---------------|
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | 所有 13 条内置规则 |
| TypeScript | `.ts`, `.tsx` | 所有 13 条内置规则 |
| Python | `.py` | 所有 13 条内置规则 |
| Go | `.go` | `CG-001` SQL 注入，`CG-002` 命令注入，`CG-020` 硬编码凭据，`CG-030` 路径遍历，`CG-060` SSRF |
| Java | `.java` | MVP：`CG-001` SQL 注入（包含 `String.format`），`CG-002` 命令注入（`Runtime.exec`、`ProcessBuilder`） |
### 内置规则集
| 类别 | 规则 ID | 备注 |
|----------|----------|-------|
| Injection | `CG-001`, `CG-002`, `CG-003` | SQL 注入、命令注入、eval/代码注入；`CG-001`/`CG-002` 也涵盖 Go 和 Java |
| XSS | `CG-010`, `CG-011` | 反射型/DOM 型 XSS |
| Auth / Crypto | `CG-020`, `CG-021` | 硬编码凭据（亦包含 Go），弱加密 |
| Path | `CG-030`, `CG-031` | 路径遍历（亦包含 Go），任意文件读/写 |
| Data | `CG-040`, `CG-041` | 敏感数据暴露，不安全的反序列化 |
| Config | `CG-050` | 安全配置错误 |
| SSRF | `CG-060` | 服务端请求伪造（亦包含 Go） |
总计：**13 条内置规则**。
### 自定义规则 Runtime
当前的 runtime 还支持通过配置使用可选的 YAML 自定义规则：
```
rules:
preset: none
custom: ./custom-rules
```
当前限制：
- `rules.custom` 可以指向一个 YAML 文件或目录
- 目录会递归加载 `*.yml` / `*.yaml`
- `disable` 通过规则 ID 应用于内置和自定义规则
- `rules --list` 显示内置规则以及配置中的自定义规则（支持 `--config`）
- `rules create` 写入一个最小化的 YAML 骨架并支持 `--force`
- `rules validate` 检查 YAML 解析、schema 有效性以及重复的规则 ID
- `rules test` 是一个**仅限 Stage 1** 的自定义规则冒烟测试路径，因此它不需要 API key
## 当前扫描的工作原理
当前的 runtime pipeline 为：
1. 使用 `fast-glob` 发现文件
2. 根据文件扩展名检测语言
3. 使用 **基于 Tree-sitter 的规范化解析器** 解析每个文件
4. 加载内置规则以及可选的自定义 YAML 规则
5. 运行规则以产生可疑节点
6. 将可疑节点转换为 Stage 1 扫描结果
7. 如果**未**启用 `--dry-run`，对这些候选项运行 Stage 2 LLM 分析
8. 将输出渲染为 text / JSON / SARIF
重要的 runtime 行为：
- `--dry-run` 表示**仅限 Stage 1**，因此 `llmCalls = 0` 且 `estimatedCost = 0`
- 到达 Stage 2 的非 dry-run 扫描需要 `llm.apiKey` 或受支持的环境变量
- 确认的 Stage 2 扫描结果会获得 `llmAnalysis`，并且 `--fix` 可以添加 `fix`
- LLM 未确认的扫描结果将被移至 `dismissedFindings`（JSON 输出）并附带 LLM 的推理过程，同时文本摘要会显示被驳回的数量 —— Stage 2 的抑制保持可审计
- Stage 2 的 prompt 将被扫描的代码视为不受信任的数据，因此针对被扫描代码中试图诱导 LLM 驳回某一发现的情况，已明确予以禁止（prompt 注入加固）
- 当达到 `llm.maxCostUSD` 时，新的 LLM 调用将停止，剩余未分析的扫描结果将保留为 Stage 1 扫描结果
- 当 `cache.enabled` 为 `true` 时，Stage 2 的结果将持久化到 `cache.directory`（默认为 `.codeguard-cache/`）；重复扫描在复用它们时，针对缓存条目的 `llmCalls = 0` 且 `estimatedCost = 0`
## 配置
运行 `init` 以生成初始配置：
```
scan:
include:
- "src/**/*.{ts,js,py,go,java}"
- "lib/**/*.{ts,js,py,go,java}"
exclude:
- "node_modules"
- "dist"
- "build"
- "**/*.test.*"
- "**/*.spec.*"
rules:
preset: owasp-top-10
llm:
provider: claude
model: claude-sonnet-5
maxConcurrency: 5
output:
format: text
```
### 配置和环境变量
加载器支持：
- `.codeguard.yml`
- `.codeguard.yaml`
- `.codeguard.json`
- `codeguard.config.js`
- `codeguard.config.ts`
配置加载器目前支持的环境变量覆盖：
- `CODEGUARD_API_KEY`
- `ANTHROPIC_API_KEY`
- `OPENAI_API_KEY`
- `CODEGUARD_MODEL`
- `CODEGUARD_MAX_COST`
Stage 2 目前使用：
- `llm.provider`
- `llm.model`
- `llm.apiKey`
- `llm.maxConcurrency`
- `llm.maxCostUSD`
Stage 2 磁盘缓存由以下选项控制（默认禁用）：
```
cache:
enabled: true
directory: .codeguard-cache
ttl: 86400
```
注意：提供商选择是在配置文件中配置的，而不是通过专门的环境变量。
## 输出格式
### Text
人类可读的终端摘要，包含严重程度、位置、代码片段、可选的修复建议、可选的 LLM 推理以及汇总计数。
### JSON
结构化的机器可读输出，包含：
- 扫描元数据
- 扫描结果
- 跳过的文件
- 可选的 `fix` 和 `llmAnalysis`
### SARIF
适用于下游工具的 SARIF v2.1.0 输出，包含可选的 SARIF 修复和 LLM markdown 上下文。
SARIF 输出可与 GitHub Code Scanning 集成：该代码库提供了一个 composite Action (`action.yml`) 和一个 `security-scan.yml` 工作流，该工作流运行 Stage 1 扫描并通过 `github/codeql-action/upload-sarif` 上传 SARIF 报告。
## 代码库结构
```
ai-codeguard/
├── src/
│ ├── analyzer/ # Stage 2 orchestration and provider adapters
│ ├── cli/ # Commander.js entry and commands
│ ├── config/ # Config schema, defaults, loader
│ ├── parser/ # Tree-sitter runtime, normalization, and adapters
│ ├── reporter/ # text / json / sarif formatters
│ ├── rules/ # Built-in + custom rule loading and execution
│ ├── scanner/ # File discovery and orchestration
│ └── types/ # Shared TypeScript types
├── docs/
│ ├── README.md # Documentation entrypoint and reading guide
│ ├── adr/
│ │ └── decisions.md
│ ├── design/
│ │ ├── TECHNICAL-SUMMARY.md
│ │ ├── core-modules.md
│ │ ├── CONFIGURATION.md
│ │ ├── RULES.md
│ │ ├── REPORTING.md
│ │ └── LLM-INTEGRATION.md
│ └── dev/
│ ├── CLI-EXAMPLES.md
│ ├── ROADMAP.md
│ └── TESTING.md
├── tests/
│ ├── fixtures/
│ ├── integration/
│ └── unit/
├── ARCHITECTURE.md
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── vitest.config.ts
```
## 验证
于 2026 年 7 月 4 日验证：
```
npm run build
npm run test:run
```
结果：
- 构建通过
- `10` 个测试文件通过
- `225` 个测试通过
## 限制
当前已知的限制：
- 默认的非 dry-run 扫描在进入 Stage 2 时需要 API key
- 解析器使用 Tree-sitter 以及保持兼容性的规范化 AST 层
- 模型成本限制依赖于内置的定价表；如果为未知模型设置了 `llm.maxCostUSD`，扫描将快速失败
- `rules test` 被特意设计为仅限 Stage 1，不会触发 Stage 2
- Go 支持涵盖 5 条规则（`CG-001`/`CG-002`/`CG-020`/`CG-030`/`CG-060`）；Java 涵盖 2 条规则（`CG-001`/`CG-002`）。Stage 1 没有数据流分析，因此内联的 `db.Query(fmt.Sprintf(...))` / `executeQuery(String.format(...))` 可能会同时报告外部调用和内部格式化调用
- `config.output.format` 已定义，但 scan 命令的 CLI 默认设置仍倾向于使用 text，除非显式提供 `--output`
- 修复建议仅供参考；CLI 不会自动重写文件
## 文档
- [docs/README.md](./docs/README.md) — 文档入口、术语指南和推荐阅读顺序
- [ARCHITECTURE.md](./ARCHITECTURE.md) — 当前实现架构
- [docs/design/core-modules.md](./docs/design/core-modules.md) — 当前代码库的逐模块解析
- [docs/design/TECHNICAL-SUMMARY.md](./docs/design/TECHNICAL-SUMMARY.md) — 实现状态、验证情况和下一步优先级
- [docs/design/CONFIGURATION.md](./docs/design/CONFIGURATION.md) — 配置模型、默认值、环境变量覆盖和 runtime 消耗边界
- [docs/design/RULES.md](./docs/design/RULES.md) — 当前内置 + 自定义规则加载行为、规则行为及已知限制
- [docs/design/REPORTING.md](./docs/design/REPORTING.md) — text / JSON / SARIF 输出行为及当前输出限制
标签：DLL 劫持, GitHub Action, IPv6支持, Petitpotam, 代码安全扫描, 多包管理, 大语言模型, 自动化攻击, 错误基检测, 静态代码分析