本文档描述太一元系统的安全最佳实践和配置指南。
✅ 推荐做法:
# 在 ~/.bashrc 或 ~/.zshrc 中设置
export ZOTERO_API_KEY="your-key-here"
export BRIGHTDATA_API_TOKEN="your-token-here"
export TIKHUB_API_TOKEN="your-token-here"
export ANTHROPIC_AUTH_TOKEN="your-token-here"❌ 避免做法:
- 不要在代码中硬编码 API 密钥
- 不要将包含密钥的配置文件提交到 Git
- 不要在日志中记录完整的 API 密钥
在使用 MCP 服务器前,验证必需的环境变量:
# 检查环境变量是否设置
if [ -z "$ZOTERO_API_KEY" ]; then
echo "错误: ZOTERO_API_KEY 未设置"
exit 1
fi原则: 日志中不应包含:
- API 密钥和令牌
- 用户密码
- 个人身份信息 (PII)
- 完整的文件路径(可能泄露用户名)
实现:
# 过滤敏感信息
log_safe() {
local message="$1"
# 移除可能的 API 密钥模式
message=$(echo "$message" | sed 's/\(api[_-]key\|token\)=[^ ]*/\1=***REDACTED***/gi')
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $message" >> "$LOG_FILE"
}# 限制日志文件权限
chmod 600 logs/*.log问题: 用户可控的路径可能导致路径遍历攻击
解决方案:
# 验证路径在允许的目录内
validate_path() {
local input_path="$1"
local base_dir="$2"
# 解析为绝对路径
local abs_path=$(realpath "$input_path" 2>/dev/null)
local abs_base=$(realpath "$base_dir")
# 检查是否在基础目录内
if [[ "$abs_path" != "$abs_base"* ]]; then
echo "错误: 路径不在允许的目录内"
return 1
fi
return 0
}# 安全的文件复制
safe_copy() {
local src="$1"
local dst="$2"
# 验证源文件存在
if [ ! -f "$src" ]; then
echo "错误: 源文件不存在"
return 1
fi
# 验证目标路径
validate_path "$dst" "$PROJECT_ROOT" || return 1
# 执行复制
cp "$src" "$dst"
}问题: 用户输入可能包含恶意命令
解决方案:
# 严格的输入验证
validate_input() {
local input="$1"
local pattern="$2"
if ! [[ "$input" =~ ^${pattern}$ ]]; then
echo "错误: 输入格式无效"
return 1
fi
return 0
}
# 示例: 验证 Agent 名称
validate_agent_name() {
local name="$1"
# 只允许字母、数字、连字符和下划线
validate_input "$name" "[a-zA-Z0-9_-]+"
}# 使用数组避免命令注入
safe_execute() {
local cmd=("$@")
"${cmd[@]}"
}
# 错误示例(易受注入攻击)
# eval "$user_input"
# 正确示例
safe_execute git status# 扫描 npm 依赖漏洞
npm audit
# 修复可自动修复的漏洞
npm audit fix
# 查看详细报告
npm audit --jsonpackage.json:
{
"dependencies": {
"express": "4.18.2", // 精确版本
"lodash": "~4.17.21" // 补丁版本
}
}.gitignore:
# 环境变量
.env
.env.local
.env.*.local
# API 密钥
**/secrets/
**/*-key.json
**/*-credentials.json
# 日志文件
logs/
*.log
# 临时文件
tmp/
temp/
#!/bin/bash
# .git/hooks/pre-commit
# 检查是否包含敏感信息
if git diff --cached | grep -E "(api[_-]key|password|secret|token)" -i; then
echo "警告: 检测到可能的敏感信息"
echo "请检查并移除后再提交"
exit 1
fi# 确保使用 HTTPS
if [[ "$API_URL" != https://* ]]; then
echo "错误: 必须使用 HTTPS"
exit 1
fi# 设置合理的超时
curl --max-time 30 "$API_URL"# 脚本文件
chmod 755 scripts/*.sh
# 配置文件
chmod 644 config/*.json
# 敏感文件
chmod 600 .env- 不要以 root 用户运行脚本
- 使用最小权限原则
- 定期审查文件权限
- 所有 API 密钥使用环境变量
- 输入验证已实施
- 日志不包含敏感信息
- 路径遍历防护已添加
- 命令注入防护已实施
- 依赖漏洞已扫描
- 文件权限已正确设置
- .gitignore 已配置
- Pre-commit hook 已安装
- HTTPS 已强制启用
- 定期更新依赖
- 定期审查日志
- 定期备份数据
- 定期安全审计
在安装或登记第三方 Skill/Agent 前,先完成安全审查,不直接运行未审查的一键安装命令。
审查重点:
- 权限是否最小化:警惕同时要求 shell、网络、文件写入、浏览器控制的 Skill。
- 密钥是否安全:不得读取、上传或记录
.env、token、cookie、浏览器会话。 - 外联是否透明:必须明确会访问的 API、域名和上传的数据类型。
- 提示词是否安全:拒绝包含越狱、隐藏指令、绕过系统约束或规避检测的 Skill。
- 功能是否重复:与现有 Skill 重叠时,优先提炼 Gotchas/模板,而不是新增依赖。
审查结论格式:
### 第三方 Skill/Agent 审查结论
- 来源:仓库/作者/版本或提交标识
- 权限:shell / 网络 / 文件写入 / 浏览器 / MCP / 其他
- 密钥:是否读取、上传、记录 token、cookie、`.env`
- 外联:访问域名、API、上传数据类型
- 提示词安全:是否包含越狱、隐藏指令、绕过系统约束或规避检测
- 功能重复:与现有 Skill/Agent 的重叠和替代方案
- 结论:通过 / 隔离验证后通过 / 拒绝处理原则:
- 安全研究、越狱、规避检测类材料只可转化为防御性审查清单,不保存可执行攻击流程。
- 需要真实账号、浏览器登录态或 API Key 的 Skill,默认在隔离环境验证后再使用。
- 只有通过审查且会长期使用的 Skill,才登记到
docs/SKILLS-CATALOG.md。
- 立即撤销 泄露的密钥
- 生成新密钥 并更新配置
- 审查日志 查找异常活动
- 通知相关方 如果有数据泄露
- 评估影响 确定漏洞严重程度
- 隔离系统 如果需要
- 应用补丁 修复漏洞
- 验证修复 确保问题解决
- 记录事件 更新安全文档
如发现安全问题,请通过以下方式报告:
- GitHub Issues (标记为 security)
- 邮件: security@example.com
请勿公开披露安全漏洞,直到我们有机会修复。