chore(claude): sync setup-security-tools to canonical

Replaces the older zod-based setup-security-tools with canonical
TypeBox version (sourced from socket-repo-template/template). Key
changes:

  - TypeBox schemas (matches the rest of the fleet's xport pattern)
  - PURL-based AgentShield package spec (pkg:npm/ecc-agentshield@1.4.0)
  - downloadPackage from @socketsecurity/lib/dlx/package — installs
    AgentShield via dlx instead of requiring it as a workspace
    devDep, so consumers don't need ecc-agentshield in
    devDependencies
  - mkdtemp (collision-safe) instead of Date.now()-only naming
  - normalizePath on binary paths
  - parseSchema from @socketsecurity/lib/schema/parse
  - pip3 added to ecosystems lists

The hook's package.json now declares @sinclair/typebox +
@socketregistry/packageurl-js (catalog refs); the new socket-registry
setup action provisions all three zero-dep packages
(@socketsecurity/lib + @socketregistry/packageurl-js +
@sinclair/typebox) via the multi-package bootstrap loop, so a
fresh checkout has them resolvable at hook-load time.

Author: jdalton

.claude/hooks/setup-security-tools/README.md

@@ -5,21 +5,24 @@ Sets up all three Socket security tools for local development in one command.
 ## Tools
 
 ### 1. AgentShield
+
 Scans your Claude Code configuration (`.claude/` directory) for security issues like prompt injection, leaked secrets, and overly permissive tool permissions.
 
-**How it's installed**: Already a devDependency (`ecc-agentshield`). The setup script just verifies it's available — if not, run `pnpm install`.
+**How it's installed**: npm package downloaded via the dlx system (pinned version + integrity hash from `external-tools.json`), cached at `~/.socket/_dlx/`. Subsequent runs reuse the cache. No `devDependencies` entry required in the consumer repo.
 
 ### 2. Zizmor
+
 Static analysis tool for GitHub Actions workflows. Catches unpinned actions, secret exposure, template injection, and permission issues.
 
 **How it's installed**: Binary downloaded from [GitHub releases](https://github.com/zizmorcore/zizmor/releases), SHA-256 verified, cached via the dlx system at `~/.socket/_dlx/`. If you already have it via `brew install zizmor`, the download is skipped.
 
 ### 3. SFW (Socket Firewall)
+
 Intercepts package manager commands (`npm install`, `pnpm add`, etc.) and scans packages against Socket.dev's malware database before installation.
 
 **How it's installed**: Binary downloaded from GitHub, SHA-256 verified, cached via the dlx system at `~/.socket/_dlx/`. Small wrapper scripts ("shims") are created at `~/.socket/sfw/shims/` that transparently route commands through the firewall.
 
-**Free vs Enterprise**: If you have a `SOCKET_API_KEY` (in env, `.env`, or `.env.local`), enterprise mode is used with additional ecosystem support (gem, bundler, nuget, go). Otherwise, free mode covers npm, yarn, pnpm, pip, uv, and cargo.
+**Free vs Enterprise**: If you have a `SOCKET_API_KEY` (in env, `.env`, or `.env.local`), enterprise mode is used with additional ecosystem support (gem, bundler, nuget, go). Otherwise, free mode covers npm, yarn, pnpm, pip, pip3, uv, and cargo.
 
 ## How to use
 
@@ -31,16 +34,17 @@ Claude will ask if you have an API key, then run the setup script.
 
 ## What gets installed where
 
-| Tool | Location | Persists across repos? |
-|------|----------|----------------------|
-| AgentShield | `node_modules/.bin/agentshield` | No (per-repo devDep) |
-| Zizmor | `~/.socket/_dlx/<hash>/zizmor` | Yes |
-| SFW binary | `~/.socket/_dlx/<hash>/sfw` | Yes |
-| SFW shims | `~/.socket/sfw/shims/npm`, etc. | Yes |
+| Tool        | Location                      | Persists across repos? |
+| ----------- | ----------------------------- | ---------------------- |
+| AgentShield | `~/.socket/_dlx/<hash>/agentshield` | Yes              |
+| Zizmor      | `~/.socket/_dlx/<hash>/zizmor`      | Yes              |
+| SFW binary  | `~/.socket/_dlx/<hash>/sfw`         | Yes              |
+| SFW shims   | `~/.socket/sfw/shims/npm`, etc.     | Yes              |
 
 ## Pre-push integration
 
 The `.git-hooks/pre-push` hook automatically runs:
+
 - **AgentShield scan** (blocks push on failure)
 - **Zizmor scan** (blocks push on failure)
 
@@ -49,7 +53,8 @@ This means every push is checked — you don't have to remember to run `/securit
 ## Re-running
 
 Safe to run multiple times:
-- AgentShield: just re-checks availability
+
+- AgentShield: skips download if cached binary matches the pinned version
 - Zizmor: skips download if cached binary matches expected version
 - SFW: skips download if cached, only rewrites shims if content changed
 
@@ -58,16 +63,16 @@ Safe to run multiple times:
 Self-contained. To add to another Socket repo:
 
 1. Copy `.claude/hooks/setup-security-tools/` and `.claude/commands/setup-security-tools.md`
-2. Run `cd .claude/hooks/setup-security-tools && npm install`
+2. Ensure the consumer repo has `@socketsecurity/lib`, `@socketregistry/packageurl-js`, and `@sinclair/typebox` available (via workspace catalog or direct deps)
 3. Ensure `.claude/hooks/` is not gitignored (add `!/.claude/hooks/` to `.gitignore`)
-4. Ensure `ecc-agentshield` is a devDep in the target repo
+4. Run `pnpm install` in the consumer repo so the hook's workspace deps resolve
 
 ## Troubleshooting
 
-**"AgentShield not found"** — Run `pnpm install`. It's the `ecc-agentshield` devDependency.
+**"AgentShield install failed"** — Check network access to npm registry. The dlx system caches at `~/.socket/_dlx/`; clear the cache (`rm -rf ~/.socket/_dlx/`) to force a fresh download.
 
 **"zizmor found but wrong version"** — The script downloads the expected version via the dlx cache. Your system version (e.g. from brew) will be ignored in favor of the correct version.
 
 **"No supported package managers found"** — SFW only creates shims for package managers found on your PATH. Install npm/pnpm/etc. first.
 
-**SFW shims not intercepting** — Make sure `~/.socket/sfw/shims` is at the *front* of PATH. Run `which npm` — it should point to the shim, not the real binary.
+**SFW shims not intercepting** — Make sure `~/.socket/sfw/shims` is at the _front_ of PATH. Run `which npm` — it should point to the shim, not the real binary.

.claude/hooks/setup-security-tools/external-tools.json

@@ -1,6 +1,11 @@
 {
   "description": "Security tools for Claude Code hooks (self-contained, no external deps)",
   "tools": {
+    "agentshield": {
+      "description": "Claude AI config security scanner (prompt injection, secrets)",
+      "purl": "pkg:npm/ecc-agentshield@1.4.0",
+      "integrity": "sha512-R98OO1Ujyk2lezDLb+iQmMhF6FwTJCHajy3G4FCB6x7wkSTqR9f8+eAelC5KDzYDsGSbc0sOZvjXOOPRBtMpDg=="
+    },
     "zizmor": {
       "description": "GitHub Actions security scanner",
       "version": "1.23.1",
@@ -56,7 +61,7 @@
           "sha256": "c953e62ad7928d4d8f2302f5737884ea1a757babc26bed6a42b9b6b68a5d54af"
         }
       },
-      "ecosystems": ["npm", "yarn", "pnpm", "pip", "uv", "cargo"]
+      "ecosystems": ["npm", "yarn", "pnpm", "pip", "pip3", "uv", "cargo"]
     },
     "sfw-enterprise": {
       "description": "Socket Firewall (enterprise tier)",
@@ -85,7 +90,7 @@
           "sha256": "9a50e1ddaf038138c3f85418dc5df0113bbe6fc884f5abe158beaa9aea18d70a"
         }
       },
