# CodeGuard Tutor

**Repository Path**: celinaN/code-guard-tutor

## Basic Information

- **Project Name**: CodeGuard Tutor
- **Description**: 一款面向初学开发者的 VS Code 内嵌式 Web 代码安全复	核与修复学习插件

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-06-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeGuard Tutor

CodeGuard Tutor 是一个面向初学者、课程项目和轻量代码实验场景的 VS Code 代码安全辅助工具。
当前仓库的主线目标不是一次做成完整企业级扫描平台，而是先把“插件触发 -> 后端规则分析 -> 上下文补全 -> 可选 AI 解释 -> 结果展示”的主链稳定下来。

## 项目定位

项目当前强调三件事：

- 在 VS Code 中直接触发分析
- 先用规则、AST 与基础污点传播发现风险候选
- 为后续 Context / AI 解释层保留稳定输入

AI 不是风险发现者，只负责在用户选择后解释引擎已经生成的 `RiskItem`。

## 当前真实能力

截至目前，仓库里已经稳定落地的是：

- VS Code 插件可向后端 `/analyze` 发送代码分析请求
- Python 项目模式可向 `/analyze-project` 一次发送入口文件与 import 关联文件
- 后端主线稳定支持 `python`，并已接入 JavaScript 四类核心风险轻量检测
- Python 已实现 `SQLInjection`、`XSS`、`HardcodedSecret`、`DangerousFunction`
- JavaScript 已实现 `SQLInjection`、`XSS`、`HardcodedSecret`、`DangerousFunction`
- 后端分析引擎已经具备：
  - Python AST 解析
  - 统一 `SourceInfo` 来源模型（Flask / Django / FastAPI 常见输入源）
  - 统一 SQL 形态分类入口 `match_sql_shape(...)`
  - `execute()` sink 判断
  - SQL 注入同文件函数调用传播
  - Python SQL 注入、XSS、危险函数的跨文件参数与返回值传播
  - Python import / relative import / 模块别名调用解析
  - 跨文件证据步骤的文件路径与 `context_files`
  - XSS 的 `source -> HTML build -> sink` 轻量数据流分析
  - 危险函数轻量数据流分析
  - 硬编码密钥变量名与占位符误报控制
  - JavaScript 四类风险轻量行扫描规则链
  - 安全 SQL 模板变量放行
  - 中间结果 `IntermediateAnalyzeResult`
  - 最终结果 `AnalyzeResponse`
- `RiskItem.needs_more_context` 可区分明确风险与待补上下文候选
- Python 与 JavaScript 选区分析使用统一的文件内上下文扩展条件
- 插件可选择跳过解释、仅使用大模型，或结合上传资料生成解释
- 未选择解释来源时只展示引擎状态与攻击路径；解释增强后再展示风险说明、修复建议和代码对比

当前还没有完整落地的部分包括：

- JavaScript 深度 AST / 跨文件数据流
- 更多语言与更多漏洞类型
- Python 动态 import、通配符 import、类实例方法和依赖注入调用解析

## 当前分析主线

当前 Python SQL 注入主线可以概括为：

1. 插件读取选区或当前文件代码并请求 `/analyze`
2. 后端将代码解析为 Python AST
3. `source_rules.py` 识别不可信输入来源
4. `pattern_matcher.py` 通过 `match_sql_shape(...)` 统一判断 SQL 形态
5. `sink_rules.py` 判断 `execute()` 是否属于安全参数化执行
6. `flow/python/sql_injection/analyzer.py` 进行表达式污点传播与危险 SQL 判定
7. `engines/python/sql_injection.py` 与 `sql_injection_evaluator.py` 输出 `IntermediateAnalyzeResult`
8. `result_converter.py` 将 `RiskCandidate` 转成插件可消费的 `AnalyzeResponse`
9. 用户选择解释来源时，`/enrich-explanations` 将完整 `RiskItem` 交给受约束的大模型生成详细说明

Python 跨文件模式在此基础上增加：

1. 插件从当前文件出发按 import 依赖图广度优先收集文件
2. 直接依赖优先于二级、三级依赖
3. 插件最多发送 29 个关联文件，加入口文件共 30 个
4. 后端重新校验文件数量、单文件大小和总请求大小
5. `PythonProjectIndex` 建立模块、import 和函数索引
6. 四类检测直接复用索引 AST，不重复解析项目文件
7. 三类 flow analyzer 在函数调用边界切换模块作用域并继续传播

当前 Python 危险函数主线类似：

