Back to Details

specstory-guard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SpecStory Guard

SpecStory Guard

A pre-commit guardrail that scans 
.specstory/history
for potential secrets and blocks commits until they are removed or redacted.
一个预提交防护工具，会扫描
.specstory/history
目录以查找潜在密钥，并在密钥被移除或编辑前阻止提交。

How It Works

工作原理

  1. Installs a git pre-commit hook in your repository
  2. Scans 
    .specstory/history
    files on every commit
  3. Detects common secret patterns (API keys, tokens, private keys)
  4. Blocks the commit if secrets are found
  5. Reports findings with redacted previews for safe review
  1. 安装：在你的代码仓库中安装git预提交钩子
  2. 扫描：每次提交时扫描
    .specstory/history
    文件
  3. 检测：识别常见的密钥模式（API密钥、令牌、私钥）
  4. 阻止：如果发现密钥则阻止提交
  5. 报告：生成包含编辑预览的检测结果，以便安全查看

Why Use Guard?

为什么使用该防护工具？

AI coding sessions may inadvertently capture sensitive data:
  • API keys you pasted into chat
  • Environment variables in command output
  • Private keys or tokens in error messages
  • Credentials in configuration examples
Guard prevents accidental commits of these secrets.
AI编码会话可能会意外捕获敏感数据：
  • 你粘贴到聊天中的API密钥
  • 命令输出中的环境变量
  • 错误消息中的私钥或令牌
  • 配置示例中的凭据
该防护工具可防止这些密钥被意外提交。

Usage

使用方法

Slash Command

斜杠命令

User saysAction
/specstory-guard
Install the pre-commit hook
/specstory-guard install
Install the pre-commit hook
/specstory-guard scan
Run a manual scan without installing
/specstory-guard check
Alias for scan
/specstory-guard uninstall
Remove the pre-commit hook
用户指令操作
/specstory-guard
安装预提交钩子
/specstory-guard install
安装预提交钩子
/specstory-guard scan
手动运行扫描，无需安装
/specstory-guard check
scan的别名
/specstory-guard uninstall
移除预提交钩子

Direct Script Usage

直接脚本使用

bash
undefined
bash
undefined

Install the pre-commit hook

Install the pre-commit hook

python skills/specstory-guard/scripts/guard.py install
python skills/specstory-guard/scripts/guard.py install

Run a manual scan

Run a manual scan

python skills/specstory-guard/scripts/guard.py scan --root .
python skills/specstory-guard/scripts/guard.py scan --root .

Uninstall the hook

Uninstall the hook

python skills/specstory-guard/scripts/guard.py uninstall
python skills/specstory-guard/scripts/guard.py uninstall

Scan with custom allowlist

Scan with custom allowlist

SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*'
python skills/specstory-guard/scripts/guard.py scan --root .
undefined
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*'
python skills/specstory-guard/scripts/guard.py scan --root .
undefined

Output

输出示例

Scan with findings:

扫描到密钥时：

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/...

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.

Clean scan:

扫描无问题时：

SpecStory Guard - Security Scan
===============================

Scanning .specstory/history/...

All clear! No secrets detected in 47 files.
SpecStory Guard - Security Scan
===============================

Scanning .specstory/history/...

All clear! No secrets detected in 47 files.

Installation success:

安装成功时：

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 .
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 .

Detected Patterns

检测模式

Guard scans for these common secret patterns:
PatternExample
AWS Keys
AKIA...
, 
aws_secret_access_key
API Tokens
Bearer ...
, 
token: ...
Private Keys
-----BEGIN RSA PRIVATE KEY-----
GitHub Tokens
ghp_...
, 
github_pat_...
Generic Secrets
password=
, 
secret=
, 
api_key=
该防护工具会扫描以下常见密钥模式：
模式示例
AWS密钥
AKIA...
, 
aws_secret_access_key
API令牌
Bearer ...
, 
token: ...
私钥
-----BEGIN RSA PRIVATE KEY-----
GitHub令牌
ghp_...
, 
github_pat_...
通用密钥
password=
, 
secret=
, 
api_key=

Tuning with Allowlist

使用允许列表进行调优

If you have false positives (example keys, placeholders), use the allowlist:
bash
undefined
如果出现误报（例如示例密钥、占位符），可以使用允许列表：
bash
undefined

Environment variable (comma-separated regex patterns)

Environment variable (comma-separated regex patterns)

SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*,test-token'
python skills/specstory-guard/scripts/guard.py scan --root .
undefined
SPECSTORY_GUARD_ALLOWLIST='example-key,PLACEHOLDER_.*,test-token'
python skills/specstory-guard/scripts/guard.py scan --root .
undefined

Remediation

修复步骤

When secrets are found:
  1. Open the file - Find the line number from the report
  2. Redact the secret - Replace with 
    [REDACTED]
    or remove the line
  3. Re-run scan - Verify the fix with another scan
  4. Commit - The pre-commit hook will pass
当发现密钥时：
  1. 打开文件 - 根据报告中的行号找到对应位置
  2. 编辑密钥 - 替换为
    [REDACTED]
    或删除该行
  3. 重新扫描 - 再次运行扫描以验证修复
  4. 提交 - 预提交钩子将允许提交

Present Results to User

向用户展示结果

After running guard commands:
  1. For install - Confirm the hook is installed and explain what it does
  2. For scan with findings - List the findings and offer to help redact them
  3. For clean scan - Confirm no secrets were found
运行防护工具命令后：
  1. 安装完成 - 确认钩子已安装并说明其功能
  2. 扫描到密钥 - 列出检测结果并提供编辑帮助
  3. 扫描无问题 - 确认未发现密钥

Example Response (findings)

示例回复（检测到密钥时）

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.
我在你的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]`，同时保留对话的其余上下文。

Notes

注意事项

  • Uses no external dependencies (pure Python)
  • Hook runs automatically on 
    git commit
  • Scan is fast - typically under 1 second for hundreds of files
  • Allowlist patterns are regular expressions
  • 不依赖外部库（纯Python实现）
  • 钩子会在
    git commit
    时自动运行
  • 扫描速度快 - 通常处理数百个文件只需不到1秒
  • 允许列表模式支持正则表达式