mcpField
S
specstory-guard

specstory-guard

github.com/specstoryai安全35257 次安装39 周前更新
代码仓库

关于 specstory-guard

SpecStory Guard 是面向在 `.specstory/history` 中保存编码会话记录的仓库的提交前防护工具。它扫描常见秘密信息模式，并在发现潜在秘密时阻止提交。

主要功能

  1. 01安装或移除 Git 提交前钩子
  2. 02手动扫描或提交前扫描 `.specstory/history`
  3. 03检测常见密钥、令牌和私钥
  4. 04以脱敏预览显示发现项
  5. 05配置正则表达式允许列表

适用场景

  1. 01防止会话记录中的凭据被提交
  2. 02安装提交钩子前检查历史文件
  3. 03查看潜在秘密而不完整显示内容
  4. 04扫描时允许已知占位符

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/specstoryai/agent-skills --skill specstory-guard

安装后在 Claude Code 中输入/specstory-guard确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

LICENSE.txt
metadata.json
hooks/
pre-commit
scripts/
guard.py
patterns.py
scan.py
setup.py

详细介绍

SpecStory Guard

一个提交前防护工具，用于扫描 .specstory/history 中的潜在机密，并在移除或脱敏这些内容之前阻止提交。

工作原理

  1. 安装 Git 提交前钩子到你的代码库
  2. 扫描每次提交中的 .specstory/history 文件
  3. 检测常见机密模式（API 密钥、令牌、私钥）
  4. 如果发现机密，阻止提交
  5. 报告发现的问题，并提供脱敏预览以供安全检查

为什么使用 Guard？

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

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

Guard 可防止意外提交这些机密。

用法

斜杠命令
用户输入操作
/specstory-guard安装提交前钩子
/specstory-guard install安装提交前钩子
/specstory-guard scan不安装钩子，直接运行手动扫描
/specstory-guard checkscan 的别名
/specstory-guard uninstall移除提交前钩子
直接使用脚本
# Install the pre-commit hook
python skills/specstory-guard/scripts/guard.py install

# Run a manual scan
python skills/specstory-guard/scripts/guard.py scan --root .

# Uninstall the hook
python skills/specstory-guard/scripts/guard.py uninstall

# Scan with custom allowlist
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*' \
  python skills/specstory-guard/scripts/guard.py scan --root .

输出

扫描发现问题时：
SpecStory Guard - Security Scan
===============================

Scanning .specstory/history/...

ALERT: Potential secrets found!

File: .specstory/history/2026-01-22_19-20-56Z-api-setup.md
  Line 142: AWS_SECRET_ACCESS_KEY=AKIA...redacted...XYZ
  Line 289: private_key: "-----BEGIN RSA PRIVATE KEY-----..."

File: .specstory/history/2026-01-20_10-15-33Z-debug-auth.md
  Line 56: Authorization: Bearer eyJhbG...redacted...

Total: 3 potential secrets in 2 files

Commit blocked. Please redact or remove these secrets before committing.
扫描结果干净时：
SpecStory Guard - Security Scan
===============================

Scanning .specstory/history/...

All clear! No secrets detected in 47 files.
安装成功时：
SpecStory Guard - Setup
=======================

Pre-commit hook installed at .git/hooks/pre-commit

The hook will now scan .specstory/history/ before each commit.
To test: 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=

使用允许列表进行调整

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

# Environment variable (comma-separated regex patterns)
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*,test-token' \
  python skills/specstory-guard/scripts/guard.py scan --root .

修复

发现机密时：

  1. 打开文件——根据报告找到行号
  2. 脱敏机密——替换为 [REDACTED] 或删除该行
  3. 重新运行扫描——再次扫描以验证修复结果
  4. 提交——提交前钩子将通过检查

向用户展示结果

运行 Guard 命令后：

  1. 安装时——确认钩子已安装，并说明其功能
  2. 扫描发现问题时——列出发现的问题，并主动协助脱敏
  3. 扫描结果干净时——确认未发现机密
回复示例（发现问题）
I found 3 potential secrets in your SpecStory history:

1. **AWS credentials** in `2026-01-22_19-20-56Z-api-setup.md` (line 142)
2. **Private key** in the same file (line 289)
3. **Bearer token** in `2026-01-20_10-15-33Z-debug-auth.md` (line 56)

Would you like me to help redact these? I can replace them with `[REDACTED]`
while preserving the rest of the conversation context.

备注

  • 无需外部依赖（纯 Python）
  • 钩子会在 git commit 时自动运行
  • 扫描速度快——扫描数百个文件通常不到 1 秒
  • 允许列表模式使用正则表达式

评论

支持 Markdown