-      "ecosystems": ["npm", "yarn", "pnpm", "pip", "uv", "cargo", "gem", "bundler", "nuget"]
+      "ecosystems": ["npm", "yarn", "pnpm", "pip", "pip3", "uv", "cargo", "gem", "bundler", "nuget"]
     }
   }
 }

.claude/hooks/setup-security-tools/index.mts

@@ -3,51 +3,63 @@
 //
 // Configures three tools:
 // 1. AgentShield — scans Claude AI config for prompt injection / secrets.
-//    Already a devDep (ecc-agentshield); this script verifies it's installed.
+//    Downloaded as npm package via dlx (pinned version, cached).
 // 2. Zizmor — static analysis for GitHub Actions workflows. Downloads the
 //    correct binary, verifies SHA-256, cached via the dlx system.
 // 3. SFW (Socket Firewall) — intercepts package manager commands to scan
 //    for malware. Downloads binary, verifies SHA-256, creates PATH shims.
 //    Enterprise vs free determined by SOCKET_API_KEY in env / .env / .env.local.
 
-import { existsSync, readFileSync, promises as fs } from 'node:fs'
+import { existsSync, promises as fs, readFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 
+import { PackageURL } from '@socketregistry/packageurl-js'
+import { Type } from '@sinclair/typebox'
+
 import { whichSync } from '@socketsecurity/lib/bin'
 import { downloadBinary } from '@socketsecurity/lib/dlx/binary'
+import { downloadPackage } from '@socketsecurity/lib/dlx/package'
 import { safeDelete } from '@socketsecurity/lib/fs'
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { normalizePath } from '@socketsecurity/lib/paths/normalize'
 import { getSocketHomePath } from '@socketsecurity/lib/paths/socket'
-import { spawn, spawnSync } from '@socketsecurity/lib/spawn'
-import { z } from 'zod'
+import { spawn } from '@socketsecurity/lib/spawn'
+import { parseSchema } from '@socketsecurity/lib/schema/parse'
 
 const logger = getDefaultLogger()
 
 // ── Tool config loaded from external-tools.json (self-contained) ──
 
-const toolSchema = z.object({
-  description: z.string().optional(),
-  version: z.string(),
-  repository: z.string().optional(),
-  assets: z.record(z.string(), z.string()).optional(),
-  platforms: z.record(z.string(), z.string()).optional(),
-  checksums: z.record(z.string(), z.string()).optional(),
-  ecosystems: z.array(z.string()).optional(),
+const checksumEntrySchema = Type.Object({
+  asset: Type.String(),
+  sha256: Type.String(),
+})
+
+const toolSchema = Type.Object({
+  description: Type.Optional(Type.String()),
+  version: Type.Optional(Type.String()),
+  purl: Type.Optional(Type.String()),
+  integrity: Type.Optional(Type.String()),
+  repository: Type.Optional(Type.String()),
+  release: Type.Optional(Type.String()),
+  checksums: Type.Optional(Type.Record(Type.String(), checksumEntrySchema)),
+  ecosystems: Type.Optional(Type.Array(Type.String())),
 })
 
-const configSchema = z.object({
-  description: z.string().optional(),
-  tools: z.record(z.string(), toolSchema),
+const configSchema = Type.Object({
+  description: Type.Optional(Type.String()),
+  tools: Type.Record(Type.String(), toolSchema),
 })
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const configPath = path.join(__dirname, 'external-tools.json')
 const rawConfig = JSON.parse(readFileSync(configPath, 'utf8'))
-const config = configSchema.parse(rawConfig)
+const config = parseSchema(configSchema, rawConfig)
 
+const AGENTSHIELD = config.tools['agentshield']!
 const ZIZMOR = config.tools['zizmor']!
 const SFW_FREE = config.tools['sfw-free']!
 const SFW_ENTERPRISE = config.tools['sfw-enterprise']!
@@ -79,19 +91,37 @@ function findApiKey(): string | undefined {
 
 // ── AgentShield ──
 
-function setupAgentShield(): boolean {
+async function setupAgentShield(): Promise<boolean> {
   logger.log('=== AgentShield ===')
-  const bin = whichSync('agentshield', { nothrow: true })
-  if (bin && typeof bin === 'string') {
-    const result = spawnSync(bin, ['--version'], { stdio: 'pipe' })
+  const purl = PackageURL.fromString(AGENTSHIELD.purl!)
+  if (purl.type !== 'npm') {
+    throw new Error(`Unsupported PURL type "${purl.type}" — only npm is supported`)
+  }
+  const npmPackage = purl.namespace ? `${purl.namespace}/${purl.name}` : purl.name!
+  const version = AGENTSHIELD.version ?? purl.version
+  const packageSpec = version ? `${npmPackage}@${version}` : npmPackage
+
+  logger.log(`Installing ${packageSpec} via dlx...`)
+  const { binaryPath, installed } = await downloadPackage({
+    package: packageSpec,
+    binaryName: 'agentshield',
+  })
+
+  // Verify version matches pinned config.
+  if (version) {
+    const result = await spawn(binaryPath, ['--version'], { stdio: 'pipe' })
     const ver = typeof result.stdout === 'string'
       ? result.stdout.trim()
       : result.stdout.toString().trim()
-    logger.log(`Found: ${bin} (${ver})`)
-    return true
+    if (!ver.includes(version)) {
+      logger.warn(`Version mismatch: expected ${version}, got ${ver}`)
+      return false
+    }
+    logger.log(installed ? `Installed: ${binaryPath} (${ver})` : `Cached: ${binaryPath} (${ver})`)
+  } else {
+    logger.log(installed ? `Installed: ${binaryPath}` : `Cached: ${binaryPath}`)
   }
-  logger.warn('Not found. Run "pnpm install" to install ecc-agentshield.')
-  return false
+  return true
 }
 
 // ── Zizmor ──
@@ -148,8 +178,8 @@ async function setupZizmor(): Promise<boolean> {
   }
 
   const isZip = asset.endsWith('.zip')
-  const extractDir = path.join(tmpdir(), `zizmor-extract-${Date.now()}`)
-  await fs.mkdir(extractDir, { recursive: true })
+  // mkdtemp is collision-safe, unlike Date.now()-only naming.
+  const extractDir = await fs.mkdtemp(path.join(tmpdir(), 'zizmor-extract-'))
   try {
     if (isZip) {
       await spawn('powershell', ['-NoProfile', '-Command',
@@ -195,6 +225,7 @@ async function setupSfw(apiKey: string | undefined): Promise<boolean> {
 
   // Create shims.
   const isWindows = process.platform === 'win32'
+
   const shimDir = path.join(getSocketHomePath(), 'sfw', 'shims')
   await fs.mkdir(shimDir, { recursive: true })
   const ecosystems = [...(sfwConfig.ecosystems ?? [])]
@@ -203,12 +234,14 @@ async function setupSfw(apiKey: string | undefined): Promise<boolean> {
   }
   const cleanPath = (process.env['PATH'] ?? '').split(path.delimiter)
     .filter(p => p !== shimDir).join(path.delimiter)
+  const sfwBin = normalizePath(binaryPath)
   const created: string[] = []
   for (const cmd of ecosystems) {
-    const realBin = whichSync(cmd, { nothrow: true, path: cleanPath })
+    let realBin = whichSync(cmd, { nothrow: true, path: cleanPath })
     if (!realBin || typeof realBin !== 'string') continue
+    realBin = normalizePath(realBin)
 
-    // Bash shim (macOS/Linux).
+    // Bash shim (macOS/Linux/Windows Git Bash).
     const bashLines = [
       '#!/bin/bash',
       `export PATH="$(echo "$PATH" | tr ':' '\\n' | grep -vxF '${shimDir}' | paste -sd: -)"`,
@@ -227,7 +260,7 @@ async function setupSfw(apiKey: string | undefined): Promise<boolean> {
         'fi',
       )
     }
-    bashLines.push(`exec "${binaryPath}" "${realBin}" "$@"`)
+    bashLines.push(`exec "${sfwBin}" "${realBin}" "$@"`)
     const bashContent = bashLines.join('\n') + '\n'
     const bashPath = path.join(shimDir, cmd)
     if (!existsSync(bashPath) || await fs.readFile(bashPath, 'utf8').catch(() => '') !== bashContent) {
@@ -257,7 +290,7 @@ async function setupSfw(apiKey: string | undefined): Promise<boolean> {
         + `set "PATH=%PATH:;${shimDir};=%"\r\n`
         + `set "PATH=%PATH:~1,-1%"\r\n`
         + cmdApiKeyBlock
-        + `"${binaryPath}" "${realBin}" %*\r\n`
+        + `"${sfwBin}" "${realBin}" %*\r\n`
       const cmdPath = path.join(shimDir, `${cmd}.cmd`)
       if (!existsSync(cmdPath) || await fs.readFile(cmdPath, 'utf8').catch(() => '') !== cmdContent) {
         await fs.writeFile(cmdPath, cmdContent)
@@ -282,7 +315,7 @@ async function main(): Promise<void> {
 
   const apiKey = findApiKey()
 
-  const agentshieldOk = setupAgentShield()
+  const agentshieldOk = await setupAgentShield()
   logger.log('')
   const zizmorOk = await setupZizmor()
   logger.log('')

.claude/hooks/setup-security-tools/package.json

@@ -4,6 +4,8 @@
   "type": "module",
   "main": "./index.mts",
   "dependencies": {
+    "@sinclair/typebox": "catalog:",
+    "@socketregistry/packageurl-js": "catalog:",
     "@socketsecurity/lib": "catalog:"
   }
 }