1. `dangerous_call_rules.py` 识别 `eval`、`exec`、`os.system`、`subprocess.*(..., shell=True)`、`pickle.load(s)` 等危险调用
2. `source_rules.py` 识别不可信输入
3. `flow/python/dangerous_function/analyzer.py` 追踪 source 到 dangerous call 的传播
4. `engines/python/dangerous_function.py` 将 flow finding 转成统一 engine finding
5. `dangerous_function_evaluator.py` 输出 `RiskCandidate`

当前 Python XSS 主线类似：

1. `source_rules.py` 识别 Flask / Django / FastAPI / Starlette 常见 HTTP 输入
2. `xss_rules.py` 识别 HTML 构造、HTML 输出点和安全 escape
3. `flow/python/xss/analyzer.py` 追踪 `source -> HTML build -> sink`
4. `engines/python/xss.py` 将 flow finding 转成统一 engine finding
5. `xss_evaluator.py` 输出 `RiskCandidate`

当前 JavaScript 轻量检测主线类似：

1. `line_utils.py` 去掉常见注释并产出有效代码行
2. `rules/javascript/secret_rules.py` 识别变量、对象字段、下标赋值中的硬编码密钥
3. `rules/javascript/dangerous_call_rules.py` 识别 `eval`、`new Function`、字符串定时器和 `child_process`
4. `rules/javascript/sql_rules.py` 识别动态 SQL 和数据库调用 sink
5. `rules/javascript/xss_rules.py` 识别 HTML 构造和 DOM / 响应 sink
6. `engines/javascript/*` 将规则命中转成统一 engine finding
7. `decision/javascript/*` 输出 `RiskCandidate`

## 当前支持的主要检测能力

当前后端主线已经覆盖 Python 四类核心风险，并接入 JavaScript 四类核心风险轻量检测。Python 的 SQL 注入、XSS、危险函数侧重 source -> sink 数据流，硬编码密钥侧重静态字面量规则；JavaScript 当前用变量级传播和高确定性规则覆盖常见写法。

### 已支持的 Source

- `request.args.get(...)`
- `request.form.get(...)`
- `request.values.get(...)`
- `request.json.get(...)`
- `request.GET.get(...)`
- `request.POST.get(...)`
- `request.query_params.get(...)`
- `request.args[...]`
- `request.form[...]`
- `request.json[...]`
- `request.GET[...]`
- `request.POST[...]`
- `request.query_params[...]`
- `Query(...)` / `fastapi.Query(...)`
- `input()`
- `sys.argv[...]`
- `os.getenv(...)`
- `os.environ.get(...)`
- `os.environ[...]`

### 已支持的 SQL 形态分类

`pattern_matcher.py` 当前通过 `match_sql_shape(...)` 统一输出三类 SQL 形态：

- `static_literal`：固定 SQL 字面量
- `parameterized_template`：带占位符的参数化 SQL 模板
- `dynamic_sql`：动态拼接 SQL

需要注意：

- 当前主线里，真正直接参与风险判定的是 `dynamic_sql`
- `parameterized_template` 主要用于“安全参数化执行”放行
- `static_literal` 当前主要用于分类语义和后续扩展准备，不会单独产生风险结果

### 已支持的动态 SQL 形态

- f-string 构造 SQL
- 字符串 `+` 拼接 SQL
- `%` 格式化 SQL
- `.format()` 构造 SQL

### 已支持的 Sink

- `execute(...)`
- `xxx.execute(...)`

### 已支持的 XSS 输出点

- `render_template_string(...)`
- `HTMLResponse(...)`
- `HttpResponse(...)`
- `Response(...)`
- `make_response(...)`
- `return HTML`

### 已支持的 JavaScript 轻量场景

- SQL 注入：`req.query` / `req.body` / `req.headers` 等输入进入模板字符串 SQL 或拼接 SQL，再流入 `query/execute/raw/run/all/get/$queryRawUnsafe/$executeRawUnsafe`
- XSS：输入进入 `innerHTML`、`outerHTML`、`insertAdjacentHTML`、`document.write`、动态 HTML 响应、jQuery HTML 写入、React `dangerouslySetInnerHTML` 等 HTML sink
- 硬编码密钥：`const apiKey = "..."`、对象字段、下标赋值
- 危险函数：`eval(...)`、`new Function(...)`
- 字符串定时器：`setTimeout("...")`、`setInterval("...")`
- Node 命令执行：`child_process.exec(...)`、`execSync(...)`、`spawn(cmd, [], { shell: true })`
- 常见 `child_process` require/import 别名
- 浏览器侧输入：`location.search`、`document.cookie`、`localStorage.getItem(...)`
- 参数化查询、`escapeHtml` / `DOMPurify.sanitize` 等安全写法会尽量放行

