Ftm Git

Events

Emits

• secrets_found — when scan detects hardcoded credentials in staged files or working tree
• secrets_clear — when scan completes with no findings (safe to proceed with commit/push)
• secrets_remediated — when auto-fix successfully extracts secrets to .env and refactors source files
• task_completed — when full scan + remediation cycle finishes

Listens To

• code_changed — run a quick scan on modified files before they get staged
• code_committed — verify the commit doesn't contain secrets (post-commit safety net)

Blackboard Read

Before starting, load context from the blackboard:

1. Read ~/.claude/ftm-state/blackboard/context.json — check current_task, recent_decisions, active_constraints
2. Read ~/.claude/ftm-state/blackboard/experiences/index.json — filter entries by task_type="security" or tags matching "secrets", "credentials", "api-keys", or "git-safety"
3. Load top 3-5 matching experience files for previously found secret patterns and effective remediation strategies
4. Read ~/.claude/ftm-state/blackboard/patterns.json — check recurring_issues for repeated secret leaks and execution_patterns for which files/directories tend to accumulate secrets

If index.json is empty or no matches found, proceed normally without experience-informed shortcuts.

FTM Git — Secret Scanning & Credential Safety Gate

This skill exists because secrets pushed to GitHub are compromised the instant they hit the remote — even if you force-push a clean history seconds later. Bots scrape public repos continuously, and private repos are one permissions mistake away from exposure. The only safe secret is one that never enters git history.

This is not a nice-to-have audit. This is a hard gate. Nothing gets committed or pushed until this skill says it's clean.

Why This Matters

Yesterday we pushed API keys to the repo. That's the kind of mistake that leads to compromised accounts, unexpected bills, and emergency credential rotations. This skill makes it structurally impossible for that to happen again by scanning every file that's about to be committed and blocking the operation if secrets are present — then auto-fixing what it can.

Phase -1: Install Git Hook (First Invocation Only)

The first time ftm-git runs in a repo, install a pre-commit hook as a hard safety net. This hook runs independently of Claude — it's a shell script that blocks git commit if staged files contain Tier 1 secret patterns. Even if Claude forgets to invoke this skill, or someone runs git directly from the terminal, the hook catches it.

Check if the hook is already installed:

# Look for ftm-git marker in existing pre-commit hook
grep -q "ftm-git" .git/hooks/pre-commit 2>/dev/null

If not installed, copy the hook script:

cp ~/.claude/skills/ftm-git/scripts/pre-commit-secrets.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

If a pre-commit hook already exists (from husky, pre-commit framework, etc.), don't overwrite it. Instead, append the ftm-git scan to the end of the existing hook:

echo "" >> .git/hooks/pre-commit
echo "# --- ftm-git secret scanner ---" >> .git/hooks/pre-commit
cat ~/.claude/skills/ftm-git/scripts/pre-commit-secrets.sh >> .git/hooks/pre-commit

Tell the user: "Installed ftm-git pre-commit hook. Commits with hardcoded secrets will be blocked automatically, even outside of Claude."

This only needs to happen once per repo. On subsequent invocations, skip this phase.

Phase 0: Determine Scan Scope

Before scanning, figure out what needs scanning and why you were invoked.

Invocation context determines scope:

Always also check these regardless of invocation context:

• Any .env file that is NOT in .gitignore — this is itself a finding
• Any file matching *credentials*, *secret*, *token* in the filename

Phase 1: Pattern Scan

Scan the in-scope files using regex patterns. The goal is zero false negatives — a few false positives are acceptable and will be filtered in Phase 2.

Tier 1: High-Confidence Patterns (almost certainly real secrets)

These patterns have distinctive prefixes or structures that make false positives rare:

# AWS
AKIA[0-9A-Z]{16}                                          # AWS Access Key ID
amzn\.mws\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}  # AWS MWS

# GitHub
ghp_[A-Za-z0-9_]{36}                                      # GitHub PAT (classic)
gho_[A-Za-z0-9_]{36}                                      # GitHub OAuth
ghu_[A-Za-z0-9_]{36}                                      # GitHub user token
ghs_[A-Za-z0-9_]{36}                                      # GitHub server token
github_pat_[A-Za-z0-9_]{82}                                # GitHub fine-grained PAT

# Slack
xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}           # Slack bot token
xoxp-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack user token
xoxa-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack app token
xoxr-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack refresh token

