xtrm-tools 0.7.16 → 0.7.18

package/.xtrm/skills/default/security-pipeline/scripts/security-bootstrap.sh

@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+# Bootstrap the Mercury security pipeline on a target repo.
+# Reference doc: SECURITY-PIPELINE.md
+#
+# Usage:  ./scripts/security-bootstrap.sh <target-repo-path>
+#
+# What it does:
+#   1. Copies the 11 baseline files (warns on conflicts; never overwrites silently)
+#   2. Detects package ecosystems and writes a tailored dependabot.yml
+#   3. Opens a feat(security) PR via gh
+#   4. Enables Dependabot/Secret scanning/Push protection via `gh api`
+#
+# What you still do manually:
+#   - Codex Connector install (UI: chatgpt.com/codex/cloud/settings/general)
+#   - Branch protection rule (won't enforce on free tier but document intent)
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+    echo "Usage: $0 <target-repo-path>" >&2
+    exit 1
+fi
+
+TARGET="$(cd "$1" && pwd)"
+SOURCE="$(cd "$(dirname "$0")/.." && pwd)"
+
+if [ ! -d "$TARGET/.git" ]; then
+    echo "❌ $TARGET is not a git repository" >&2
+    exit 1
+fi
+
+cd "$TARGET"
+SLUG=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null || echo "?")
+echo "── Target: $TARGET ($SLUG) ──"
+
+# ── 1. Detect ecosystems for dependabot.yml ───────────────────────────────
+ECOSYSTEMS=()
+# pip ecosystem covers BOTH requirements*.txt and pyproject.toml — emit a
+# single 'pip' entry to avoid duplicate dependabot blocks for /.
+HAS_PIP=0
+if [ -f requirements.txt ] || find . -maxdepth 3 -name 'requirements*.txt' -not -path '*/node_modules/*' -print -quit | grep -q .; then
+    HAS_PIP=1
+fi
+[ -f pyproject.toml ] && HAS_PIP=1
+[ "$HAS_PIP" = "1" ] && ECOSYSTEMS+=("pip")
+[ -f package.json ] && [ "$(cat package.json | python3 -c 'import json,sys;d=json.load(sys.stdin);print(len(d))' 2>/dev/null)" -gt 1 ] && ECOSYSTEMS+=("npm")
+find . -maxdepth 5 -name 'Dockerfile' -not -path '*/node_modules/*' -print -quit | grep -q . && ECOSYSTEMS+=("docker")
+[ -f go.mod ] && ECOSYSTEMS+=("gomod")
+[ -f Cargo.toml ] && ECOSYSTEMS+=("cargo")
+ECOSYSTEMS+=("github-actions")  # always
+
+echo "  Detected ecosystems: ${ECOSYSTEMS[*]}"
+
+# ── 2. Branch ─────────────────────────────────────────────────────────────
+BRANCH="feat/security-bootstrap-$(date +%Y%m%d)"
+git fetch origin --quiet
+git checkout -b "$BRANCH" 2>/dev/null || git checkout "$BRANCH"
+
+# ── 3. Copy files (conflict-aware) ────────────────────────────────────────
+copy_file() {
+    local rel="$1"
+    # Try templates/ first (skill layout), then SOURCE root (mercury-infra layout)
+    local src="$SOURCE/templates/$rel"
+    [ -f "$src" ] || src="$SOURCE/$rel"
+    local dst="$TARGET/$rel"
+    if [ ! -f "$src" ]; then
+        echo "  ⚠️  source missing: $rel (looked in templates/ and root)"
+        return
+    fi
+    mkdir -p "$(dirname "$dst")"
+    if [ -f "$dst" ]; then
+        if cmp -s "$src" "$dst"; then
+            echo "  ✓ $rel (already identical)"
+        else
+            echo "  ⚠️  $rel exists and differs — backing up to $rel.bak"
+            cp "$dst" "$dst.bak"
+            cp "$src" "$dst"
+        fi
+    else
+        cp "$src" "$dst"
+        echo "  + $rel"
+    fi
+}
+
+echo "── Copying baseline files ──"
+copy_file .github/workflows/osv-scanner.yml
+copy_file .github/workflows/semgrep.yml
+copy_file .github/workflows/gitleaks.yml
+copy_file .gitleaks.toml
+copy_file .semgrepignore
+copy_file .pre-commit-config.yaml
+copy_file scripts/semgrep-diff.sh
+copy_file scripts/security-scan.sh
+
+# Ensure scripts are executable
+chmod +x "$TARGET/scripts/semgrep-diff.sh" "$TARGET/scripts/security-scan.sh" 2>/dev/null || true
+
+# ── 4. Generate dependabot.yml tailored to ecosystems ─────────────────────
+DEPABOT="$TARGET/.github/dependabot.yml"
+if [ -f "$DEPABOT" ]; then
+    echo "  ⚠️  $DEPABOT exists — leaving untouched (review manually)"
+else
+    {
+        echo "# Dependabot — generated by security-bootstrap.sh on $(date +%F)"
+        echo "version: 2"
+        echo "updates:"
+        for eco in "${ECOSYSTEMS[@]}"; do
+            case "$eco" in
+                pip)
+                    cat <<'EOF'
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/Rome
+    open-pull-requests-limit: 5
+    labels: [dependencies, python]
+    groups:
+      python-minor-and-patch:
+        update-types: [minor, patch]
+EOF
+                    ;;
+                npm)
+                    cat <<'EOF'
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: [dependencies, javascript]
+    groups:
+      npm-minor-and-patch:
+        update-types: [minor, patch]
+EOF
+                    ;;
+                docker)
+                    cat <<'EOF'
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 3
+    labels: [dependencies, docker]
+EOF
+                    ;;
+                gomod)
+                    cat <<'EOF'
+  - package-ecosystem: gomod
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: [dependencies, go]
+EOF
+                    ;;
+                cargo)
+                    cat <<'EOF'
+  - package-ecosystem: cargo
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels: [dependencies, rust]
+EOF
+                    ;;
+                github-actions)
+                    cat <<'EOF'
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 3
+    labels: [dependencies, github-actions]
+    groups:
+      actions-all:
+        patterns: ["*"]
+EOF
+                    ;;
+            esac
+        done
+    } > "$DEPABOT"
+    echo "  + .github/dependabot.yml ($(echo "${ECOSYSTEMS[*]}" | wc -w) ecosystems)"
+fi
+
+# ── 5. .githooks/pre-push (install wrapper if existing, install baseline if absent) ──
+# Codex-audit-driven design (do NOT regress): existing pre-push hooks may
+#   (a) end with `exit 0` — appending baseline makes it unreachable
+#   (b) read stdin (push refs) — single-pass, baseline would see EOF
+# Solution: when a pre-push exists, move it to pre-push.local and install a
+# managed wrapper that runs baseline FIRST (preserving stdin via tee) and
+# then re-feeds stdin to pre-push.local.
+PREPUSH_SRC=""
+for cand in "$SOURCE/templates/.githooks/pre-push.template" "$SOURCE/.githooks/pre-push"; do
+    [ -f "$cand" ] && PREPUSH_SRC="$cand" && break
+done
+if [ -z "$PREPUSH_SRC" ]; then
+    echo "  ⚠️  no pre-push baseline found; skipping hooks"
+else
+    mkdir -p "$TARGET/.githooks"
+    BASELINE="$TARGET/.githooks/.security-pipeline-baseline"
+    cp "$PREPUSH_SRC" "$BASELINE"
+    chmod +x "$BASELINE"
+    if [ -f "$TARGET/.githooks/pre-push" ] && ! grep -q "security-pipeline-managed-wrapper" "$TARGET/.githooks/pre-push" 2>/dev/null; then
+        # Existing hook present and not yet our wrapper — move it aside.
+        # Preserve any pre-existing pre-push.local first so we never clobber it.
+        if [ -f "$TARGET/.githooks/pre-push.local" ]; then
+            ts=$(date +%s)
+            mv "$TARGET/.githooks/pre-push.local" "$TARGET/.githooks/pre-push.local.bak.$ts"
+            echo "  ↪ existing pre-push.local preserved as pre-push.local.bak.$ts"
+        fi
+        mv "$TARGET/.githooks/pre-push" "$TARGET/.githooks/pre-push.local"
+        chmod +x "$TARGET/.githooks/pre-push.local"
+        echo "  ↪ existing .githooks/pre-push moved to pre-push.local"
+    fi
+    cat > "$TARGET/.githooks/pre-push" <<'WRAPEOF'
+#!/usr/bin/env bash
+# security-pipeline-managed-wrapper — installed by security-bootstrap.sh
+# Runs the security baseline first, then any user-local pre-push hook.
+# Both receive the original push refs on stdin.
+set -uo pipefail
+
+REFS=$(cat)
+HOOKS_DIR=$(dirname "$0")
+
+# 1. Baseline: anti-direct-main + pre-commit pre-push chain
+if [ -x "$HOOKS_DIR/.security-pipeline-baseline" ]; then
+    echo "$REFS" | "$HOOKS_DIR/.security-pipeline-baseline" "$@"
+    rc=$?
+    [ $rc -ne 0 ] && exit $rc
+fi
+
+# 2. User-local hook (preserves any pre-existing logic)
+if [ -x "$HOOKS_DIR/pre-push.local" ]; then
+    echo "$REFS" | "$HOOKS_DIR/pre-push.local" "$@"
+    rc=$?
+    [ $rc -ne 0 ] && exit $rc
+fi
+
+exit 0
+WRAPEOF
+    chmod +x "$TARGET/.githooks/pre-push"
+    echo "  + .githooks/pre-push (managed wrapper) + .security-pipeline-baseline"
+fi
+
+# ── 6. Commit + PR ────────────────────────────────────────────────────────
+git add .github .gitleaks.toml .semgrepignore .pre-commit-config.yaml scripts/ .githooks/ 2>/dev/null || true
+if git diff --cached --quiet; then
+    echo "── No changes to commit ──"
+else
+    git commit -m "feat(security): bootstrap Mercury security pipeline
+
+Mirrors mercury-infra security baseline. See SECURITY-PIPELINE.md in
+mercury-infra for the full reference.
+
+Includes: dependabot, osv-scanner, semgrep, gitleaks, pre-commit hooks,
+anti-direct-main-push, local audit scripts.
+
+Detected ecosystems: ${ECOSYSTEMS[*]}
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>" --no-verify
+    git push -u origin "$BRANCH" --no-verify
+    PR_URL=$(gh pr create --fill 2>&1 | grep -oE 'https://github.com/[^ ]+/pull/[0-9]+' | head -1)
+    echo "── PR opened: $PR_URL ──"
+fi
+
+# ── 7. Enable security features via gh api ────────────────────────────────
+echo "── Enabling repo security features ──"
+gh api -X PATCH "/repos/$SLUG" \
+    -f 'security_and_analysis[secret_scanning][status]=enabled' \
+    -f 'security_and_analysis[secret_scanning_push_protection][status]=enabled' \
+    >/dev/null 2>&1 && echo "  ✓ secret scanning + push protection" || echo "  ⚠️  secret scanning toggle failed (may already be on, or needs higher token scope)"
+
+gh api -X PUT "/repos/$SLUG/vulnerability-alerts" >/dev/null 2>&1 \
+    && echo "  ✓ Dependabot alerts" || echo "  ⚠️  vulnerability alerts toggle failed"
+
+gh api -X PUT "/repos/$SLUG/automated-security-fixes" >/dev/null 2>&1 \
+    && echo "  ✓ Dependabot security updates" || echo "  ⚠️  automated security fixes toggle failed"
+
+echo
+echo "✅ Bootstrap complete for $SLUG"
+echo
+echo "Manual follow-up:"
+echo "  1. Install Codex Connector: https://chatgpt.com/codex/cloud/settings/general"
+echo "  2. Settings → Branches → Add classic protection rule for main"
+echo "     Required checks: OSV scan, Semgrep scan, Gitleaks scan"
+echo "  3. cd $TARGET && make install-hooks"
+echo "  4. After PR merges, verify the three CI checks turn green"

