@tencent-ai/codebuddy-code 2.67.0 → 2.68.0

package/dist/web-ui/docs/cn/cli/security.md

@@ -0,0 +1,387 @@
+# 安全
+
+> 了解 CodeBuddy Code 的安全防护措施和安全使用最佳实践。
+
+## 安全方法
+
+### 安全基础
+
+您的代码安全至关重要。CodeBuddy Code 将安全作为核心构建，遵循腾讯的全面安全计划开发。
+
+### 基于权限的架构
+
+CodeBuddy Code 默认使用严格的只读权限。当需要额外操作（编辑文件、运行测试、执行命令）时，CodeBuddy Code 会请求明确的权限。用户可以控制是一次性批准操作还是自动允许。
+
+我们将 CodeBuddy Code 设计得透明且安全。例如，我们在执行 bash 命令之前需要批准，让您拥有直接控制权。这种方法使用户和组织能够直接配置权限。
+
+有关详细的权限配置，请参阅[身份和访问管理](iam.md)。
+
+### 内置保护
+
+为了降低智能代理系统中的风险：
+
+* **沙箱化 bash 工具**: [Bash 沙箱](bash-sandboxing.md)隔离 bash 命令的文件系统和网络访问，减少权限提示的同时保持安全性。使用 `/sandbox` 启用以定义 CodeBuddy Code 可以自主工作的边界
+* **写入访问限制**: CodeBuddy Code 只能写入其启动的文件夹及其子文件夹——没有明确权限不能修改父目录中的文件。虽然 CodeBuddy Code 可以读取工作目录外的文件（对访问系统库和依赖项很有用）,但写入操作严格限制在项目范围内，创建了清晰的安全边界
+* **提示疲劳缓解**：支持按用户、按代码库或按组织将频繁使用的安全命令加入白名单
+* **接受编辑模式**：批量接受多个编辑，同时保持对具有副作用的命令的权限提示
+
+### 用户责任
+
+CodeBuddy Code 只拥有您授予它的权限。您有责任在批准之前审查建议的代码和命令的安全性。
+
+## 防范提示注入
+
+提示注入是一种攻击技术，攻击者试图通过插入恶意文本来覆盖或操纵 AI 助手的指令。CodeBuddy Code 包含多种针对这些攻击的防护措施：
+
+### 核心保护
+
+* **权限系统**：敏感操作需要明确批准
+* **上下文感知分析**：通过分析完整请求检测潜在有害指令
+* **输入清理**：通过处理用户输入防止命令注入
+* **命令阻止列表**：默认阻止从网络获取任意内容的风险命令，如 `curl` 和 `wget`。当明确允许时，请注意[权限模式限制](iam.md#工具特定的权限规则）
+
+### 隐私保护
+
+我们实施了多项保护措施来保护您的数据，包括：
+
+* 敏感信息的有限保留期
+* 限制访问用户会话数据
+
+有关完整详情,请查看我们的[服务条款](https://cloud.tencent.com/document/product/301/106125)和[隐私政策](https://privacy.qq.com/document/preview/284d799a07164d09bfc7cedd0ec3e089)。
+
+### 额外保护措施
+
+* **网络请求批准**：发出网络请求的工具默认需要用户批准
+* **隔离的上下文窗口**: Web 获取使用单独的上下文窗口，以避免注入潜在的恶意提示
+* **信任验证**：首次运行代码库和新的 MCP 服务器需要信任验证
+  * 注意： 使用 `-p` 标志非交互式运行时，信任验证被禁用
+* **命令注入检测**：可疑的 bash 命令即使之前已加入白名单也需要手动批准
+* **失败关闭匹配**：不匹配的命令默认需要手动批准
+* **自然语言描述**：复杂的 bash 命令包含解释以便用户理解
+* **安全凭据存储**: API 密钥和令牌经过加密。参见[凭据管理](iam.md#凭据管理）
+
+<Warning>
+  **Windows WebDAV 安全风险**: 在 Windows 上运行 CodeBuddy Code 时,我们建议不要启用 WebDAV 或允许 CodeBuddy Code 访问可能包含 WebDAV 子目录的路径,如 `\\*`。[WebDAV 已被 Microsoft 弃用](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20\(WebDAV\)%20service%20is%20deprecated)由于安全风险。启用 WebDAV 可能允许 CodeBuddy Code 触发对远程主机的网络请求,绕过权限系统。
+</Warning>
+
+**处理不受信任内容的最佳实践**:
+
+1. 批准前审查建议的命令
+2. 避免将不受信任的内容直接传输到 CodeBuddy
+3. 验证对关键文件的建议更改
+4. 使用虚拟机(VM)运行脚本和进行工具调用，特别是在与外部 Web 服务交互时
+
+<Warning>
+  虽然这些保护措施显著降低了风险，但没有系统能完全免疫所有攻击。在使用任何 AI 工具时，始终保持良好的安全实践。
+</Warning>
+
+## MCP 安全
+
+CodeBuddy Code 允许用户配置模型上下文协议(MCP)服务器。允许的 MCP 服务器列表在源代码中配置，作为工程师检入源代码控制的 CodeBuddy Code 设置的一部分。
+
+我们鼓励编写您自己的 MCP 服务器或使用您信任的提供商的 MCP 服务器。您可以为 MCP 服务器配置 CodeBuddy Code 权限。CodeBuddy 不管理或审计任何 MCP 服务器。
+
+详见 [MCP 集成文档](mcp.md)。
+
+## 沙箱安全
+
+CodeBuddy Code 支持 Bash 沙箱功能，将 bash 命令与您的文件系统和网络隔离：
+
+### 沙箱隔离级别
+
+* **文件系统隔离**：通过 Read/Edit 权限控制文件访问
+* **网络隔离**：通过 WebFetch 权限控制网络访问
+* **命令隔离**：某些命令可以配置为在沙箱外运行
+
+### 沙箱配置
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "autoAllowBashIfSandboxed": true,
+    "excludedCommands": ["git", "docker"],
+    "network": {
+      "allowUnixSockets": ["/var/run/docker.sock"],
+      "allowLocalBinding": true
+    }
+  }
+}
+```
+
+### 沙箱限制
+
+* **平台支持**：目前仅支持 macOS 和 Linux
+* **性能影响**：沙箱化可能略微影响命令执行性能
+* **兼容性**：某些工具可能在沙箱中无法正常工作
+
+详见[Bash 沙箱文档](bash-sandboxing.md)了解完整配置选项。
+
+## 安全最佳实践
+
+### 处理敏感代码
+
+* 批准前审查所有建议的更改
+* 为敏感仓库使用项目特定的权限设置
+* 定期使用 `/permissions` 审计您的权限设置
+* 使用沙箱功能提供额外隔离
+
+### 团队安全
+
+* 通过版本控制共享批准的权限配置
+* 培训团队成员安全最佳实践
+* 定期审查和更新权限策略
+* 使用项目级设置强制执行团队标准
+
+### 权限配置最佳实践
+
+**1. 最小权限原则**
+
+仅授予完成任务所需的最小权限：
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit(src/**/*.ts)",
+      "Bash(npm:test,npm:build)"
+    ],
+    "deny": [
+      "Edit(**/*.env)",
+      "Bash(rm:*)",
+      "Bash(sudo:*)"
+    ]
+  }
+}
+```
+
+**2. 保护敏感文件**
+
+始终拒绝访问包含敏感信息的文件：
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(secrets/**)",
+      "Read(~/.ssh/**)",
+      "Read(~/.aws/**)",
+      "Edit(**/*.key)",
+      "Edit(**/*.pem)"
+    ]
+  }
+}
+```
+
+**3. 审慎使用 WebFetch**
+
+默认情况下拒绝或询问网络请求：
+
+```json
+{
+  "permissions": {
+    "ask": [
+      "WebFetch"
+    ],
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:npmjs.com)"
+    ]
+  }
+}
+```
+
+**4. 限制危险命令**
+
+明确拒绝可能造成破坏的命令：
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(rm:*)",
+      "Bash(sudo:*)",
+      "Bash(chmod:*)",
+      "Bash(chown:*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)"
+    ]
+  }
+}
+```
+
+### 环境隔离
+
+**1. 使用独立的开发环境**
+
+为不同的安全级别使用不同的环境：
+
+```bash
+# 生产代码 - 严格权限
+cd ~/production/app
+codebuddy --permission-mode default
+
+# 实验项目 - 宽松权限
+cd ~/experiments/test
+codebuddy --permission-mode acceptEdits
+```
+
+**2. 容器化开发**
+
+使用 Docker 容器提供额外的安全边界：
+
+```bash
+# 在容器中运行
+docker run -it --rm -v $(pwd):/workspace codebuddy
+```
+
+### 代码审查流程
+
+**1. 自动化审查前置**
+
+在提交前审查 CodeBuddy 的更改：
+
+```bash
+# 查看所有更改
+git diff
+
+# 审查特定文件
+git diff src/critical.ts
+```
+
+**2. 使用钩子验证**
+
+配置 pre-commit hooks 验证更改：
+
+```json
+{
+  "hooks": {
+    "PreToolUse": {
+      "Edit": "npm run lint-staged"
+    }
+  }
+}
+```
+
+**3. 团队代码审查**
+
+重要更改需要团队成员审查：
+
+```bash
+# 创建 PR 而不是直接提交
+git checkout -b feature/codebuddy-changes
+git push origin feature/codebuddy-changes
+```
+
+### 敏感数据保护
+
+**1. 使用环境变量**
+
+不要在代码中硬编码敏感信息：
+
+```bash
+# 错误示例
+export API_KEY="sk-1234567890"
+
+# 正确示例 - 使用环境变量管理工具
+export $(cat .env.local | xargs)
+```
+
+**2. 配置文件加密**
+
+对敏感配置文件进行加密：
+
+```bash
+# 使用 git-crypt
+git-crypt init
+echo "secrets.json filter=git-crypt diff=git-crypt" >> .gitattributes
+```
+
+**3. 定期轮换凭据**
+
+定期更换 API 密钥和访问令牌：
+
+```bash
+# 使用 apiKeyHelper 动态获取密钥
+{
+  "apiKeyHelper": "/usr/local/bin/get-rotating-key.sh"
+}
+```
+
+### 审计和监控
+
+**1. 记录权限请求**
+
+跟踪 CodeBuddy 的权限请求：
+
+```json
+{
+  "hooks": {
+    "PreToolUse": {
+      "*": "echo \"[$(date)] Tool: $TOOL_NAME\" >> ~/.codebuddy/audit.log"
+    }
+  }
+}
+```
+
+**2. 定期审查日志**
+
+检查审计日志以发现异常：
+
+```bash
+# 查看最近的工具使用
+tail -f ~/.codebuddy/audit.log
+
+# 搜索敏感操作
+grep "Edit.*\.env" ~/.codebuddy/audit.log
+```
+
+**3. 权限配置审计**
+
+定期审查权限配置：
+
+```bash
+# 查看当前权限
+codebuddy config get permissions
+
+# 列出所有设置文件
+find . -name "settings.json" -o -name "settings.local.json"
+```
+
+## 报告安全问题
+
+如果您发现 CodeBuddy Code 中的安全漏洞：
+
+1. 不要公开披露
+2. 通过 [联系我们](https://cloud.tencent.com/document/product/1749/104249) 报告
+3. 包含详细的重现步骤
+4. 在我们解决问题之前允许时间，然后再公开披露
+
+## 安全检查清单
+
+在使用 CodeBuddy Code 之前，请确保：
+
+- [ ] 已审查并配置适当的权限设置
+- [ ] 敏感文件已添加到 deny 列表
+- [ ] 危险命令已被阻止或需要确认
+- [ ] 沙箱功能已根据需要启用
+- [ ] API 密钥和令牌安全存储
+- [ ] 团队成员已接受安全培训
+- [ ] 已建立代码审查流程
+- [ ] 定期审计权限使用情况
+- [ ] 了解如何报告安全问题
+
+## 相关资源
+
+* [身份和访问管理](iam.md) - 配置权限和访问控制
+* [Bash 沙箱](bash-sandboxing.md) - bash 命令的文件系统和网络隔离
+* [MCP 集成](mcp.md) - 配置 MCP 服务器权限
+* [Hooks 文档](hooks.md) - 使用 hooks 进行自定义安全验证
+* [设置配置](settings.md) - 完整的配置选项
+
+---
+
+*通过适当的安全配置和最佳实践，确保 CodeBuddy Code 的安全使用*