@torus-engineering/tas-kit 1.8.0 → 1.10.0

package/.tas/hooks/README.md

@@ -0,0 +1,138 @@
+# TAS Kit — Pre-commit Security Hook
+
+Fast, deterministic scan of staged files on every `git commit`. Blocks commits
+that contain hardcoded secrets, private keys, `.env` files, or (optionally)
+findings from a deeper AI-powered audit.
+
+## Files
+
+| File | Role |
+|---|---|
+| `security-scan.js` | Vanilla Node scanner. No runtime deps. Reads `tas.yaml` for config. |
+| `pre-commit` | Shell wrapper invoked by git. Calls the scanner via `node`. |
+| `README.md` | This file. |
+
+## How it gets wired
+
+The installer offers two modes during `npx @torus-engineering/tas-kit install`:
+
+### 1. Husky mode (recommended for Node/TS projects)
+
+Adds `husky` to devDependencies, sets a `"prepare": "husky"` script, and creates
+`.husky/pre-commit` that sources `.tas/hooks/pre-commit`. The hook is shared
+across the team via git — anyone cloning the repo gets it after `npm install`.
+
+### 2. Native mode (works for any stack)
+
+Copies `.tas/hooks/pre-commit` directly into `.git/hooks/pre-commit` (and
+`chmod +x` on Unix). Local to each clone — each teammate has to re-run the
+installer or copy the hook themselves. Zero Node dependency added.
+
+### 3. Skip
+
+No hook wiring. You can always run `/tas-security --staged` manually, or wire
+it later by re-running the installer.
+
+## 3-Tier Scan
+
+| Tier | When | What runs | Blocks? | Cost |
+|---|---|---|---|---|
+| 1 | Always | Built-in regex on staged files (~45 secret patterns) | Yes, if severity ∈ `block_on` | < 1s |
+| 2 | If tool on PATH | `gitleaks` or `trufflehog` — community-maintained rules | Yes, if severity ∈ `block_on` | 2–10s |
+| 3 | Opt-in, **local only** | AI deep scan via `claude` / `codex` / `gemini`, writes `docs/security-report.md` | **No — report-only** | 15–60s |
+
+**Tier 1 & 2** are the hard gate — they stop obvious credential leaks on every
+commit.
+
+**Tier 3** is optional and local-only. It's designed for devs who want a
+second-opinion AI review before pushing. Uses your personal Claude Code (or
+Codex / Gemini) subscription — no per-call API charges because quota resets
+on a rolling window. Output goes to `docs/security-report.md`; if you want
+reviewers to see it, `git add` it into your commit. This tier is deliberately
+NOT wired into CI — running it there would burn paid API tokens, and PR
+review already gives humans a chance to catch issues.
+
+## Config (in `tas.yaml`)
+
+```yaml
+security:
+  pre_commit_hook: true         # false → disable hook without uninstalling
+  external_scanner: auto        # auto | gitleaks | trufflehog | none — tier 2
+  tool: claude                  # claude | codex | gemini | none — tier 3 AI
+  deep_scan_on_every_commit: false
+  block_on: [critical, high]
+  allow_bypass: true
+```
+
+- **pre_commit_hook** — master switch. `false` → scanner exits early.
+- **external_scanner** — tier 2 control.
+  - `auto` (default) → try `gitleaks` first, then `trufflehog`. Silent skip if
+    neither is on PATH. Zero cost when not installed.
+  - `gitleaks` / `trufflehog` → force that specific tool; warn if missing.
+  - `none` → disable tier 2 entirely.
+- **tool** — tier 3 AI CLI. Must be on `PATH` when deep scan is triggered.
+- **deep_scan_on_every_commit** — `false` = skip tier 3 locally (default).
+  `true` = also invoke `tool` on the staged diff every commit (slow).
+- **block_on** — severities that cause exit code 1. Medium/Low always pass.
+- **allow_bypass** — cosmetic: when `true`, scanner prints bypass hints.
+  Git always honors `--no-verify` regardless.
+
+## Installing tier 2 scanners (optional)
+
+**gitleaks** — fastest, purpose-built for pre-commit:
+- Windows: `scoop install gitleaks` or download binary from releases
+- macOS: `brew install gitleaks`
+- Linux: `brew install gitleaks` or apt/download
+
+**trufflehog** — slower but can verify secrets against live APIs:
+- Windows: `scoop install trufflehog`
+- macOS: `brew install trufflehog`
+- Linux: `curl -sSfL https://raw.githubusercontent.com/trufflesecurity/trufflehog/main/scripts/install.sh | sh -s -- -b /usr/local/bin`
+
+No action needed if you don't want tier 2 — the hook silently skips it.
+
+## Behavior on CI
+
+If `CI=true` (or `CI=1`) is in the environment, the scanner force-enables
+deep scan regardless of `deep_scan_on_every_commit`. This lets CI gates run
+the full AI audit even when local commits stay fast.
+
+## Bypass
+
+```
+SKIP_SECURITY_SCAN=1 git commit -m "..."
+git commit --no-verify -m "..."
+```
+
+Document the reason in the commit body when bypassing.
+
+## What the fast scan catches
+
+- AWS access keys (`AKIA...`)
+- GitHub / Slack / Google API tokens
+- Private keys (RSA, OpenSSH, EC, DSA, PGP)
+- Hardcoded secrets: `api_key|secret|password|token = "..."` patterns
+- JWTs embedded in source
+- DB connection strings with credentials
+- `.env` files staged (except `.env.example` / `.sample` / `.template`)
+
+Binary files, large files (>2MB), and common asset extensions are skipped.
+
+## What deep scan catches (when enabled)
+
+OWASP Top 10, injection, authz flaws, unsafe deserialization — whatever the
+configured AI CLI reports. Output must follow the grep-friendly format:
+
+```
+<SEVERITY> | <file:line> | <description>
+```
+
+Anything not in that format is ignored. If the tool reports `NO FINDINGS`,
+scan passes.
+
+## Extending
+
+- **Add a pattern:** edit `PATTERNS` array in `security-scan.js`.
+- **Change tool invocation:** edit the `tools` map (bin + args).
+- **Report findings to `docs/security-report.md`:** not done by default.
+  Use `/tas-security` command for a proper run that writes the report.

package/.tas/hooks/pre-commit

@@ -0,0 +1,26 @@
+#!/bin/sh
+# TAS Kit — pre-commit security hook
+#
+# Invoked by either:
+#   - husky (.husky/pre-commit sources this file), or
+#   - native git hook (.git/hooks/pre-commit is a copy of this file)
+#
+# Delegates to .tas/hooks/security-scan.js. Exits 0 if ok, 1 to block commit.
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "[TAS Security] node not found on PATH — skipping scan" >&2
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+SCANNER="$REPO_ROOT/.tas/hooks/security-scan.js"
+if [ ! -f "$SCANNER" ]; then
+  echo "[TAS Security] Scanner not found at $SCANNER — did you run 'npx @torus-engineering/tas-kit install'?" >&2
+  exit 0
+fi
+
+exec node "$SCANNER"