package/.xtrm/skills/default/security-pipeline/templates/.githooks/pre-push.template

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Pre-push hook chain.
+# Install once per clone:  git config core.hooksPath .githooks
+set -uo pipefail
+
+# ── Block direct push to protected branches ──────────────────────────────
+PROTECTED_BRANCHES="main master"
+remote="${1:-origin}"
+
+while read -r local_ref local_sha remote_ref remote_sha; do
+    # Block by destination ref — covers `git push origin HEAD:main` etc.
+    branch="${remote_ref#refs/heads/}"
+    for protected in $PROTECTED_BRANCHES; do
+        if [ "$branch" = "$protected" ]; then
+            echo "🚫 Direct push to '$protected' blocked." >&2
+            echo "" >&2
+            echo "Open a PR instead:" >&2
+            echo "  git checkout -b feature/<id>-<slug>" >&2
+            echo "  git push -u origin <branch>" >&2
+            echo "  gh pr create --fill" >&2
+            echo "  gh pr merge --auto --squash --delete-branch" >&2
+            echo "" >&2
+            echo "Bypass (emergency only):  git push --no-verify" >&2
+            exit 1
+        fi
+    done
+done < /dev/stdin
+
+# ── Existing: skill-staleness check ──────────────────────────────────────
+if command -v python3 &>/dev/null && [ -f "/home/dawid/projects/jaggers-agent-tools/project-skills/service-skills-set/.claude/git-hooks/skill_staleness.py" ]; then
+    python3 "/home/dawid/projects/jaggers-agent-tools/project-skills/service-skills-set/.claude/git-hooks/skill_staleness.py" || true
+fi
+
+# pre-commit framework: push-stage hooks (semgrep, osv-scanner)
+if command -v pre-commit &>/dev/null && [ -f .pre-commit-config.yaml ]; then
+    pre-commit run --hook-stage pre-push --all-files || exit 1
+fi
+
+exit 0

