@comate/zulu 1.2.1-beta.1 → 1.3.0

package/comate-engine/assets/skills/code-security-comate/references/vul_repair-php_sql_injection.md

@@ -0,0 +1,318 @@
+php sqli 漏洞修复知识
+
+# PHP SQL 注入漏洞修复最佳实践
+采用先分析漏洞报告 -> 分析数据传递链路 -> 判断依赖与副作用 -> 选择修复方式 -> 修复 -> 校验的流程。
+
+注意：**不要做与漏洞修复无关的代码改动**。
+
+---
+
+## I. 核心修复分析逻辑
+在开始修改代码前，仅需确认以下四点：
+
+1. **分析修复方式**
+
+    * **值绑定**：数据值（如 `id=1`, `name='test'`）-> 必须预编译/参数绑定。
+    * **结构定义**：表名、列名、排序方向等结构化 SQL 片段 -> 必须过滤。
+
+2. **分析数据链路**
+
+    * 确认变量从哪里进入、在哪个 sink 执行。
+    * 检查是否跨函数、跨文件、跨层（Controller -> Service -> DAO）。
+
+3. **依赖与副作用**
+
+    * 修改函数签名后，调用方是否需要同步。
+    * 同一 SQL 在其他位置是否复用，修复是否会影响其他逻辑。
+
+4. **框架能力确认（修复前必做）**
+
+    * 确认当前 DB/DAO 是否支持：`prepare`、`query($sql, $params)`、`execute($sql, $params)`。
+    * **禁止猜测 API**：若代码库中不存在该方法，不可直接使用。
+    * 修复前先查当前类同文件/同包已有调用方式，优先复用项目内已验证的安全写法。
+
+---
+
+## II. Yii (Yii2) 框架修复方案
+Yii 提供了较完善的防注入机制，核心原则：**优先使用数组语法（Hash Format）代替字符串拼接**。
+
+### 1. ActiveRecord / Query Builder（推荐）
+Yii 的 `ActiveRecord` 和 `Query` 在数组条件场景会自动进行参数绑定。
+
+**场景 A：普通条件查询**
+
+```php
+// Bad
+$user = User::find()->where("name = '" . $name . "'")->one();
+
+// Fix
+$user = User::find()->where(['name' => $name])->one();
+
+// 复杂条件
+$users = User::find()->where(['>', 'age', $age])->all();
+```
+**场景 B：IN 查询**
+
+```php
+// Bad
+$ids = $_GET['ids'];
+$users = User::find()->where("id IN ($ids)")->all();
+
+// Fix
+$ids = explode(',', $_GET['ids']);
+$users = User::find()->where(['id' => $ids])->all();
+```
+### 2. DAO / 原生 SQL（createCommand）
+```php
+// Bad
+$sql = "SELECT * FROM post WHERE id=" . $id;
+$posts = Yii::$app->db->createCommand($sql)->queryAll();
+
+// Fix
+$sql = "SELECT * FROM post WHERE id=:id";
+$posts = Yii::$app->db->createCommand($sql)
+    ->bindValue(':id', $id)
+    ->queryAll();
+```
+### 3. `findBySql` 修复
+```php
+// Bad
+$sql = "SELECT * FROM user WHERE status=" . $status;
+$users = User::findBySql($sql)->all();
+
+// Fix
+$sql = "SELECT * FROM user WHERE status=:status";
+$users = User::findBySql($sql, [':status' => $status])->all();
+```
+### 4. 无法预编译场景（Order By / Table Name）
+```php
+$sort = $_GET['sort'];
+$regex = "/^[\w\s\[\]" . "`" . "$.,*]+$/";
+
+if (!preg_match($regex, $sort)) {
+    throw new \yii\web\BadRequestHttpException("Invalid sort parameter");
+}
+
+$users = User::find()->orderBy($sort)->all();
+```
+### 5. Yii 常见错误（必须规避）
+1. `execute()`** 返回值误用**：Yii2 `execute()` 返回影响行数（int），不能继续 `->queryAll()`。
+2. **提前创建 Command**：必须先拼完 SQL，再 `createCommand($sql)`。
+3. **Yii1 **`criteria->params`** 覆盖**：`$criteria->params = [...]` 会覆盖已设置参数，需合并而非覆盖。
+
+---
+
+## III. ODP 框架修复方案
+适用于 `Bd_Db_ConnMgr` 等 DB 封装。
+
+### 1. SQL 模板方式（推荐）
+```php
+$template = "SELECT * FROM users WHERE id={id:n} AND name={name:s}";
+$sqlTemplate = new Bd_Db_SQLTemplate($db);
+$sqlTemplate->prepare($template);
+$sqlTemplate->bindParam('id', $userId);
+$sqlTemplate->bindParam('name', $userName);
+$sql = $sqlTemplate->getSQL();
+```
+### 2. SQL 组合器方式
+```php
+// 安全
+$result = $db->select(
+    'users',
+    ['id', 'name', 'email'],
+    ['id' => $userId, 'status' => 1]
+);
+
+// 危险
+$result = $db->select('users', '*', "id = $userId AND name = '$userName'");
+```
+### 3. 预处理语句方式（以项目实际 API 为准）
+```php
+$stmt = $db->prepare("SELECT * FROM users WHERE id = ? AND name = ?");
+$stmt->bindParam('is', $userId, $userName);
+$result = $stmt->execute();
+```
+### 4. 使用前先确认 API 存在
+* 仅在代码库确认存在 `Bd_Db_SQLTemplate` / `queryf` / `prepare` 等 API 时才可使用。
+* 若当前项目 DB 类仅支持 `query($sql)`，不可硬改成不存在的方法。
+
+---
+
+## III.1 safeFilter / safeValidate 过滤函数规范
+### 1. 命名与目标
+* 过滤函数命名必须以 `safeFilter` 或 `safeValidate` 开头。
+* 目的：
+
+    1. 统一修复风格；
+    2. 便于规则引擎识别清洗点（已存在对应 sanitizer 规则）。
+
+### 2. 使用规则
+1. **必须使用临时变量承接过滤结果**，后续 SQL 只能使用安全变量。
+2. 禁止“过滤后继续使用原变量”。
+3. 非法输入必须返回错误/中断，不允许静默放行。
+4. 对对象参数，优先提供“对象级过滤函数”，返回安全对象后再下传。
+
+### 3. 示例（标量）
+```php
+function safeFilterOrderBy($input) {
+    $regex = '/^[\w\s\[\]"`$.,*]+$/';
+    if (!is_string($input) || !preg_match($regex, $input)) {
+        throw new InvalidArgumentException('Invalid order by');
+    }
+    return $input;
+}
+
+$safeOrderBy = safeFilterOrderBy($orderBy);
+$sql = "SELECT * FROM t ORDER BY {$safeOrderBy}";
+```
+### 4. 示例（对象）
+```php
+function safeValidateQuery($query) {
+    $regex = '/^[\w\s\[\]"`$.,*]+$/';
+    if (isset($query['sort']) && !preg_match($regex, $query['sort'])) {
+        throw new InvalidArgumentException('Invalid sort');
+    }
+    return $query;
+}
+
+$safeQuery = safeValidateQuery($query);
+$sort = $safeQuery['sort'] ?? 'id DESC';
+```
+---
+
+## IV. 原生 PHP / PDO 修复方案（通用）
+### 1. 预编译修复（跨函数/数据流）
+当 SQL 在一个函数构建、另一个函数执行时，可通过默认参数兼容改造。
+
+```php
+// Bad
+function getInfo($id) {
+    $sql = "SELECT * FROM news WHERE id = $id";
+    return fetchAll($sql);
+}
+
+function fetchAll($sql) {
+    global $conn;
+    return $conn->query($sql);
+}
+
+// Fix
+function getInfo($id) {
+    $sql = "SELECT * FROM news WHERE id = ?";
+    return fetchAll($sql, [$id]);
+}
+
+function fetchAll($sql, $params = []) {
+    global $conn;
+    $stmt = $conn->prepare($sql);
+    $stmt->execute($params);
+    return $stmt->fetchAll();
+}
+```
+### 2. IN 子句修复（原生 PDO）
+```php
+$ids = explode(',', $inputIds);
+if (empty($ids)) {
+    return [];
+}
+
+$inQuery = implode(',', array_fill(0, count($ids), '?'));
+$sql = "SELECT * FROM table WHERE id IN ($inQuery)";
+$stmt = $pdo->prepare($sql);
+$stmt->execute($ids);
+$rows = $stmt->fetchAll();
+```
+### 3. IN 子句强约束（必须满足）
+1. 禁止 `IN (:ids)` 直接绑定数组。
+2. 占位符数量必须与参数数量一致。
+3. 空数组必须有兜底逻辑（返回空结果或显式中断）。
+4. 禁止出现参数翻倍、错位绑定。
+
+### 4. PDO 常见错误（必须规避）
+1. `execute()` 返回 bool，不能当 Statement 使用。
+2. `prepare + bindValue` 后必须 `execute()` 再 `fetch/fetchAll`。
+3. 禁止同一 SQL 中混用 `?` 与 `:name`。
+
+---
+
+## V. 必须使用正则过滤的场景
+以下场景不支持预编译，必须使用正则 `^[\w\s\[\]\"\x60$.,*]+$` 过滤：
+
+1. 动态表名/库名：`FROM $tableName`
+2. 动态列名：`SELECT $columnName`
+3. Order By：`ORDER BY $field $direction`
+4. DDL/DCL：`CREATE`, `DROP`, `GRANT`, `SHOW`
+
+**代码复用提示**
+
+* 若文件头/类常量已定义类似正则（如 `SAFE_SQL_PATTERN`），直接复用。
+
+### 补充：操作符/排序方向建议枚举校验（不替换现有正则）
+在保留上述正则前提下，建议叠加枚举校验：
+
+```php
+$direction = strtoupper(trim($direction));
+if (!in_array($direction, ['ASC', 'DESC'], true)) {
+    throw new InvalidArgumentException('Invalid sort direction');
+}
+
+$op = strtoupper(trim($op));
+$validOps = ['=', '!=', '<', '<=', '>', '>=', 'LIKE', 'IN'];
+if (!in_array($op, $validOps, true)) {
+    throw new InvalidArgumentException('Invalid operator');
+}
+```
+---
+
+## VI. 不可修复场景
+遇到以下情况，标记为不可修复，不强行修改：
+
+1. 外部生成整段 SQL（第三方 Jar/Extension/Service），无法拆解参数。
+2. 污点作为复杂动态子句拼入（例如完整 WHERE 逻辑），无法安全结构化。
+
+### 不可修复判定模板（建议）
+* **数据流结论**：指出 taint 来源、传播路径、sink。
+* **不可修复原因**：明确是“外部整段 SQL”还是“复杂子句不可拆解”。
+* **风险说明**：说明为什么强修会破坏业务或产生误修。
+* **建议动作**：补输入侧网关校验、人工评审、上游接口收敛。
+
+---
+
+## VII. 修复后检查点（强检查清单）
+1. 是否优先使用框架安全写法（Yii 数组语法等）。
+2. 是否遗留旧拼接 SQL（避免新旧并存导致覆盖）。
+3. 是否存在 `prepare/bind` 后漏 `execute()`。
+4. 是否误用 `execute()` 返回值。
+5. 占位符数量是否与参数数量一致。
+6. 条件分支中的参数绑定是否一致、变量是否已定义。
+7. 若改动公共函数签名，调用方是否全部兼容。
+8. 修复位置是否与真实数据流文件/函数一致（避免改错位置）。
+9. 是否引入语法错误、死代码或不可达代码。
+10. 正则与枚举校验是否按预期拦截非法输入。
+
+---
+
+## VIII. 高频修复失败反模式（来自 php_review_20260416）
+以下为高频失败原因，修复时必须逐项自检：
+
+1. **调用不存在 API**：如盲目使用 `prepare/queryf/execute($sql,$params)`。
+2. **修错文件或修错函数**：与 SARIF 数据流路径不一致。
+3. **部分修复**：只修一个分支或一部分参数，其他 sink 仍可注入。
+4. **新旧 SQL 并存**：参数化查询后仍保留旧拼接查询。
+5. **变量作用域错误**：分支变量在另一分支未定义即绑定。
+6. **过滤顺序错误**：先拼接 SQL 后过滤/转义。
+7. **仅加引号不转义**：`'$input'` 不是安全修复。
+8. **IN 数组绑定错误**：单占位符绑定数组或空数组未兜底。
+9. **过度依赖“看起来安全”**：未验证框架/DAO 真实能力。
+10. **未做回归检查**：代码改了但未验证是否仍被扫描命中。
+
+---
+
+## IX. 最小修复策略（执行建议）
+为提高修复成功率，可按以下顺序执行：
+
+1. 找到真实 sink 位置，确认是否可参数化。
+2. 可参数化则优先参数化；不可参数化则走正则过滤。
+3. 对结构化参数叠加枚举校验（方向、操作符等）。
+4. 使用 `safeFilter/safeValidate` + 临时变量截断数据流。
+5. 做 VII 节 10 条强检查后再提交。

package/comate-engine/assets/skills/code-security-comate/references/vul_repair-python_sql_injection.md

@@ -0,0 +1,198 @@
+python sqli 漏洞修复知识
+
+# python sqli 漏洞修复最佳实践
+采用先分析漏洞报告 -> 分析数据传递链路 -> 判断依赖与副作用 -> 选择修复方式 -> 修复漏洞 -> 验证语法与调用兼容性的流程。
+
+注意：**不要做与漏洞修复无关的代码改动**。
+
+---
+
+## I. 漏洞分析
+### 1. 不可修复场景
+1. SQL 语句由外部包/外部服务直接生成并传入，当前代码无法拆解 SQL 结构。
+2. 污点以完整子句（如完整 `WHERE` / `ORDER` / `JOIN` 逻辑）注入，且无法安全结构化拆分。
+3. 无法确认修复位置是否在真实数据流 sink 路径上（此时应先回到数据流定位，不盲改）。
+
+### 2. 可修复场景
+1. 仅在当前数据流相关文件内修复，不创建新的代码文件。
+2. 同文件已有过滤函数/正则时优先复用。
+3. 表名、列名、视图名、库名、`order/orderby` 等结构化 SQL 片段必须过滤，过滤正则使用：`"^[\\w\\s\\[\\]\"`$.,*]+$"`。
+4. `show/create/drop/grant` 等场景不支持参数化绑定，必须过滤，过滤正则同上。
+5. `IN` 参数优先参数化：按元素数量展开占位符，不允许单占位符直接绑定数组。
+6. 同一参数只采用一种修复方式，不要叠加“过滤 + 参数化 + 转义”多种方案。
+7. 禁止直接对完整 SQL 做“整体过滤”；应对拼接进 SQL 的污点参数做防护。
+8. 需要改函数签名时，要保证现有调用方兼容（默认参数或同步改调用方）。
+9. 修复前先确认当前 DB API 能力（`execute` 占位符风格、是否支持命名参数等），禁止猜测 API。
+10. 若 SQL 在多个函数复用，修复时需一并分析其他调用点，避免只修一处导致复发。
+
+---
+
+## II. 过滤方式规则（safeFilter / safeValidate）
+### 1. 命名规范
+* 过滤函数命名建议以 `safeFilter` 或 `safeValidate` 开头。
+* 便于规则引擎识别清洗点（仓库已存在对应 sanitizer 规则）。
+
+### 2. 使用规范
+1. 过滤结果必须由临时变量承接，后续拼接 SQL 只能使用过滤后的变量。
+2. 禁止“先赋值污点变量，再覆盖为安全值”的写法。
+3. 非法输入必须抛错/返回错误，不能静默放行。
+4. 对对象参数，建议返回安全对象后再向下传递。
+
+### 3. 标量示例
+```python
+import re
+
+SAFE_SQL_PATTERN = r'^[\w\s\[\]"`$.,*]+$'
+
+
+def safeFilterOrderBy(order_by: str) -> str:
+    if not isinstance(order_by, str) or not re.fullmatch(SAFE_SQL_PATTERN, order_by):
+        raise ValueError("invalid order by")
+    return order_by
+
+
+safe_order = safeFilterOrderBy(request.GET.get("sort", "id DESC"))
+sql = f"SELECT * FROM users ORDER BY {safe_order}"
+cursor.execute(sql)
+```
+### 4. 对象示例
+```python
+import re
+
+SAFE_SQL_PATTERN = r'^[\w\s\[\]"`$.,*]+$'
+
+
+def safeValidateQuery(query: dict) -> dict:
+    safe_query = dict(query)
+    sort_value = safe_query.get("sort")
+    if sort_value is not None and not re.fullmatch(SAFE_SQL_PATTERN, sort_value):
+        raise ValueError("invalid sort")
+    return safe_query
+
+
+safe_query = safeValidateQuery(query)
+sql = f"SELECT * FROM users ORDER BY {safe_query.get('sort', 'id DESC')}"
+cursor.execute(sql)
+```
+---
+
+## III. Python 常见修复方案
+### 1. DB-API 参数化查询（优先）
+```python
+# Bad
+sql = "SELECT * FROM users WHERE username = '" + username + "'"
+cursor.execute(sql)
+
+# Fix（MySQL/PostgreSQL/多数驱动）
+cursor.execute("SELECT * FROM users WHERE username = %s", (username,))
+
+# Fix（sqlite3 常见写法）
+cursor.execute("SELECT * FROM users WHERE username = ?", (username,))
+```
+### 2. IN 子句参数化
+```python
+ids = request.GET.getlist("ids")
+if not ids:
+    return []
+
+placeholders = ",".join(["%s"] * len(ids))
+sql = f"SELECT * FROM users WHERE id IN ({placeholders})"
+cursor.execute(sql, tuple(ids))
+rows = cursor.fetchall()
+```
+### 3. 结构化片段过滤（表名/列名/排序）
+```python
+import re
+
+SAFE_SQL_PATTERN = r'^[\w\s\[\]"`$.,*]+$'
+
+
+def safeFilterIdentifier(value: str) -> str:
+    if not re.fullmatch(SAFE_SQL_PATTERN, value):
+        raise ValueError("invalid identifier")
+    return value
+
+
+sort_col = safeFilterIdentifier(request.GET.get("sort", "id DESC"))
+sql = f"SELECT id, username FROM users ORDER BY {sort_col}"
+cursor.execute(sql)
+```
+### 4. Django 原生 SQL 场景
+```python
+from django.db import connection
+
+username = request.GET.get("username")
+with connection.cursor() as cursor:
+    # Bad: f-string 拼接
+    # cursor.execute(f"SELECT * FROM auth_user WHERE username = '{username}'")
+
+    # Fix: 参数化
+    cursor.execute("SELECT * FROM auth_user WHERE username = %s", [username])
+```
+### 5. SQLAlchemy 场景
+```python
+from sqlalchemy import text
+
+# Bad
+# session.execute(text(f"SELECT * FROM users WHERE name = '{name}'"))
+
+# Fix
+session.execute(text("SELECT * FROM users WHERE name = :name"), {"name": name})
+```
+### 6. pandas `read_sql` 场景
+```python
+import pandas as pd
+
+# Bad
+# sql = f"SELECT * FROM users WHERE name = '{user_input}'"
+# df = pd.read_sql(sql, conn)
+
+# Fix
+sql = "SELECT * FROM users WHERE name = ?"
+df = pd.read_sql(sql, conn, params=[user_input])
+```
+---
+
+## IV. 必须使用正则过滤的场景
+以下场景不支持预编译，必须使用正则 `^[\w\s\[\]"`$.,*]+$` 过滤：
+
+1. 动态表名/库名：`FROM {table_name}`
+2. 动态列名：`SELECT {columns}`
+3. 动态排序：`ORDER BY {order_by}`
+4. DDL/DCL：`CREATE` / `DROP` / `GRANT` / `SHOW`
+
+代码复用提示：若文件中已定义 `SAFE_SQL_PATTERN`，直接复用，不重复定义。
+
+---
+
+## V. 修复后检查点（强检查清单）
+1. 参数值是否全部走参数化，是否遗留字符串拼接。
+2. 结构化 SQL 片段是否全部走过滤。
+3. `IN` 子句占位符数量是否与参数数量一致。
+4. 空数组场景是否有兜底（避免 `IN ()` 语法错误）。
+5. 是否混用了不兼容的占位符风格（`%s` / `?` / `:name`）。
+6. 是否修复了真实 sink 所在函数/文件（不是“改错位置”）。
+7. 改动函数签名后，调用方是否同步兼容。
+8. 是否出现“新旧 SQL 并存”导致旧拼接逻辑覆盖新逻辑。
+9. 是否存在变量作用域问题（分支变量未定义）。
+10. 修复代码是否保持原业务语义（避免把 `UPDATE/DELETE` 改成 `SELECT`）。
+
+---
+
+## VI. 高频失败反模式（修复时必须规避）
+1. 仍使用 `%`/`format`/f-string 拼接 SQL。
+2. `IN` 直接绑定列表到单占位符。
+3. 修复一个分支，遗漏同函数其他分支。
+4. 修复一个 sink，遗漏同参数的其他 sink。
+5. 调用不存在的 DB API 或错误假设驱动能力。
+6. 修复后仍保留旧的拼接 SQL。
+7. 只加引号不做参数化/过滤。
+8. 先使用污点变量，后再“补过滤”（数据流已放行）。
+
+---
+
+## VII. 最小修复策略（执行建议）
+1. 先定位真实数据流 sink，再选修复方式。
+2. 值参数优先参数化；结构化片段用正则过滤。
+3. 使用 `safeFilter/safeValidate` + 临时变量承接。
+4. 完成后按 V 节 10 条逐项自检，再提交。