# Google
AIza[0-9A-Za-z\-_]{35}                                    # Google API key

# Stripe
sk_live_[0-9a-zA-Z]{24,}                                  # Stripe secret key (live)
sk_test_[0-9a-zA-Z]{24,}                                  # Stripe secret key (test)
rk_live_[0-9a-zA-Z]{24,}                                  # Stripe restricted key

# Other services
SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}               # SendGrid
SK[0-9a-fA-F]{32}                                          # Twilio
npm_[A-Za-z0-9]{36}                                        # npm token
pypi-[A-Za-z0-9\-_]{100,}                                 # PyPI token
glpat-[A-Za-z0-9\-_]{20,}                                 # GitLab PAT
-----BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY-----      # Private keys

Tier 2: Context-Dependent Patterns (need surrounding context to confirm)

These match common assignment patterns. Check that the value isn't a placeholder, empty string, or env var reference before flagging:

# Generic key/secret assignments — flag if value looks real (not placeholder)
(api_key|apikey|api-key)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
(secret|secret_key|client_secret)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
(password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{8,}["']?
(token|access_token|auth_token)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{16,}["']?
(database_url|db_url|connection_string)\s*[:=]\s*["']?[^\s"']{20,}["']?

# Bearer tokens in code
bearer\s+[A-Za-z0-9\-._~+/]{20,}

# Webhook URLs with tokens
https://hooks\.slack\.com/services/T[A-Z0-9]{8,}/B[A-Z0-9]{8,}/[a-zA-Z0-9]{24}

What to Ignore (false positive suppression)

Skip matches that are clearly not real secrets:

• Values that are "", '', None, null, undefined, TODO, CHANGEME, your-key-here, xxx, placeholder, example, test, dummy, fake, sample
• References to environment variables: os.environ[, process.env., ENV[, ${, os.getenv(
• Lines that are comments (#, //, /*, --)
• Files in node_modules/, .git/, vendor/, __pycache__/, dist/, build/
• Files that are themselves .env.example, .env.sample, .env.template
• Lock files (package-lock.json, yarn.lock, Gemfile.lock, poetry.lock)
• Test fixtures where the "secret" is obviously fake (e.g., test_api_key = "sk_test_abc123" in a test file — but still flag sk_live_* in test files, those are real)

Running the Scan

Use the Grep tool to search in-scope files for each pattern. Run Tier 1 patterns in parallel since they're independent. For Tier 2, check surrounding context before confirming.

For each finding, record:

• file: absolute path
• line: line number
• pattern: which pattern matched
• tier: 1 or 2
• value_preview: first 8 chars + ... + last 4 chars (never log the full secret)
• context: the surrounding code (with the secret value masked)

Phase 2: Validate Findings

For each Tier 2 match, read the surrounding context (5 lines before and after) and determine:

1. Is the value a real secret or a placeholder? — Check against the ignore list above.
2. Is it already using an env var? — If the code does key = os.environ.get("API_KEY", "sk_live_abc..."), the hardcoded value is a fallback default. Still a finding — fallback defaults with real secrets are dangerous.
3. Is it in a file that should be gitignored? — If the secret is in .env and .env is in .gitignore, it's fine. If .env is NOT in .gitignore, that's a separate finding.

After validation, produce a findings list sorted by severity:

If zero findings after validation: emit secrets_clear and proceed. The commit/push is safe.

If any CRITICAL or HIGH findings: STOP. The commit/push is BLOCKED. Say this explicitly to the user before doing anything else:

ftm-git: BLOCKED — <N> secret(s) found. Commit/push halted. Attempting auto-remediation...

Then proceed to Phase 3 to fix. The commit/push does NOT happen until Phase 3 completes and a re-scan in Phase 3 Step 5 comes back clean. This is non-negotiable — even if you can fix the secrets, the user needs to see that the operation was blocked and why.

Phase 3: Auto-Remediate

For each finding, apply the appropriate fix automatically. The goal is to make the code safe without breaking functionality.

Step 1: Ensure .env infrastructure exists

Check for a .env file in the project root. If it doesn't exist, create one with a header comment:

# Environment variables — DO NOT COMMIT THIS FILE
# Copy .env.example for the template, fill in real values locally

Check .gitignore for .env coverage. If missing, add:

# Environment files with secrets
.env
.env.local
.env.production
.env.staging
.env.*.local

Step 2: Extract secrets to .env

For each finding:

1. Choose an env var name — derive it from the context. If the code says STRIPE_API_KEY = "sk_live_...", the env var is STRIPE_API_KEY. If it says api_key: "AIza...", infer from the file/service context (e.g., GOOGLE_API_KEY). Use SCREAMING_SNAKE_CASE.

2. Add to .env — append VAR_NAME=<actual-secret-value> to .env. If the var already exists, don't duplicate it.

3. Add to .env.example — create or update .env.example with VAR_NAME=your-value-here so other developers know the variable exists without seeing the real value.

Step 3: Refactor source files

Replace the hardcoded secret with an env var reference. Match the language/framework:

If the file doesn't already import the env-reading module (e.g., import os in Python, require('dotenv').config() in Node), add the import. Check if the project uses python-dotenv, dotenv (Node), or similar — if so, use the project's existing pattern for loading env vars.

Step 4: Unstage remediated files

After refactoring, make sure the .env file (with real secrets) is NOT staged:

git reset HEAD .env 2>/dev/null  # unstage if accidentally staged

Stage the refactored source files (which now reference env vars instead of hardcoded secrets):

git add <refactored-files>

Step 5: Verify the fix

Re-run Phase 1 scan on the refactored files to confirm the secrets are gone. If any remain, loop back and fix. Do not proceed until the scan is clean.

Phase 4: Report

After remediation (or if the scan was clean from the start), produce a summary:

Clean scan:

ftm-git: Clean scan. 0 secrets found in <N> files scanned. Safe to commit.

After remediation:

ftm-git: Found <N> hardcoded secrets. Auto-remediated:

  CRITICAL: sk_live_**** in src/payments.py:42 -> STRIPE_SECRET_KEY
  HIGH:     AIza**** in config/google.ts:18 -> GOOGLE_API_KEY
  MEDIUM:   .env was not in .gitignore -> added

Actions taken:
  - Extracted <N> secrets to .env (gitignored)
  - Created/updated .env.example with placeholder vars
  - Refactored <N> source files to use env var references
  - Updated .gitignore

Verify the app still works with the new env var setup, then commit.

Blocked (auto-fix not possible):

Some secrets can't be auto-fixed — for example, a private key embedded in a binary file, or a secret in a format the skill can't safely refactor. In these cases:

ftm-git: BLOCKED. Found secrets that require manual remediation:

  CRITICAL: Private key in assets/cert.pem:1
            -> Move this file outside the repo and reference via path env var

  Action required: Fix the above manually, then run ftm-git again.

Phase 5: Git History Check (Manual Invocation Only)

When explicitly asked to do a deep scan (e.g., "scan the repo history for secrets"), also check past commits. This is expensive so it only runs on explicit request, not as part of the pre-commit gate.

git log --all --diff-filter=A --name-only --pretty=format:"%H" -- "*.env" "*.pem" "*.key" "*credentials*" "*secret*"

For each historically added sensitive file, check if it's still in the current tree. If it was added and later removed, warn that the secret is still in git history and suggest:

1. Rotate the credential immediately (it's compromised)
2. Use git filter-repo or BFG Repo Cleaner to purge from history if needed

Operating Principles

1. Block first, fix second. Never let a secret through while figuring out the fix. The commit waits.
2. Zero false negatives over zero false positives. It's better to flag something that turns out to be harmless than to miss a real key.
3. Never log full secrets. In all output, mask secret values. Show only enough to identify which secret it is (first 8 + last 4 chars).
4. Env vars are the escape hatch. The remediation pattern is always: secret goes to gitignored .env, code references the env var.
5. Existing patterns win. If the project already uses dotenv, Vault, AWS Secrets Manager, or any other secret management system, match that pattern rather than introducing a new one.
6. Test files are not exempt. A real sk_live_* key in a test file is just as dangerous as one in production code. Only sk_test_* with obviously fake values get a pass.

Integration Points

With ftm-executor

ftm-executor should invoke ftm-git before every commit operation in its task execution loop. If ftm-git emits secrets_found, the executor must pause and remediate before proceeding.

With ftm-mind

When ftm-mind routes a commit or push request, it should run ftm-git as a prerequisite gate. The commit/push only proceeds after secrets_clear or secrets_remediated.

With git-workflow agent

The git-workflow agent should check with ftm-git before executing any commit or push command. If you're about to run git commit or git push, ftm-git goes first.

Post-Commit Experience Recording

FTM includes a post-commit hook that guarantees every commit produces an experience entry in the blackboard.

How It Works

1. After every git commit, the hook checks if an experience was recorded in the last 2 minutes
2. If yes (the LLM already recorded a detailed experience) → skip, no duplicate
3. If no → create a minimal experience from commit metadata (hash, message, files, branch)
4. Update the experience index

Installation

The hook is at ftm-git/hooks/post-commit-experience.sh. To install:

cp ~/.claude/skills/ftm-git/hooks/post-commit-experience.sh .git/hooks/post-commit
chmod +x .git/hooks/post-commit

Or add to your project's husky config if using husky.

Minimal vs Rich Experiences

• Minimal (from hook): commit metadata only, confidence 0.5, tags: auto-recorded
• Rich (from LLM): full task context, lessons learned, higher confidence, domain-specific tags

The hook ensures no commit goes unrecorded, while the LLM produces richer entries during active sessions.

Blackboard Write

After completing, update the blackboard:

1. Update ~/.claude/ftm-state/blackboard/context.json:
   • Set current_task status to "complete"
   • Append scan summary to recent_decisions (cap at 10)
   • Update session_metadata.skills_invoked and last_updated
2. Write an experience file to experiences/YYYY-MM-DD_secret-scan-<slug>.json with:
   • Number of files scanned
   • Findings by severity
   • Remediation actions taken
   • Which patterns matched (to improve future scans)
3. Update experiences/index.json with the new entry
4. Emit secrets_clear or secrets_remediated or secrets_blocked

Requirements

• tool: git | required | staged file inspection, commit history scanning
• reference: references/patterns/SECRET-PATTERNS.md | required | Tier 1/2 patterns, severity table, ignore list
• reference: references/protocols/REMEDIATION.md | required | remediation protocol, env var patterns, report formats
• reference: ~/.claude/skills/ftm-git/scripts/pre-commit-secrets.sh | required | pre-commit hook script for installation
• reference: ~/.claude/skills/ftm-git/hooks/post-commit-experience.sh | optional | post-commit experience recorder hook

Risk

• level: medium_write
• scope: modifies source files to replace hardcoded secrets with env var references; creates/updates .env and .env.example files; installs git hooks in .git/hooks/; re-stages files after remediation
• rollback: git checkout on refactored source files; manually remove added .env and .gitignore entries; remove hook from .git/hooks/pre-commit

Approval Gates

• trigger: CRITICAL or HIGH severity secret found | action: BLOCK commit/push immediately, announce "BLOCKED — N secret(s) found", then attempt auto-remediation
• trigger: auto-remediation proposed for a finding | action: show proposed change (file, variable name, env var name) before applying
• trigger: re-scan after remediation still finds secrets | action: report remaining findings to user, do not proceed with commit
• complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto

Fallbacks

• condition: .env file does not exist | action: create .env and .env.example and add .env to .gitignore before extracting secrets
• condition: .gitignore does not exist | action: create .gitignore with .env entry before remediation
• condition: language detection fails for env var pattern | action: extract secret to .env but flag source file refactoring as MANUAL_INTERVENTION_NEEDED
• condition: pre-commit hook already exists | action: append ftm-git scan to existing hook rather than overwriting

Capabilities

• cli: git | required | staged file listing, diff inspection, commit history traversal

Event Payloads

secrets_found

• skill: string — "ftm-git"
• findings_count: number — total secrets detected
• critical_count: number — CRITICAL severity findings
• high_count: number — HIGH severity findings
• files_affected: string[] — files containing secrets
• blocked: boolean — whether commit/push was halted

secrets_clear

• skill: string — "ftm-git"
• files_scanned: number — total files checked
• scope: string — "staged" | "working_tree" | "history" | "pre-push"

secrets_remediated

• skill: string — "ftm-git"
• findings_remediated: number — secrets successfully extracted
• env_vars_added: string[] — environment variable names created
• files_refactored: string[] — source files updated to use env vars
• manual_needed: number — findings requiring manual intervention

task_completed

• skill: string — "ftm-git"
• outcome: string — "clear" | "remediated" | "blocked"
• files_scanned: number — total files scanned
• duration_ms: number — total scan and remediation time

Source: kkudumu/feed-the-machine — distributed by TomeVault.