API Security Skill

API密钥安全实践与防护指南

🚨 安全事件回顾

• 日期: 2026年2月10日
• 事件: 在stock-monitor技能的SKILL.md中发现明文API密钥
• 风险: 如果上传到GitHub，密钥将公开暴露
• 措施: 立即修复，改为安全配置说明

🔒 核心安全原则

绝对禁止

1. ❌ 绝不在代码中硬编码API密钥
2. ❌ 绝不在文档中包含明文密钥
3. ❌ 绝不在版本控制中提交密钥文件
4. ❌ 绝不在日志中输出完整密钥

必须做到

1. ✅ 使用环境变量管理密钥
2. ✅ 使用外部配置文件（.gitignore保护）
3. ✅ 提供安全的配置说明
4. ✅ 实施密钥轮换机制

📝 安全配置模式

模式1：环境变量（推荐）

# 设置环境变量
export ALPHA_VANTAGE_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here
export GITHUB_TOKEN=your_key_here

# 在Python中使用
import os
api_key = os.environ.get('API_KEY')

模式2：外部配置文件

# 创建安全的密钥文件
mkdir -p ~/.secure/keys
echo "your_api_key_here" > ~/.secure/keys/api_key
chmod 600 ~/.secure/keys/api_key  # 仅所有者可读写

# 在Python中读取
with open(os.path.expanduser('~/.secure/keys/api_key'), 'r') as f:
    api_key = f.read().strip()

模式3：.env文件（带.gitignore）

# .env文件（添加到.gitignore）
API_KEY=your_key_here
DATABASE_URL=your_database_url

# .gitignore必须包含
.env
*.key
*.secret
config/secret*.json

🛡️ 安全检查清单

创建新技能时

• [ ] 代码中没有API_KEY = "明文密钥"
• [ ] 文档中没有密钥: ABC123这样的明文
• [ ] .gitignore文件已配置
• [ ] 提供了环境变量配置说明
• [ ] 提供了外部文件配置说明
• [ ] 测试了安全的密钥加载

提交到Git前

# 检查是否包含敏感信息
grep -r "API_KEY\|APIKEY\|PASSWORD\|SECRET" . --include="*.py" --include="*.md" --include="*.json"

# 检查.gitignore是否有效
git status --ignored

# 使用git-secrets等工具扫描

发布前审查

• [ ] 文档示例使用your_api_key_here占位符
• [ ] 所有配置文件路径都是相对的或用户主目录
• [ ] 错误消息不泄露密钥信息
• [ ] 日志中只显示密钥的前/后几位

🚫 常见错误示例

错误1：硬编码密钥

# ❌ 错误示例
API_KEY = "R4MKJRGWX0WLUPX5"  # 明文密钥，绝对禁止！

# ✅ 正确示例
import os
API_KEY = os.environ.get('API_KEY')  # 从环境变量读取

错误2：文档中包含密钥

<!-- ❌ 错误示例 -->
## 配置API密钥
密钥: `R4MKJRGWX0WLUPX5`

<!-- ✅ 正确示例 -->
## 配置API密钥
1. 获取API密钥: https://example.com/api-key
2. 设置环境变量: `export API_KEY=your_key`
3. 或创建密钥文件: `echo "your_key" > ~/.api_key`

错误3：git提交密钥文件

# ❌ 错误：提交了密钥文件
git add config/api_key.txt
git commit -m "Add API config"

# ✅ 正确：.gitignore保护
echo "config/api_key.txt" >> .gitignore
git add .gitignore

🛠️ 安全工具

1. git-secrets

# 安装
git secrets --install

# 添加模式
git secrets --add 'API_KEY.*=.*["\'].*["\']'
git secrets --add --allowed 'API_KEY.*=.*your_key_here'

# 扫描
git secrets --scan

2. truffleHog / gitleaks

# 扫描提交历史中的密钥
gitleaks detect --source . -v

