概述

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

支持的版本

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

注意：作为一个教育指南项目，我们更关注维护当前最佳实践和文档安全，而不是传统意义上的版本支持。更新会直接应用到 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. 访问：YOUR_REPO
2. 点击 “Report a vulnerability”
3. 填写漏洞细节
4. 请包含：
   • 漏洞的清晰描述
   • 受影响的组件（文件、章节、示例）
   • 潜在影响
   • 复现步骤（如适用）
   • 建议修复方式（如果你有）

接下来会发生什么：

• 我们会在 48 小时内确认收到
• 我们会调查并评估严重性
• 我们会与你一起修复
• 我们会协调披露时间线
• 如你愿意，我们会在安全公告中致谢

公开报告

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

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

漏洞响应流程

评估（24 小时内）

1. 我们确认收到报告
2. 我们使用 CVSS v3.1 评估严重性
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：关键文件有指定审查者
• 签名提交：建议贡献者使用

开发安全

# 安装 pre-commit hooks
pre-commit install

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

依赖安全

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

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

贡献者安全指南

编写示例时

1. 永远不要硬编码密钥

   # ❌ 不好
   api_key = "sk-1234567890"
   
   # ✅ 更好
   api_key = os.getenv("API_KEY")
   

2. 提醒安全影响

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

3. 使用安全默认值

   • 默认启用认证
   • 在适用场景中使用 HTTPS
   • 校验并清理输入
   • 使用参数化查询

4. 记录安全注意事项

   • 解释为什么安全很重要
   • 展示安全与不安全的写法
   • 链接权威来源
   • 明显展示警告

审查贡献时

1. 检查是否泄露秘密

   • 扫描常见模式（api_key=、password= 等）
   • 审查配置文件
   • 检查环境变量使用情况

2. 验证安全编码实践

   • 没有硬编码凭据
   • 正确的输入验证
   • 安全的认证/授权
   • 安全的文件处理

3. 测试安全影响

   • 这会不会被滥用？
   • 最坏情况是什么？
   • 有没有边界情况？

安全资源

官方标准

• OWASP Top 10
• CWE Top 25
• CVSS Calculator

Python 安全

• Python Security Advisories
• PyPI Security
• Bandit Documentation

依赖管理

• OWASP Dependency Check
• GitHub Security Alerts

通用安全

• Anthropic Security
• GitHub Security Best Practices

安全公告存档

过往安全公告可在 GitHub 的 Security Advisories 标签页查看。

联系方式

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

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

致谢

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

政策更新

本安全政策会在以下情况更新：

• 发现新漏洞时
• 安全最佳实践演进时
• 项目范围发生变化时
• 至少每年一次

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

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