发布前安全协议

防止在开源发布中暴露凭据等安全漏洞。

功能特性

✅ 多层级扫描

• 快速扫描：每次推送时执行（约 5 秒）
• 历史扫描：每月一次深度扫描（约 2–5 分钟）
• 依赖项 CVE 扫描：每周执行 npm/Python 检查（约 30 秒）
• 完整审计：按需触发的全面扫描（约 3–6 分钟）

✅ 智能频率管理

• 状态跟踪可记录每类扫描的最后执行时间
• 自动判断需运行哪些扫描任务
• 避免重复检查

✅ 检测范围

• GitHub PAT、API 密钥、密码、私钥
• Git 历史中的密钥（即使已“删除”仍可访问）
• npm/Python 依赖项的 CVE 漏洞
• 不安全代码模式（如 eval、exec）
• 文档占位符（如 [ORG]、example.com）
• 缺失 LICENSE/README 文件
• 导出含密钥的环境变量

✅ 自动化防护

• Git pre-push 钩子阻止存在风险的提交
• 基于严重等级返回退出码（CRITICAL/HIGH/MEDIUM/LOW）
• 生成含可操作修复建议的 Markdown 报告

快速上手

安装 pre-push 钩子

# 每次推送时自动启用防护
./install-hooks.sh /path/to/your/repo

首次执行历史扫描

# 一次性深度扫描（或每月执行）
./audit-full.sh /path/to/repo history

查看当前状态

# 查看各扫描任务最后执行时间
./schedule.sh status

运行计划内审计

# 根据时间自动判断需执行的扫描类型
./schedule.sh run /path/to/repo

手动扫描

# 快速扫描（每次推送时执行）
./audit-simple.sh /path/to/repo

# Git 历史扫描（每月执行）
./audit-full.sh /path/to/repo history

# 依赖项扫描（每周执行）
./audit-full.sh /path/to/repo dependencies

# 完整审计（发布前执行）
./audit-full.sh /path/to/repo full

扫描内容说明

快速扫描（每次推送）

• 当前文件中的密钥模式匹配
• 文档占位符检测
• 基础 LICENSE/README 文件存在性检查
• 执行耗时：约 5 秒

历史扫描（每月执行）

• 完整 Git 提交历史遍历
• 已删除但仍可访问的凭据
• 历史遗留的安全问题
• 执行耗时：2–5 分钟

依赖项扫描（每周执行）

• npm audit（Node.js CVE 检测）
• Python safety 检查
• 已知漏洞识别
• 执行耗时：约 30 秒

完整审计（按需执行）

• 涵盖上述全部检查项
• 环境变量泄露检测
• pre-commit 钩子有效性验证
• 代码质量模式检查
• 执行耗时：3–6 分钟

严重等级定义

• CRITICAL → 阻止推送（密钥、凭据泄露）
• HIGH → 需人工审批（漏洞、缺失 LICENSE）
• MEDIUM → 警告（TODO 注释、缺失 README）
• LOW → 信息提示

集成方式

pre-push 钩子（推荐）

./install-hooks.sh ~/my-repo
git push  # 自动执行安全检查

每周定时任务（Cron）

# 添加至 OpenClaw cron
openclaw cron add 
  --name "weekly-repo-scan" 
  --cron "0 3 * * 1" 
  --announce 
  --message "Run: ~/.openclaw/workspace/skills/pre-publish-security/schedule.sh run ~/repo"

手动发布前检查

# 在 clawhub publish 前执行
./audit-full.sh ~/skills/my-skill full
clawhub publish skills/my-skill --version 1.0.1

相关文件

• audit-simple.sh — 快速 pre-push 扫描脚本
• audit-full.sh — 具备状态跟踪能力的完整扫描器
• schedule.sh — 状态查询与智能调度脚本
• install-hooks.sh — Git 钩子安装脚本
• audit-state.json — 状态跟踪文件（自动生成）
• AUDIT-SCHEDULE.md — 详细扫描频率指南
• README.md — 完整使用文档
• agents/ — 子代理定义目录（预留未来扩展）

运行依赖

必需依赖：

• git
• jq
• grep

可选依赖（增强检测能力）：

• npm（用于 Node.js 依赖项扫描）
• pip + safety（用于 Python 依赖项扫描）
• shellcheck（用于 Bash 脚本校验）

状态跟踪

自动记录以下信息：

• 每类扫描的最后执行时间戳
• 各类扫描的累计执行次数
• 按严重等级统计的累计发现数

查看方式：./schedule.sh status

退出码说明

• 0 — 通过（无问题，或仅存在 LOW/MEDIUM 级别问题）
• 1 — 存在 CRITICAL 级别问题（阻止推送）
• 2 — 存在 HIGH 级别问题（需人工复核）

真实案例

问题：误将 GitHub PAT 写入 git remote URL 并推送
解决方案：本工具捕获该风险并阻止推送
结果：凭据从未被公开暴露

适用场景

1. 个人开发者：pre-push 钩子防止误操作
2. 开源项目：防范贡献者引入的安全失误
3. ClawHub 技能：确保技能发布前完成合规验证
4. CI/CD 流水线：集成至 GitHub Actions 实现自动化检查
5. 安全审计：对代码仓库执行全面审查

设计初衷

2026-03-15，某项目因在 git 配置文件中意外暴露 GitHub PAT 导致安全事件。本协议旨在彻底杜绝此类问题——对任何人皆然。

许可证

MIT 协议 — 欢迎自由使用、改进与分享。

参与贡献

欢迎提交 Issue 与 Pull Request：https://github.com/solmas/pre-publish-security