# 安全

> 了解 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)。

## Gateway 网络安全

当通过 `--serve` 模式或 Daemon 启动 HTTP 服务时，CodeBuddy Code 采用多层防御保护 API 端点：

### CORS 白名单

仅允许来自合法源的跨域请求。非法 Origin 的请求（无论 OPTIONS 预检还是实际请求）均被直接拒绝，不执行任何业务逻辑。支持精确 origin（`https://example.com`）、子域通配（`https://*.example.com`）和全部允许（`*`）三种配置模式。通过环境变量 `CODEBUDDY_CODE_CORS_ORIGINS` 或 Settings `gateway.corsOrigins` 配置。

### 自定义请求头校验

所有 API 请求必须携带 `X-CodeBuddy-Request: 1` 头。此机制利用浏览器安全策略：自定义头会强制触发 CORS preflight，且 `no-cors` 模式下浏览器不允许发送自定义头，从而阻止跨站请求伪造。

可通过 `CODEBUDDY_DISABLE_REQUEST_VALIDATION=1` 关闭。详见 [HTTP API 安全](http-api.md#安全)。

### 认证保护

敏感端点（包括 `/info`、`/health`）在启用密码认证时需要 Bearer Token。详见 [HTTP API 认证](http-api.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 的安全使用*
