# 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.