specstory-guard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

工作原理

Installs a git pre-commit hook in your repository
Scans
```
.specstory/history
```
files on every commit
Detects common secret patterns (API keys, tokens, private keys)
Blocks the commit if secrets are found
Reports findings with redacted previews for safe review

安装：在你的代码仓库中安装git预提交钩子
扫描：每次提交时扫描
```
.specstory/history
```
文件
检测：识别常见的密钥模式（API密钥、令牌、私钥）
阻止：如果发现密钥则阻止提交
报告：生成包含编辑预览的检测结果，以便安全查看

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 says	Action
`/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

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 .

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:

Pattern	Example
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)

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:

Open the file - Find the line number from the report
Redact the secret - Replace with
```
[REDACTED]
```
or remove the line
Re-run scan - Verify the fix with another scan
Commit - The pre-commit hook will pass

当发现密钥时：

打开文件 - 根据报告中的行号找到对应位置
编辑密钥 - 替换为
```
[REDACTED]
```
或删除该行
重新扫描 - 再次运行扫描以验证修复
提交 - 预提交钩子将允许提交

Present Results to User

向用户展示结果

After running guard commands:

For install - Confirm the hook is installed and explain what it does
For scan with findings - List the findings and offer to help redact them
For clean scan - Confirm no secrets were found

运行防护工具命令后：

安装完成 - 确认钩子已安装并说明其功能
扫描到密钥 - 列出检测结果并提供编辑帮助
扫描无问题 - 确认未发现密钥

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秒
允许列表模式支持正则表达式