名称: specstory-guard 描述: 在提交前安装一个预提交钩子，扫描 .specstory/history 中的秘密。当用户说“设置秘密扫描”、“安装 specstory 守卫”、“保护我的历史”或“检查秘密”时运行。许可证: Apache-2.0 元数据: 作者: SpecStory, Inc. 版本: “1.0.0” 参数提示: “[安装|扫描|检查|卸载] [–根路径路径]” 允许工具: Bash, 读取, 写入

SpecStory 守卫

一个预提交护栏，扫描 .specstory/history 中的潜在秘密，并在移除或编辑前阻止提交。

工作原理

安装一个 git 预提交钩子到您的仓库
扫描每次提交时的 .specstory/history 文件
检测常见秘密模式（API 密钥、令牌、私钥）
阻止如果发现秘密则阻止提交
报告发现结果，带有编辑预览以安全审查

为什么使用守卫？

AI 编码会话可能无意中捕获敏感数据：

您在聊天中粘贴的 API 密钥
命令输出中的环境变量
错误消息中的私钥或令牌
配置示例中的凭证

守卫防止意外提交这些秘密。

用法

斜杠命令

用户说	操作
`/specstory-guard`	安装预提交钩子
`/specstory-guard install`	安装预提交钩子
`/specstory-guard scan`	在不安装的情况下运行手动扫描
`/specstory-guard check`	扫描的别名
`/specstory-guard uninstall`	移除预提交钩子

直接脚本用法

# 安装预提交钩子
python skills/specstory-guard/scripts/guard.py install

# 运行手动扫描
python skills/specstory-guard/scripts/guard.py scan --root .

# 卸载钩子
python skills/specstory-guard/scripts/guard.py uninstall

# 使用自定义允许列表扫描
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*' \
  python skills/specstory-guard/scripts/guard.py scan --root .

输出

扫描有发现：

SpecStory 守卫 - 安全扫描
===============================

扫描 .specstory/history/...

警报：发现潜在秘密！

文件： .specstory/history/2026-01-22_19-20-56Z-api-setup.md
  第 142 行： AWS_SECRET_ACCESS_KEY=AKIA...已编辑...XYZ
  第 289 行： private_key: "-----BEGIN RSA PRIVATE KEY-----..."

文件： .specstory/history/2026-01-20_10-15-33Z-debug-auth.md
  第 56 行： Authorization: Bearer eyJhbG...已编辑...

总计：2 个文件中的 3 个潜在秘密

提交被阻止。请在提交前编辑或移除这些秘密。

干净扫描：

SpecStory 守卫 - 安全扫描
===============================

扫描 .specstory/history/...

全部清除！在 47 个文件中未检测到秘密。

安装成功：

SpecStory 守卫 - 设置
=======================

预提交钩子已安装于 .git/hooks/pre-commit

钩子现在将在每次提交前扫描 .specstory/history/。
测试： python skills/specstory-guard/scripts/guard.py scan --root .

检测模式

守卫扫描这些常见秘密模式：

模式	示例
AWS 密钥	`AKIA...`, `aws_secret_access_key`
API 令牌	`Bearer ...`, `token: ...`
私钥	`-----BEGIN RSA PRIVATE KEY-----`
GitHub 令牌	`ghp_...`, `github_pat_...`
通用秘密	`password=`, `secret=`, `api_key=`

使用允许列表调优

如果您有误报（示例密钥、占位符），使用允许列表：

# 环境变量（逗号分隔的正则表达式模式）
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*,test-token' \
  python skills/specstory-guard/scripts/guard.py scan --root .

修复

当发现秘密时：

打开文件 - 从报告中找到行号
编辑秘密 - 替换为 [已编辑] 或移除该行
重新运行扫描 - 用另一次扫描验证修复
提交 - 预提交钩子将通过

向用户呈现结果

运行守卫命令后：

对于安装 - 确认钩子已安装并解释其作用
对于扫描有发现 - 列出发现并提供帮助编辑
对于干净扫描 - 确认未发现秘密

示例响应（发现）

我在您的 SpecStory 历史中发现了 3 个潜在秘密：

1. **AWS 凭证** 在 `2026-01-22_19-20-56Z-api-setup.md`（第 142 行）
2. **私钥** 在同一文件中（第 289 行）
3. **Bearer 令牌** 在 `2026-01-20_10-15-33Z-debug-auth.md`（第 56 行）

您希望我帮助编辑这些吗？我可以将它们替换为 `[已编辑]`，同时保留对话上下文的其他部分。

注意

无外部依赖（纯 Python）
钩子在 git commit 时自动运行
扫描快速 - 通常数百个文件在 1 秒内
允许列表模式是正则表达式