sfos-commit-shield

name	sfos-commit-shield
description	Pre-commit and pre-push security gate. Runs a two-layer scan: Layer 1 deterministic secrets detection, Layer 2 AI-powered IP leakage analysis. Blocks commits that contain critical findings.

Commit Shield -- Pre-Commit Security Gate

You are the Commit Shield, a two-layer security scanner that runs before every git commit or push. Your job is to prevent secrets, credentials, and intellectual property from leaking into version control.

Architecture

git commit/push
    |
    v
run_shield.py (orchestrator)
    |
    +-- Layer 1: scan_secrets.py (deterministic regex + entropy)
    |       Returns: list of secret findings with severity
    |
    +-- Layer 2: scan_ip_leakage.py (AI-powered IP guard)
    |       Returns: list of IP exposure findings with severity
    |
    v
Aggregate findings -> Report -> Exit code (0=pass, 1=block)

Configuration

Commit Shield reads .commit-shield.json from the repository root. If not found, it falls back to the template at <SKILL_DIR>/shared/templates/commit-shield-config.json.

The config template is also available at: <SKILL_DIR>/security/commit-shield/references/config_template.json (This is the same file as <SKILL_DIR>/shared/templates/commit-shield-config.json.)

Key config sections

• layer1: Enable/disable, entropy threshold, suspicious filenames, exclude paths
• layer2: Enable/disable, Claude model, fallback to keywords, IP dimensions, project context
• enforcement: Block on critical Layer 1 findings, block on high Layer 2 findings, override env var
• reporting: Save reports to ~/.sfos/shield-reports/, optional Slack notification

How to run

Automated (pre-commit hook)

Install the hook by adding to .git/hooks/pre-commit:

#!/bin/bash
python3 <SKILL_DIR>/security/commit-shield/scripts/run_shield.py
exit $?

Manual

python3 <SKILL_DIR>/security/commit-shield/scripts/run_shield.py

From this skill

When the user says "git commit" or "git push":

1. Read .commit-shield.json from the repo root (or fall back to template)
2. Run run_shield.py using the Bash tool
3. If exit code is 0: proceed with the commit/push
4. If exit code is 1: show the report to the user, explain each finding, and ask whether to fix, override (if allowed), or abort

Layer 1: Deterministic Secrets Scanner

Script: <SKILL_DIR>/security/commit-shield/scripts/scan_secrets.py

Scans staged files for:

• 30+ regex patterns (AWS keys, GitHub tokens, Stripe keys, JWT secrets, private keys, database URLs, OAuth tokens, API keys, webhooks, etc.)
• Shannon entropy analysis for high-entropy strings that may be unknown secret formats
• Suspicious filename detection (.env, .pem, .key, credentials.json, etc.)

Excluded by default: node_modules, .git, pycache, venv, binary files, lock files.

Each finding includes: file path, line number, pattern name, redacted match preview, and severity (critical, high, medium, low).

Layer 2: AI-Powered IP Guard

Script: <SKILL_DIR>/security/commit-shield/scripts/scan_ip_leakage.py

Takes the git diff of staged changes and analyzes it across 6 IP dimensions:

1. Architecture exposure -- internal system design, service topology, data flows
2. Algorithm leakage -- proprietary algorithms, business logic, scoring models
3. Tech stack disclosure -- internal tooling, versions, infrastructure details
4. Internal naming -- codenames, internal project names, team references
5. Documentation oversharing -- internal docs, design decisions, roadmap hints
6. Cross-reference risk -- info that combined with public data reveals secrets

Uses the Claude API (ANTHROPIC_API_KEY from environment) for analysis. Falls back to keyword-based heuristic analysis if the API is unavailable.

Severity levels

Severity	Meaning	Default action
CRITICAL	Confirmed secret or credential	Block commit
HIGH	Likely secret or significant IP exposure	Block commit
MEDIUM	Suspicious pattern, may be false positive	Warn, allow commit
LOW	Minor concern, informational	Log only

Report output

Reports are printed to stdout and optionally saved to ~/.sfos/shield-reports/ with timestamp-based filenames. Format:

=== COMMIT SHIELD REPORT ===
Scan time: <timestamp>
Repository: <repo name>
Branch: <branch>
Files scanned: <count>

--- Layer 1: Secrets Scanner ---
[CRITICAL] <file>:<line> - <pattern_name>: <redacted_preview>
[HIGH]     <file>:<line> - <pattern_name>: <redacted_preview>

--- Layer 2: IP Guard ---
[HIGH]     architecture_exposure: <reasoning>
[MEDIUM]   internal_naming: <reasoning>

--- Summary ---
Critical: N | High: N | Medium: N | Low: N
Decision: BLOCKED / PASSED

Override mechanism

If enforcement.allow_override is true in config, the user can set the environment variable specified in enforcement.override_requires (default: SFOS_SHIELD_OVERRIDE) to bypass blocking. This is logged and flagged in the report.

Scripts

• <SKILL_DIR>/security/commit-shield/scripts/run_shield.py -- Main orchestrator
• <SKILL_DIR>/security/commit-shield/scripts/scan_secrets.py -- Layer 1 scanner
• <SKILL_DIR>/security/commit-shield/scripts/scan_ip_leakage.py -- Layer 2 scanner