### 已做的安全写法放行

- `execute("SELECT ... WHERE id = ?", params)`
- `execute("SELECT ... WHERE id = %s", params)`
- `sql = "SELECT ... WHERE id = ?"` 后再执行 `execute(sql, params)`
- `sql = "SELECT ... WHERE id = %s"` 后再执行 `execute(sql, params)`

当前 `flow/python/sql_injection/analyzer.py` 内部会维护 `safe_sql_template_variables`，用于在“安全模板先赋给变量、再进入 `execute(sql, params)`”时继续识别为安全写法。

更完整的实现结构与能力边界见
[Architecture](docs/architecture.md) 和
[B 阶段跨文件联合分析设计](docs/B阶段跨文件联合分析设计.md)。

## 当前目录结构

```text
code-guard-tutor/
├── vscode-extension/
├── backend/
│   ├── api/routes/analyze.py
│   ├── api/routes/analyze_project.py
│   ├── core/
│   │   ├── project/python/
│   │   ├── parser/python_parser.py
│   │   ├── rules/python/
│   │   ├── flow/python/sql_injection/analyzer.py
│   │   ├── flow/python/dangerous_function/analyzer.py
│   │   ├── flow/python/xss/analyzer.py
│   │   ├── rules/javascript/
│   │   ├── engines/javascript/
│   │   ├── engines/python/sql_injection.py
│   │   ├── engines/python/xss.py
│   │   └── decision/python/sql_injection_evaluator.py
│   └── schemas/
├── tests/
├── docs/
└── README.md
```

## 运行方式

### 启动后端

第一次运行建议先安装依赖：

```powershell
cd backend
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn app:app --host 127.0.0.1 --port 8000 --reload
```

启动后可访问：

- `http://127.0.0.1:8000/docs`

### 运行后端测试

```powershell
cd backend
python -m pip install -r requirements.txt
python -m pytest tests
```

### 启动 VS Code 扩展

第一次运行建议先安装前端依赖：

```powershell
cd vscode-extension
npm install
npm run compile
```

然后：

1. 用 VS Code 打开仓库根目录
2. 按 `F5`
3. 选择 `Run CodeGuard Tutor Extension`
4. 在 Extension Development Host 中打开 `.py` 文件
5. 运行命令：
   - `CodeGuard 导师：分析选中片段`
   - `CodeGuard 导师：分析当前文件`

输出面板名称为 `CodeGuard 导师`。

说明：`vscode-extension/out/` 是 `npm run compile` 生成的本地编译产物，扩展运行会用到它，但版本库不跟踪该目录。

## 文档索引

- [开发框架契约](CodeGuard_Tutor_开发框架契约.md)
- [API Contract](docs/api_contract.md)
- [Architecture](docs/architecture.md)
- [B 阶段 Detector 架构与规则说明](docs/B阶段Detector架构与规则说明.md)
- [开发变更记录](docs/开发变更记录.md)
- [Shared Schemas](shared/schemas.md)
- [B 阶段输出给 AI 的说明](docs/B阶段输出给AI的说明.md)
- [B 阶段跨文件联合分析设计](docs/B阶段跨文件联合分析设计.md)

## 版本库约定

- 后端依赖写在 `backend/requirements.txt`
- 扩展依赖写在 `vscode-extension/package.json` 与 `vscode-extension/package-lock.json`
- 不提交 `backend/.venv/`、`__pycache__/`、`vscode-extension/out/`、`node_modules/` 等本地环境或构建产物

## 当前阶段说明

当前仓库应按“已经真实实现到哪一步”来理解，而不是按最终目标态理解。
当前重点是：

- 保持 Python SQL 注入、XSS、危险函数、硬编码密钥四类风险主线稳定
- 用 JavaScript 四类轻量 detector 验证多语言 detector 扩展方式
- 明确 A / B / C 的接口边界
- 固定中间 schema
- 让插件、分析引擎、后续 AI 层能稳定对接

另外需要注意，当前函数传播能力仍以“同文件、普通函数、轻量模拟”为边界：

- 支持普通函数调用、参数绑定、默认值、返回值、`global` / `nonlocal`
- Python 项目模式暂不支持动态 import、通配符 import、类实例方法、依赖注入调用和容器元素的精细状态
- Web 框架入口函数当前会作为低置信上下文提示处理，后续仍可继续细化可达性建模