# 配置排除规则
echo '[[rules]]
description = "Allow placeholder API keys"
regex = '''API_KEY.*=.*["']your_.*["']''' > .gitleaks.toml

3. pre-commit钩子

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.0
    hooks:
      - id: gitleaks

📋 技能模板

安全技能结构

skill-name/
├── SKILL.md          # 文档（无明文密钥）
├── __init__.py       # 主模块
├── config.py         # 配置加载
├── security_check.py # 安全检查
└── .gitignore        # 忽略敏感文件

config.py示例

import os
from pathlib import Path

def load_api_key(key_name, default_path=None):
    """安全加载API密钥"""
    # 1. 检查环境变量
    key = os.environ.get(key_name)
    if key:
        return key
    
    # 2. 检查密钥文件
    key_files = [
        Path.home() / f'.openclaw/{key_name.lower()}',
        Path.home() / f'.{key_name.lower()}',
        default_path
    ]
    
    for key_file in key_files:
        if key_file and key_file.exists():
            try:
                with open(key_file, 'r') as f:
                    return f.read().strip()
            except:
                continue
    
    raise ValueError(f"未找到{key_name}，请设置环境变量或创建密钥文件")

🚀 实施步骤

1. 新技能开发

# 创建技能结构
mkdir -p new-skill && cd new-skill

# 立即创建.gitignore
echo ".env\n*.key\n*.secret\nconfig/secret*" > .gitignore

# 使用安全模板
cp ../api-security/templates/config.py .

2. 现有技能修复

# 检查现有技能
cd existing-skill

# 扫描敏感信息
python -c "
import re
import os

patterns = [
    r'API_?KEY\s*[=:]\s*[\"\']\w+[\"\']',
    r'password\s*[=:]\s*[\"\']\w+[\"\']',
    r'secret\s*[=:]\s*[\"\']\w+[\"\']'
]

for root, dirs, files in os.walk('.'):
    for file in files:
        if file.endswith(('.py', '.md', '.json', '.yml', '.yaml')):
            path = os.path.join(root, file)
            with open(path, 'r', encoding='utf-8', errors='ignore') as f:
                content = f.read()
                for pattern in patterns:
                    if re.search(pattern, content, re.IGNORECASE):
                        print(f'警告: {path} 可能包含敏感信息')
"

# 修复发现问题

3. 文档更新

<!-- 更新SKILL.md的安全部分 -->
## 🔐 安全配置

请按以下方式安全配置API密钥：

### 选项A：环境变量（推荐）
```bash
export YOUR_API_KEY=your_actual_key_here

选项B：密钥文件

echo "your_actual_key_here" > ~/.your_api_key
chmod 600 ~/.your_api_key

重要：请勿在代码或文档中使用明文密钥！

## 📚 相关资源

### 最佳实践文档
- [OWASP API Security Top 10](https://owasp.org/www-project-api-security/)
- [GitHub Secrets Scanning](https://docs.github.com/en/code-security/secret-scanning)
- [12 Factor App Config](https://12factor.net/config)

### 监控与警报
```python
# 密钥使用监控
import logging

class SecureAPIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        # 记录密钥使用（不记录完整密钥）
        logging.info(f"API客户端初始化，密钥: {api_key[:4]}...{api_key[-4:]}")
    
    def make_request(self):
        # 使用密钥
        pass

⚠️ 紧急响应

发现密钥泄露

1. 立即轮换密钥 - 在服务提供商处重置
2. 审查提交历史 - 确认泄露范围
3. 撤销访问权限 - 如果可能
4. 监控异常活动 - 关注API使用情况
5. 更新文档 - 移除所有明文密钥

预防措施

1. 定期密钥轮换 - 每90天更换一次
2. 最小权限原则 - 只授予必要权限
3. 使用密钥别名 - 便于管理和撤销
4. 启用审计日志 - 记录所有API调用

创建日期: 2026年2月10日
最后更新: 2026年2月10日
重要性: 关键安全实践
适用范围: 所有涉及API密钥的技能
状态: 生效中 ✅