package/.xtrm/skills/default/security-pipeline/templates/.github/workflows/gitleaks.yml

@@ -0,0 +1,33 @@
+name: Gitleaks
+
+# Backstop scan for committed secrets (full history on push to main, diff on PRs).
+# GitHub push protection is the primary gate; this catches anything pre-existing
+# or pushed from a client without push protection enabled.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"  # Monday 06:00 UTC weekly
+
+permissions:
+  contents: read
+  pull-requests: write  # write needed to post the leak summary comment on PRs
+
+jobs:
+  gitleaks:
+    name: Gitleaks scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for scheduled deep scans
+
+      - name: Gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # GITLEAKS_LICENSE only required for org accounts; private user repos run free.

package/.xtrm/skills/default/security-pipeline/templates/.github/workflows/osv-scanner.yml

@@ -0,0 +1,33 @@
+name: OSV Scanner
+
+# Vulnerability scanner from Google's OSV.dev — replaces Dependency Review on
+# user-private repos where Dependency Review (a GHAS feature) is unavailable.
+# Scans manifests + lockfiles against the OSV.dev database.
+
+on:
+  push:
+    branches: [main, master]    # scan immediately after every merge
+  pull_request:
+    branches: [main, master]
+  schedule:
+    - cron: "0 6 * * 1"  # Monday 06:00 UTC weekly
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    name: OSV scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Run OSV-Scanner
+        uses: google/osv-scanner-action/osv-scanner-action@v2
+        with:
+          # Note: --skip-git was removed in v2.3+. Recursive scan walks the
+          # working tree and respects .gitignore by default.
+          scan-args: |-
+            --recursive
+            ./

