claude-howto/zh/SECURITY.md

# 安全政策

## 概述

Claude How To 项目的安全对我们非常重要。本文档说明我们的安全实践，以及如何负责任地报告安全漏洞。

## 支持的版本

我们为以下版本提供安全更新：

| 版本 | 状态 | 支持至 |
|---------|--------|---------------|
| 最新版（main） | ✅ 活跃 | 当前版本 + 6 个月 |
| 1.x 发布版 | ✅ 活跃 | 直到下一个大版本 |

**注意**：作为一个教育指南项目，我们更关注维护当前最佳实践和文档安全，而不是传统意义上的版本支持。更新会直接应用到 main 分支。

## 安全实践

### 代码安全

1. **依赖管理**
   - 所有 Python 依赖都固定在 `requirements.txt` 中
   - 通过 dependabot 和人工审查进行定期更新
   - 每次提交都会运行 Bandit 安全扫描
   - 使用 pre-commit hooks 做安全检查

2. **代码质量**
   - 使用 Ruff 做 lint，能捕获常见问题
   - 使用 mypy 做类型检查，避免类型相关漏洞
   - 通过 pre-commit hooks 强制执行标准
   - 所有更改在合并前都要审查

3. **访问控制**
   - 对 `main` 分支启用分支保护
   - 合并前需要审查通过
   - 状态检查必须通过后才能合并
   - 仓库写权限受限

### 文档安全

1. **示例中不放密钥**
   - 所有示例中的 API key 都使用占位符
   - 从不硬编码凭据
   - `.env.example` 文件会展示所需变量
   - 明确提示密钥管理风险

2. **安全最佳实践**
   - 示例会展示安全模式
   - 文档中会突出安全警告
   - 链接到官方安全指南
   - 在相关章节中说明凭据处理方式

3. **内容审查**
   - 所有文档都会审查安全问题
   - 贡献指南中包含安全注意事项
   - 会验证外部链接和引用

### 依赖安全

1. **扫描**
   - Bandit 会扫描所有 Python 代码中的漏洞
   - 通过 GitHub 安全警报检查依赖漏洞
   - 定期进行人工安全审计

2. **更新**
   - 安全补丁会尽快应用
   - 大版本会谨慎评估
   - 更新日志会包含安全相关变更

3. **透明度**
   - 安全更新会记录在提交中
   - 漏洞披露会负责任地处理
   - 在适当情况下发布公开安全公告

## 漏洞报告

### 我们关注的安全问题

我们欢迎以下报告：
- **代码漏洞**：脚本或示例中的漏洞
- **依赖漏洞**：Python 包中的漏洞
- **加密问题**：任何代码示例中的密码学问题
- **认证/授权缺陷**：文档中的认证或授权问题
- **数据暴露风险**：配置示例中的数据泄露风险
- **注入漏洞**：SQL、命令等注入
- **SSRF / XXE / 路径穿越** 问题

### 不在范围内的安全问题

以下问题不在本项目范围内：
- Claude Code 本身的漏洞（请向 Anthropic 报告）
- 外部服务或库的问题（请向上游项目报告）
- 社会工程学或用户教育问题（与本指南无关）
- 没有 PoC 的理论漏洞
- 依赖库中已通过官方渠道报告的漏洞

## 如何报告

### 私密报告（推荐）

**如遇敏感安全问题，请使用 GitHub 的私密漏洞报告：**

1. 访问：<https://github.com/luongnv89/claude-howto/security/advisories>
2. 点击 “Report a vulnerability”
3. 填写漏洞细节
4. 请包含：
   - 漏洞的清晰描述
   - 受影响的组件（文件、章节、示例）
   - 潜在影响
   - 复现步骤（如适用）
   - 建议修复方式（如果你有）

**接下来会发生什么：**
- 我们会在 48 小时内确认收到
- 我们会调查并评估严重性
- 我们会与你一起修复
- 我们会协调披露时间线
- 如你愿意，我们会在安全公告中致谢

### 公开报告

对于不敏感或已公开的问题：

1. **创建 GitHub Issue** 并打上 `security` 标签
2. 包含：
   - 标题：以 `[SECURITY]` 开头并附简短说明
   - 详细描述
   - 受影响的文件或章节
   - 潜在影响
   - 建议修复方式

## 漏洞响应流程

### 评估（24 小时内）

1. 我们确认收到报告
2. 我们使用 [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) 评估严重性
3. 我们判断是否在范围内
4. 我们向你反馈初步评估

### 开发（1-7 天）

1. 我们开发修复
2. 我们审查并测试修复
3. 我们创建安全公告
4. 我们准备发布说明

### 披露（取决于严重性）

