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

> Discover the security mechanism for scanning secrets in gsd-build codebase mapping. Our guide explains how API keys and tokens are automatically detected before committing files.

- Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/gsd-build/get-shit-done/blob/main/STACK.md), [`ARCHITECTURE.md`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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:

```bash
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:

```bash
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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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.