Switch hook from direct API to Socket CLI (no API key needed)

Uses 'socket package score' instead of calling the /v0/purl endpoint
directly. Auth is handled by the CLI's own config (socket login), so
no SOCKET_API_KEY env var is required.

Author: dc-larsen

README.md

@@ -231,7 +231,10 @@ The hook fails open on all errors, so it never blocks legitimate work.
 
 ### Hook Setup
 
-**Prerequisites:** Node.js 22+ and a [Socket API key](https://docs.socket.dev/reference/creating-and-managing-api-tokens) (`packages:list` scope).
+**Prerequisites:**
+- Node.js 22+
+- [Socket CLI](https://www.npmjs.com/package/@socketsecurity/cli): `npm install -g @socketsecurity/cli`
+- Run `socket login` to authenticate (one-time setup, no env vars needed)
 
 1. Copy the hook script:
 
@@ -251,7 +254,7 @@ cp hooks/socket-gate.ts ~/.claude/hooks/
         "hooks": [
           {
             "type": "command",
-            "command": "SOCKET_API_KEY=your-api-key-here node --experimental-strip-types ~/.claude/hooks/socket-gate.ts"
+            "command": "node --experimental-strip-types ~/.claude/hooks/socket-gate.ts"
           }
         ]
       }
@@ -260,8 +263,6 @@ cp hooks/socket-gate.ts ~/.claude/hooks/
 }
 ```
 
-If `SOCKET_API_KEY` is already in your shell environment, you can omit it from the command.
-
 ### How it works
 
 | Alert Severity | Decision | Example |
@@ -275,11 +276,11 @@ If `SOCKET_API_KEY` is already in your shell environment, you can omit it from t
 ```bash
 # Should block (typosquat)
 echo '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"npm install browserlist"}}' \
-  | SOCKET_API_KEY=your-key node --experimental-strip-types hooks/socket-gate.ts
+  | node --experimental-strip-types hooks/socket-gate.ts
 
 # Should allow (safe package)
 echo '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"npm install express"}}' \