**严重（CVSS 9.0-10.0）**
- 立即发布修复
- 发布公开公告
- 提前 24 小时通知报告者

**高危（CVSS 7.0-8.9）**
- 48-72 小时内发布修复
- 提前 5 天通知报告者
- 发布时公开公告

**中危（CVSS 4.0-6.9）**
- 在下一次常规更新中修复
- 发布时公开公告

**低危（CVSS 0.1-3.9）**
- 在下一次常规更新中修复
- 发布时附带公告

### 公布

我们发布的安全公告会包含：
- 漏洞描述
- 受影响组件
- 严重性评估（CVSS 分数）
- 修复版本
- 临时缓解方案（如适用）
- 对报告者的致谢（如获许可）

## 报告者最佳实践

### 报告前

- **确认问题**：你能稳定复现吗？
- **搜索已有 issue**：是否已经有人报告？
- **查看文档**：是否已有安全使用说明？
- **测试修复**：你建议的修复是否有效？

### 报告时

- **尽量具体**：提供准确的文件路径和行号
- **补充上下文**：为什么这是安全问题？
- **说明影响**：攻击者可能做什么？
- **提供步骤**：如何复现？
- **提出修复建议**：你会怎么修？

### 报告后

- **保持耐心**：我们的资源有限
- **积极响应**：尽快回答后续问题
- **保持保密**：在修复前不要公开披露
- **尊重协调流程**：按时间线推进披露

## 安全头与配置

### 仓库安全

- **分支保护**：主分支需要 2 份批准
- **状态检查**：所有 CI/CD 检查必须通过
- **CODEOWNERS**：关键文件有指定审查者
- **签名提交**：建议贡献者使用

### 开发安全

```bash
# 安装 pre-commit hooks
pre-commit install

# 本地运行安全扫描
bandit -c pyproject.toml -r scripts/
mypy scripts/ --ignore-missing-imports
ruff check scripts/
```

### 依赖安全

```bash
# 检查已知漏洞
pip install safety
safety check

# 或使用 pip-audit
pip install pip-audit
pip-audit
```

## 贡献者安全指南

### 编写示例时

1. **永远不要硬编码密钥**
   ```python
   # ❌ 不好
   api_key = "sk-1234567890"

   # ✅ 更好
   api_key = os.getenv("API_KEY")
   ```

2. **提醒安全影响**
   ```markdown
   ⚠️ **安全提示**：切勿把 `.env` 文件提交到 git。
   请立即加入 `.gitignore`。
   ```

3. **使用安全默认值**
   - 默认启用认证
   - 在适用场景中使用 HTTPS
   - 校验并清理输入
   - 使用参数化查询

4. **记录安全注意事项**
   - 解释为什么安全很重要
   - 展示安全与不安全的写法
   - 链接权威来源
   - 明显展示警告

### 审查贡献时

1. **检查是否泄露秘密**
   - 扫描常见模式（api_key=、password= 等）
   - 审查配置文件
   - 检查环境变量使用情况

2. **验证安全编码实践**
   - 没有硬编码凭据
   - 正确的输入验证
   - 安全的认证/授权
   - 安全的文件处理

3. **测试安全影响**
   - 这会不会被滥用？
   - 最坏情况是什么？
   - 有没有边界情况？

## 安全资源

### 官方标准
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [CWE Top 25](https://cwe.mitre.org/top25/)
- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1)

### Python 安全
- [Python Security Advisories](https://www.python.org/dev/security/)
- [PyPI Security](https://pypi.org/help/#security)
- [Bandit Documentation](https://bandit.readthedocs.io/)

### 依赖管理
- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/)
- [GitHub Security Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)

### 通用安全
- [Anthropic Security](https://www.anthropic.com/)
- [GitHub Security Best Practices](https://docs.github.com/en/code-security)

## 安全公告存档

过往安全公告可在 GitHub 的 [Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories) 标签页查看。

## 联系方式

如需咨询安全相关问题或讨论安全实践：

1. **私密安全报告**：使用 GitHub 的私密漏洞报告
2. **一般安全问题**：使用 `[SECURITY]` 标签发起 discussion
3. **安全政策反馈**：创建带 `security` 标签的 issue

## 致谢

感谢帮助本项目保持安全的安全研究者和社区成员。负责任地报告漏洞的贡献者会在我们的安全公告中获得致谢（除非你希望匿名）。

## 政策更新

本安全政策会在以下情况更新：
- 发现新漏洞时
- 安全最佳实践演进时
- 项目范围发生变化时
- 至少每年一次

**最后更新**：2026 年 1 月
**下次审查**：2027 年 1 月

---

感谢你帮助 Claude How To 保持安全！🔒