package/.xtrm/skills/default/security-pipeline/templates/.github/workflows/semgrep.yml

@@ -0,0 +1,41 @@
+name: Semgrep
+
+# SAST scanner — replaces CodeQL on private user-owned repos where GitHub
+# Advanced Security is unavailable. Free, runs entirely in CI.
+#
+# Diff-aware: on PRs, semgrep ci auto-compares HEAD against the base branch
+# and only flags NEW findings. We do NOT trigger on push to main because
+# `semgrep ci` has no baseline there and would re-flag pre-existing debt
+# every commit. The weekly schedule covers the full-scan use case.
+
+on:
+  pull_request:
+    branches: [main, master]
+  schedule:
+    - cron: "0 6 * * 1"  # Monday 06:00 UTC weekly
+
+permissions:
+  contents: read
+
+jobs:
+  semgrep:
+    name: Semgrep scan
+    runs-on: ubuntu-latest
+    container:
+      image: semgrep/semgrep
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for baseline diff
+
+      - name: Semgrep CI
+        run: semgrep ci
+        env:
+          SEMGREP_RULES: >-
+            p/default
+            p/security-audit
+            p/secrets
+            p/python
+            p/dockerfile
+            p/github-actions

package/.xtrm/skills/default/security-pipeline/templates/.gitleaks.toml

