Security Mechanism for Scanning Secrets in GSD-Build Codebase Mapping: A Complete Guide

The gsd-build workflow automatically scans generated documentation for API keys, tokens, and private keys using a grep-based regex detector before committing files to the repository.

The gsd-build/get-shit-done repository implements a critical security mechanism for scanning secrets during its codebase mapping workflow. When the gsd:map-codebase command runs, it generates documentation files in .planning/codebase/ that could inadvertently contain sensitive credentials from the source code being analyzed. The security mechanism for scanning secrets in gsd-build codebase mapping acts as an automated gate to prevent accidental credential leakage.

How the Secret Scanning Mechanism Works in GSD-Build

The workflow operates as a multi-stage pipeline where documentation generation precedes a mandatory security validation step.

Documentation Generation Phase

Multiple parallel gsd-codebase-mapper agents analyze the repository structure and write Markdown files directly to .planning/codebase/. These files include STACK.md, ARCHITECTURE.md, and other architectural documentation that may quote configuration files or environment variable examples from the source code.

The scan_for_secrets Security Gate

Before any commit occurs, the workflow executes the scan_for_secrets step defined in get-shit-done/workflows/map-codebase.md. This step runs a single grep -E command that searches all generated Markdown files for comprehensive regex patterns matching known secret formats.

Regex Patterns and Detection Capabilities

The detection engine uses an extended regular expression covering major cloud providers, SaaS platforms, and cryptographic formats:

grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+)' \
    .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false

The pattern list includes:

• Stripe keys: sk_live_, sk_test_, and sk- prefixes
• GitHub tokens: ghp_ and gho_ personal access tokens
• GitLab tokens: glpat- prefixed strings
• AWS credentials: AKIA access key IDs
• Slack tokens: xoxb, xoxa, xoxp, xoxr, xoxs formats
• JWT tokens: Base64-encoded JSON Web Token headers
• PEM keys: -----BEGIN private key headers

Workflow Branching: Handling Detected Secrets

The mechanism implements conditional logic that branches based on the SECRETS_FOUND variable.

When Secrets Are Found

If the grep command detects matches, the workflow sets SECRETS_FOUND=true and executes a security alert routine:

if [ "$SECRETS_FOUND" = true ]; then
  echo "⚠️  SECURITY ALERT: Potential secrets detected in codebase documents!"
  echo "Please review and remove any real credentials before proceeding."
  # Workflow pauses here for manual intervention

fi

The offending lines are displayed in the terminal output, and the workflow halts before reaching the commit_codebase_map step. Users must manually verify whether the detected strings are actual secrets or false positives, then edit the documents in .planning/codebase/ accordingly.

When No Secrets Are Detected

If SECRETS_FOUND remains false, the workflow proceeds immediately to the commit_codebase_map step, which commits the generated documentation to the repository with a standard commit message.

Defense in Depth: Claude Code Deny Lists

Beyond the automated grep scanning, the repository implements a defense-in-depth strategy through Claude Code's deny list feature. As documented in README.md, users should add sensitive file paths to Claude Code's "Deny" list before running the mapper workflow.

This preventive measure ensures that gsd-codebase-mapper agents never read files likely to contain secrets—such as .env files, config/secrets.yml, or private key directories—eliminating the risk of those secrets appearing in generated documentation at the source.

Summary

• The security mechanism for scanning secrets in gsd-build codebase mapping uses a grep -E command with comprehensive regex patterns to detect API keys, tokens, and private keys in generated documentation.
• The scan_for_secrets step in get-shit-done/workflows/map-codebase.md acts as a mandatory gate that halts the workflow if credentials are detected, requiring manual review before commit.
• Detection covers major platforms including Stripe, GitHub, GitLab, AWS, Slack, and cryptographic formats like JWT and PEM keys.
• Defense-in-depth is achieved by combining the automated scan with Claude Code deny lists that prevent mapper agents from reading sensitive files initially.

Frequently Asked Questions

What types of secrets does the gsd-build scanner detect?

The scanner detects API keys and tokens from major platforms including Stripe (sk_live_, sk_test_), GitHub (ghp_), GitLab (glpat-), AWS (AKIA), and Slack (xoxb, xoxp). It also identifies cryptographic material such as PEM private keys (-----BEGIN) and JSON Web Tokens (JWTs) with the eyJ header prefix.

Where is the secret scanning logic defined in the repository?

The secret scanning logic is defined in get-shit-done/workflows/map-codebase.md within the scan_for_secrets step. This file contains the grep -E command with the comprehensive regex pattern and the conditional logic that branches based on whether secrets are found. The mapper agents that generate the scanned content are defined in agents/gsd-codebase-mapper.md.

What happens if the scanner finds a false positive?

If the scanner detects a pattern that resembles a secret but is actually a false positive (such as a placeholder string or example code), the workflow halts and displays a security alert with the offending lines. The user must manually review the generated files in .planning/codebase/, remove or modify the false positive text, and then rerun the workflow to proceed past the scan_for_secrets gate.

How does the deny list provide additional security?

The deny list provides defense-in-depth by preventing the gsd-codebase-mapper agents from reading sensitive files before they generate documentation. By adding paths like .env files or private key directories to Claude Code's deny list, users ensure that secrets never enter the mapper's context window, eliminating the risk of accidental inclusion in .planning/codebase/ files regardless of the grep scanner's effectiveness.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}