specstory-guard

SpecStory Guard

A pre-commit guardrail that scans .specstory/history for potential secrets and blocks commits until they are removed or redacted.

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

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.

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

Direct Script Usage

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

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.

Clean scan:

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 .

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=

Tuning with Allowlist

If you have false positives (example keys, placeholders), use the allowlist:

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

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

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

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.

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