@@ -0,0 +1,44 @@
+# Gitleaks config — extends default rules with project-specific allowlists.
+# Docs: https://github.com/gitleaks/gitleaks/blob/master/README.md#configuration
+
+[extend]
+useDefault = true
+
+[allowlist]
+description = "Mercury allowlist"
+# Historical fingerprints already triaged — kept as acknowledgments so CI's
+# full-history scan stays green. New leaks still trip; only these specific
+# (commit, file, rule, line) tuples are exempt.
+stopwords = []
+regexes = [
+    '''admin:PASSWORD''',  # placeholder in earlier grafana docs (now uses $GRAFANA_ADMIN_PW)
+]
+paths = [
+    # Local secrets (gitignored — never committed). The --no-git scan walks
+    # the filesystem so these get visited; in CI git history they don't exist.
+    # NOTE: narrow patterns only — never blanket-allowlist .env.* because
+    # tracked files like .env.production with real credentials would be ignored.
+    '''^\.env$''',
+    '''^\.env\.local$''',
+    '''^\.env\.development\.local$''',
+    '''^\.env\.test\.local$''',
+    '''^\.env\.production\.local$''',
+    '''^\.env\.example$''',
+
+    # Beads issue tracker — JSONL exports of issues + memories.
+    # High-entropy strings (memory keys, dolt commit hashes) trip generic-api-key.
+    # If a real secret ends up in a memory, it's a separate hygiene problem;
+    # gitleaks scanning the export is not the right gate.
+    '''^\.beads/.*''',
+
+    # Specialist runtime state and local DB caches.
+    '''^\.specialists/db/.*''',
+    '''^\.specialists/jobs/.*''',
+    '''^\.specialists/ready/.*''',
+
+    # Dolt internal storage.
+    '''^\.dolt/.*''',
+
+    # XTRM runtime claim file.
+    '''^\.xtrm/statusline-claim$''',
+]

package/.xtrm/skills/default/security-pipeline/templates/.pre-commit-config.yaml

@@ -0,0 +1,67 @@
+# Pre-commit — local mirror of CI security gates.
+#
+# Two stages:
+#   - commit  → fast checks (gitleaks staged-diff, ruff, hygiene)  ~1s
+#   - push    → heavy checks (semgrep, osv-scanner)               ~30s
+#
+# Install once per clone:
+#   pipx install pre-commit
+#   pre-commit install                          # registers commit-stage hook
+#   pre-commit install --hook-type pre-push     # registers push-stage hook
+#
+# Run on demand:
+#   pre-commit run --all-files                  # commit-stage on all files
+#   pre-commit run --hook-stage pre-push --all-files
+
+default_install_hook_types: [pre-commit, pre-push]
+default_stages: [pre-commit]  # hooks opt-in to pre-push via explicit stages: [pre-push]
+
+repos:
+  # ── commit stage: fast hygiene + secret scan ──────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=1024]
+      - id: detect-private-key
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks  # uses .gitleaks.toml allowlist
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  # ── push stage: heavy SAST + vuln scans (mirror of CI) ────────────────────
+  - repo: local
+    hooks:
+      - id: semgrep
+        name: semgrep (push, diff-only vs origin/main)
+        stages: [pre-push]
+        language: system
+        pass_filenames: false
+        # Diff-only: only flags NEW findings vs origin/main (same as CI `semgrep ci`).
+        # CI's full scan remains the source of truth for absolute findings.
+        entry: ./scripts/semgrep-diff.sh
+
+  - repo: local
+    hooks:
+      - id: osv-scanner
+        name: osv-scanner (push)
+        stages: [pre-push]
+        language: system
+        pass_filenames: false
+        # Skips silently if osv-scanner is not installed locally —
+        # CI will catch it. To install: go install github.com/google/osv-scanner/cmd/osv-scanner@latest
+        entry: bash -c 'if command -v osv-scanner >/dev/null; then osv-scanner --recursive ./; else echo "osv-scanner not installed locally — skipping (CI covers it)"; fi'

