SQLBot/docs/agents/security.md

安全 Agent 说明

原则

• LLM 输出、SQL、文件名、路径、Host 头、路由参数、第三方回传数据和前端消息都不是可信输入。
• 新接口默认拒绝；先认证、再授权、再校验资源归属，最后执行业务。
• 发现现有绕过路径时优先收敛授权语义，不要只在单个 URL 上打补丁。
• 涉及以下任何区域，必须补充或更新回归测试，并运行 backend/tests/ 中的相关守卫。

API 权限

• 使用 CurrentUser / SessionDep 获取身份和会话，不信任请求体中的用户或工作空间 ID。
• 资源型接口使用 @require_permissions(...)，并确认：
  • type 指向正确资源；
  • keyExpression 能取到真实资源 ID；
  • 列表语义不会被单个资源绕过；
  • 管理员、工作空间管理员和普通用户路径都明确。
• 权限表达式引用的参数缺失、解析失败或归属不匹配时必须拒绝，不能回退为直接执行处理函数。
• 子资源归属从服务端记录推导并校验完整关系（如字段 → 表 → 数据源 → 工作空间）；请求中的 ds_id、oid 仅为待校验输入。不能仅验证调用者有权访问所提供的数据源，再按任意表/字段 ID 执行操作。
• 批量接口明确整批拒绝还是仅操作有权记录，并测试混合归属输入；单项、批量、同步、导出等入口应遵循相同授权边界。
• 手写查询归属时，同时校验：
  • 资源存在；
  • 资源属于当前工作空间；
  • 资源属于当前用户或其授权范围；
  • 助手上下文没有切换到其他工作空间。
• oid 和 workspace_id 都表示工作空间 ID；不要把两者当成不同授权域。
• 高级助手动态数据源只允许既有动态类型走动态数据源例外；本地 CoreDatasource 仍必须校验工作空间归属。

SQL 生成与执行

修改主流程时应满足以下安全顺序；需在实际入口和调用链验证，不能把本清单当作现状已安全的证明：

1. 只把允许的表和字段元数据提供给模型；
2. 解析模型返回 JSON 并提取 SQL；
3. 用 sqlglot 提取真实表名并排除 CTE 别名；
4. 对照允许表集合拒绝未授权表；
5. 按用户、助手和页面嵌入场景应用行权限或动态 SQL 变换；
6. 校验并保存最终 SQL；
7. 执行最终 SQL 并保存结果。

额外要求：

• 不要信任模型返回的 tables 字段替代真实 SQL 解析。
• 行权限拼接沿用白名单逻辑运算符和 _escape_sql_value，不要引入新的字符串拼接入口。
• 保持 SQL 行数限制和 SQLBOT_ALLOW_METADATA_QUERIES 默认关闭语义；不要为了调试全局开启元数据查询。
• 动态 SQL 生成后仍必须走同一解析、校验和保存路径。
• 数据源连接配置解密只发生在服务端执行路径，不进入日志或 API 响应。

认证、Host 与嵌入

• 修改 backend/main.py 的中间件顺序时，验证实际请求执行顺序（不能只看注册顺序）；HostValidationMiddleware 必须在认证/业务使用 Host 前拒绝非法值，并回归预检与正常请求。
• Host 只允许合法域名 / IPv4 / IPv6 形态，不能包含 /、@ 或空白。
• 认证和助手 token 头由后端中间件与前端 request interceptor 处理；不要新增手工传递或复制 token 的路径。
• 页面嵌入协议必须保持：
  • 仅 AssistantModel.type == 4 可用 embedded 协议；
  • 先提取目标助手，再用 app_secret 验证签名；
  • 管理员账号拒绝通过 embedded token 使用；
  • 账号状态和工作空间归属仍需校验。
• 修改助手 domain、app_id、app_secret 或类型时，同时考虑目标系统信任边界和跨工作空间访问。
• 前端 postMessage 证书流程不要降级为无请求绑定、无来源约束或永久有效证书。

文件与路径

• 不信任上传文件名、扩展名、MIME、sheet 名或用户提供的 filePath。
• 上传必须限制类型和大小，落盘使用服务端生成的文件名或 opaque ID。
• 读取用户可控路径前，解析真实路径后用 os.path.commonpath 等验证其仍位于允许目录内，或通过已授权的内部 ID 映射路径；不使用字符串前缀判断。校验到打开之间不得允许不可信方替换路径或符号链接。
• 下载前先校验权限和服务端文件实际路径的目录归属，包括符号链接解析；os.path.basename 只适合清理下载展示名，FileResponse 只负责传输，两者都不能替代路径授权。响应不回显内部绝对路径。
• Excel/CSV 解析错误不能变成可猜测的内部路径信息。

前端渲染

• 不直接在组件中调用 axios，避免绕开认证、语言、助手证书和错误处理。
• Markdown 渲染保持 html: false，代码高亮必须转义。
• 新增富文本 / HTML 渲染必须走既有安全工具和组件；不要添加未净化 v-html。
• 链接、图片和远程脚本必须限制协议和来源，不允许 javascript: 或用户控制的服务端地址。
• xpack 静态脚本保留缓存穿透参数和失败处理；不要把商业脚本或密钥复制进前端源码。

日志与敏感信息

• 不记录 token、密码、API key、数据源明文连接串、SQL 凭据、助手 secret 或完整敏感配置。
• 异常响应面向用户时使用后端 i18n 错误；内部 traceback 只进入受控日志。
• 安全测试样本可以包含攻击载荷，但不得包含真实可用凭据或内部地址。

必测场景

按本次涉及的入口选择相关场景；不要求每次安全改动执行下列全部类别，但必须说明未覆盖的相关风险：

• 未登录、无权限、资源不存在、跨工作空间访问；
• 管理员、工作空间管理员、普通用户、助手用户；
• Host 头携带路径、@、空白等污染形态；
• SQL 引用未授权表、CTE 别名、动态 SQL 和行权限边界；
• embedded token 错误助手类型、错误签名、管理员账号和无效账号；
• 上传路径穿越、非法扩展、超限大小和重复扩展名；
• 前端错误传播和未净化内容渲染。