-  | SOCKET_API_KEY=your-key node --experimental-strip-types hooks/socket-gate.ts
+  | node --experimental-strip-types hooks/socket-gate.ts
 ```
 
 Inspired by [Jimmy Vo's dependency hook](https://blog.jimmyvo.com/posts/claudes-dependency-hook/).

hooks/socket-gate.test.ts

@@ -6,15 +6,12 @@ import { join } from 'node:path'
 
 const hookPath = join(import.meta.dirname, 'socket-gate.ts')
 
-function runHook (input: string, env?: Record<string, string>): string {
+function runHook (input: string): string {
   return execFileSync('node', ['--experimental-strip-types', hookPath], {
     input,
     encoding: 'utf-8',
-    timeout: 30_000,
-    env: {
-      ...process.env,
-      ...env
-    }
+    timeout: 60_000,
+    env: { ...process.env }
   }).trim()
 }
 
@@ -34,11 +31,20 @@ function makeInput (command: string): string {
   })
 }
 
-test('socket-gate hook', async (t) => {
-  const apiKey = process.env['SOCKET_API_KEY']
+function socketCliAvailable (): boolean {
+  try {
+    execFileSync('which', ['socket'], { encoding: 'utf-8', timeout: 5_000 })
+    return true
+  } catch {
+    return false
+  }
+}
+
+const hasCli = socketCliAvailable()
 
+test('socket-gate hook', async (t) => {
   // ========================================
-  // Unit tests (no API key required)
+  // Unit tests (no Socket CLI required)
   // ========================================
 
   await t.test('allows non-Bash tools', () => {
@@ -69,43 +75,38 @@ test('socket-gate hook', async (t) => {
     assert.strictEqual(result.decision, 'allow')
   })
 
-  await t.test('allows when no API key is set', () => {
-    const result = parseOutput(runHook(makeInput('npm install malicious-pkg'), { SOCKET_API_KEY: '' }))
-    assert.strictEqual(result.decision, 'allow')
-  })
-
   // ========================================
-  // Integration tests (require SOCKET_API_KEY)
+  // Integration tests (require Socket CLI with `socket login`)
   // ========================================
 
-  await t.test('allows safe package (lodash)', { skip: !apiKey && 'SOCKET_API_KEY not set' }, () => {
+  await t.test('allows safe package (lodash)', { skip: !hasCli && 'Socket CLI not installed' }, () => {
     const result = parseOutput(runHook(makeInput('npm install lodash')))
     assert.strictEqual(result.decision, 'allow')
   })
 
-  await t.test('allows safe scoped package (@types/node)', { skip: !apiKey && 'SOCKET_API_KEY not set' }, () => {
+  await t.test('allows safe scoped package (@types/node)', { skip: !hasCli && 'Socket CLI not installed' }, () => {
     const result = parseOutput(runHook(makeInput('yarn add @types/node')))
     assert.strictEqual(result.decision, 'allow')
   })
 
-  await t.test('blocks typosquat (browserlist)', { skip: !apiKey && 'SOCKET_API_KEY not set' }, () => {
+  await t.test('blocks typosquat (browserlist)', { skip: !hasCli && 'Socket CLI not installed' }, () => {
     const result = parseOutput(runHook(makeInput('npm install browserlist')))
     assert.strictEqual(result.decision, 'deny')
     assert.ok(result.reason?.includes('browserlist'), 'reason should mention package name')
     assert.ok(result.reason?.includes('socket.dev'), 'reason should include review link')
   })
 
-  await t.test('handles versioned install', { skip: !apiKey && 'SOCKET_API_KEY not set' }, () => {
+  await t.test('handles versioned install', { skip: !hasCli && 'Socket CLI not installed' }, () => {
     const result = parseOutput(runHook(makeInput('npm install express@4.18.2')))
     assert.strictEqual(result.decision, 'allow')
   })
 
-  await t.test('handles pnpm add', { skip: !apiKey && 'SOCKET_API_KEY not set' }, () => {
+  await t.test('handles pnpm add', { skip: !hasCli && 'Socket CLI not installed' }, () => {
     const result = parseOutput(runHook(makeInput('pnpm add express')))
     assert.strictEqual(result.decision, 'allow')
   })
 
-  await t.test('handles bun add', { skip: !apiKey && 'SOCKET_API_KEY not set' }, () => {
+  await t.test('handles bun add', { skip: !hasCli && 'Socket CLI not installed' }, () => {
     const result = parseOutput(runHook(makeInput('bun add express')))
     assert.strictEqual(result.decision, 'allow')
   })

hooks/socket-gate.ts

@@ -3,19 +3,23 @@
  * socket-gate.ts — Claude Code PreToolUse hook
  *
  * Intercepts npm/yarn/bun/pnpm install commands and checks packages against
- * the Socket API. Blocks packages with critical alerts (malware, typosquats)
- * and warns on high severity supply chain risks.
+ * Socket. Blocks packages with critical alerts (malware, typosquats)
+ * and high severity supply chain risks.
+ *
+ * Uses the Socket CLI (`socket package score`) which handles its own auth
+ * via `socket login`. No API key env var needed.
  *
  * Setup:
- *   1. Copy this file to ~/.claude/hooks/socket-gate.ts
- *   2. Add to ~/.claude/settings.json (see README)
- *   3. Set SOCKET_API_KEY env var
+ *   1. Install Socket CLI: npm install -g @socketsecurity/cli && socket login
+ *   2. Copy this file to ~/.claude/hooks/socket-gate.ts
+ *   3. Add to ~/.claude/settings.json (see README)
  *
- * Fails open on all errors (network, auth, parse) so it never blocks
- * legitimate work.
+ * Fails open on all errors (CLI missing, network timeout, parse failures)
+ * so it never blocks legitimate work.
  */
 
 import { readFileSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
 
 // ========================================
 // Types
@@ -28,21 +32,18 @@ interface HookInput {
 }
 
 interface SocketAlert {
-  type: string
+  name: string
   severity: string
   category?: string
-  props?: Record<string, unknown>
 }
 
-interface PurlResponseLine {
-  _type?: string
-  score?: Record<string, unknown>
-  alerts?: SocketAlert[]
-  name?: string
-  namespace?: string
-  type?: string
-  version?: string
-  [key: string]: unknown
+interface SocketScoreResult {
+  ok?: boolean
+  data?: {
+    self?: {
+      alerts?: SocketAlert[]
+    }
+  }
 }
 
 // ========================================
@@ -104,75 +105,34 @@ export function extractPackageName (command: string): string | null {
 }
 
 // ========================================
-// PURL construction (npm only, inline)
-// ========================================
-
-export function buildNpmPurl (packageName: string): string {
-  if (packageName.startsWith('@') && packageName.includes('/')) {
-    const slash = packageName.indexOf('/')
-    const scope = encodeURIComponent(packageName.slice(0, slash))
-    const name = packageName.slice(slash + 1)
-    return `pkg:npm/${scope}/${name}`
-  }
-  return `pkg:npm/${packageName}`
-}
-
-// ========================================
-// Socket API
+// Socket CLI
 // ========================================
 
-const DEFAULT_SOCKET_API_URL = 'https://api.socket.dev/v0/purl'
-
-function getSocketApiUrl (): string {
-  if (process.env['SOCKET_API_URL']) {
-    return process.env['SOCKET_API_URL']
+function isSocketInstalled (): boolean {
+  try {
+    execFileSync('which', ['socket'], { encoding: 'utf-8', timeout: 5_000 })
+    return true
+  } catch {
+    return false
   }
-  return `${DEFAULT_SOCKET_API_URL}?alerts=true&compact=false&fixable=false&licenseattrib=false&licensedetails=false`
 }
 
-export async function checkPackage (packageName: string, apiKey: string): Promise<{ decision: 'allow' | 'deny', reason: string }> {
-  const purl = buildNpmPurl(packageName)
-
-  const response = await fetch(getSocketApiUrl(), {
-    method: 'POST',
-    headers: {
-      'user-agent': 'socket-mcp-hook/1.0',
-      accept: 'application/x-ndjson',
-      'content-type': 'application/json',
-      authorization: `Bearer ${apiKey}`
-    },
-    body: JSON.stringify({ components: [{ purl }] }),
-    signal: AbortSignal.timeout(15_000)
-  })
-
-  if (!response.ok) {
-    return { decision: 'allow', reason: '' }
-  }
-
-  const text = await response.text()
-  if (!text.trim()) {
-    return { decision: 'allow', reason: '' }
-  }
-
-  const lines: PurlResponseLine[] = text
-    .split('\n')
-    .filter(line => line.trim())
-    .map(line => JSON.parse(line) as PurlResponseLine)
-    .filter(obj => !obj._type)
-
-  if (lines.length === 0) {
-    return { decision: 'allow', reason: '' }
-  }
+export function checkPackage (packageName: string): { decision: 'allow' | 'deny', reason: string } {
+  const result = execFileSync(
+    'socket',
+    ['package', 'score', 'npm', packageName, '--json', '--no-banner'],
+    { encoding: 'utf-8', timeout: 30_000, maxBuffer: 10 * 1024 * 1024 }
+  )
 
-  const pkg = lines[0]
-  const alerts = pkg.alerts || []
+  const parsed: SocketScoreResult = JSON.parse(result)
+  const alerts = parsed.data?.self?.alerts || []
 
   const critical = alerts.filter(a => a.severity === 'critical')
   const high = alerts.filter(a => a.severity === 'high')
 
   if (critical.length > 0) {
     const details = critical
-      .map(a => `  - ${a.type}: ${a.category || 'detected'}`)
+      .map(a => `  - ${a.name}: ${a.category || 'detected'}`)
       .join('\n')
 
     return {
@@ -183,7 +143,7 @@ export async function checkPackage (packageName: string, apiKey: string): Promis
 
   if (high.length > 0) {
     const details = high
-      .map(a => `  - ${a.type}: ${a.category || 'detected'}`)
+      .map(a => `  - ${a.name}: ${a.category || 'detected'}`)
       .join('\n')
 
     return {
@@ -241,20 +201,21 @@ async function main (): Promise<void> {
     return
   }
 
-  const apiKey = process.env['SOCKET_API_KEY']
-  if (!apiKey) {
+  if (!isSocketInstalled()) {
+    // CLI not installed, fail open
     outputAllow()
     return
   }
 
   try {
-    const result = await checkPackage(packageName, apiKey)
+    const result = checkPackage(packageName)
     if (result.decision === 'deny') {
       outputDeny(result.reason)
     } else {
       outputAllow()
     }
   } catch {
+    // Fail open on any error
     outputAllow()
   }
 }