specstory-guard

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 check	scan の別名です
/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 秒未満で完了します
• 許可リストのパターンには正規表現を使用します