⚡

SpecStory安全卫士 specstory-guard

SpecStory Guard 是一个开发安全工具，通过安装 Git pre-commit hook，自动扫描 .specstory/history 文件中的敏感信息，如 API 密钥、令牌、私钥等，防止秘密数据意外提交到版本控制系统。它提供快速扫描、检测常见模式、支持自定义允许列表，并输出报告。关键词：秘密扫描、Git 安全、安全防护、DevOps 工具、AI 编码安全。

安全运维 0 次安装 0 次浏览 更新于 3/7/2026

name: specstory-guard description: 安装一个 pre-commit hook，在提交前扫描 .specstory/history 中的秘密。当用户说“设置秘密扫描”、“安装 specstory guard”、“保护我的历史”或“检查秘密”时运行。 license: Apache-2.0 metadata: author: SpecStory, Inc. version: “1.0.0” argument-hint: “[install|scan|check|uninstall] [–root PATH]” allowed-tools: Bash, Read, Write

SpecStory Guard

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

工作原理

  1. 安装 一个 git pre-commit hook 到您的仓库
  2. 扫描 每次提交时的 .specstory/history 文件
  3. 检测 常见秘密模式（API 密钥、令牌、私钥）
  4. 阻止 提交如果发现秘密
  5. 报告 发现内容，提供编辑预览以供安全审查

为什么使用 Guard？

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

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

Guard 防止这些秘密的意外提交。

使用方式

斜杠命令

用户说 操作
/specstory-guard 安装 pre-commit hook
/specstory-guard install 安装 pre-commit hook
/specstory-guard scan 运行手动扫描而不安装
/specstory-guard check 扫描的别名
/specstory-guard uninstall 移除 pre-commit hook

直接脚本使用

# 安装 pre-commit hook
python skills/specstory-guard/scripts/guard.py install

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

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

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

输出

扫描有发现：

SpecStory Guard - 安全扫描
===============================

扫描 .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 Guard - 安全扫描
===============================

扫描 .specstory/history/...

一切清晰！在 47 个文件中未检测到秘密。

安装成功：

SpecStory Guard - 设置
=======================

Pre-commit hook 已安装在 .git/hooks/pre-commit

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

检测模式

Guard 扫描这些常见秘密模式：

模式 示例
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 .

修复

当发现秘密时：

  1. 打开文件 - 从报告中找到行号
  2. 编辑秘密 - 替换为 [REDACTED] 或移除该行
  3. 重新运行扫描 - 用另一次扫描验证修复
  4. 提交 - Pre-commit hook 将通过

向用户呈现结果

运行 guard 命令后：

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

示例响应（发现）

我在您的 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）

您希望我帮助编辑这些吗？我可以用 `[REDACTED]` 替换它们，同时保留对话上下文。

注释

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