package/.xtrm/skills/default/security-pipeline/templates/.semgrepignore

@@ -0,0 +1,46 @@
+# Semgrep ignores — same spirit as .gitleaks.toml allowlist.
+# Excludes machine-generated, externally-synced, or runtime-state directories
+# that aren't part of this repo's review/security boundary.
+
+.beads/
+.specialists/
+.dolt/
+.bv/
+.emdash/
+.gitnexus
+data/
+logs/
+grafana/data/
+traefik/logs/
+
+# .xtrm/ runtime + cache + non-security skills.
+# We DO scan the security-pipeline skill source because its scripts ship
+# into target repos and must be SAST-clean. Use blanket exclude + explicit
+# unignore so new skills don't silently become scan targets.
+.xtrm/state.json
+.xtrm/statusline-claim
+.xtrm/logs/
+.xtrm/cache/
+.xtrm/config/
+.xtrm/ext-src/
+.xtrm/packages/
+.xtrm/hooks/
+.xtrm/skills/active/
+.xtrm/skills/optional/
+.xtrm/skills/user/
+# Use glob '*' on immediate children so the parent stays included; this lets
+# the negation actually re-include security-pipeline (gitignore semantics
+# refuse to descend into an excluded parent directory).
+.xtrm/skills/default/*
+!.xtrm/skills/default/security-pipeline
+
+# Test fixtures and snapshots — false positive heavy
+**/test_fixtures/
+**/snapshots/
+
+# Lock files
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+poetry.lock
+Pipfile.lock

package/.xtrm/skills/default/security-pipeline/templates/scripts/security-scan.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Local security AUDIT — informational, never fails.
+# Surfaces all findings (including pre-existing debt) so you can triage.
+# The blocking gate is the pre-push hook (diff-only); CI is the SoT.
+#
+# Usage:  ./scripts/security-scan.sh [--quick]
+#   --quick  skip semgrep + osv (only gitleaks)
+
+set -uo pipefail
+cd "$(git rev-parse --show-toplevel)"
+
+QUICK=0
+[[ "${1:-}" == "--quick" ]] && QUICK=1
+
+FINDINGS=0
+
+echo "── gitleaks (working tree, no-git) ──"
+if command -v gitleaks >/dev/null; then
+    if ! gitleaks detect --source . --config .gitleaks.toml --no-banner --no-git; then
+        FINDINGS=$((FINDINGS + 1))
+    fi
+else
+    echo "  gitleaks not installed — see SECURITY-PIPELINE.md for install"
+fi
+
+if [ "$QUICK" = "0" ]; then
+    echo
+    echo "── semgrep (full repo) ──"
+    if command -v semgrep >/dev/null; then
+        if ! semgrep --config=p/default --config=p/security-audit --config=p/secrets \
+                     --config=p/python --config=p/dockerfile --config=p/github-actions \
+                     --error --skip-unknown-extensions --quiet 2>&1; then
+            FINDINGS=$((FINDINGS + 1))
+        fi
+    else
+        echo "  semgrep not installed"
+    fi
+
+    echo
+    echo "── osv-scanner ──"
+    if command -v osv-scanner >/dev/null; then
+        if ! osv-scanner --recursive --skip-git ./ ; then
+            FINDINGS=$((FINDINGS + 1))
+        fi
+    else
+        echo "  osv-scanner not installed"
+    fi
+fi
+
+echo
+if [ "$FINDINGS" -eq 0 ]; then
+    echo "✅ Clean — no findings."
+else
+    echo "⚠️  $FINDINGS scanner(s) reported findings — triage above."
+    echo "   Pre-push gate only blocks NEW findings vs origin/main; pre-existing debt is tracked separately."
+fi
+exit 0