Add optional Claude Code hook for blocking malicious packages

Adds a PreToolUse hook (socket-gate.ts) that intercepts npm/yarn/bun/pnpm
install commands and checks packages against the Socket API. Blocks packages
with critical or high severity alerts (typosquats, malware, supply chain
attacks). Fails open on all errors.

Includes tests and README documentation.

Author: dc-larsen

README.md

@@ -223,6 +223,67 @@ This approach automatically uses the latest version without requiring global ins
    }
    ```
 
+## Claude Code Hook (Optional)
+
+The repo includes an optional [Claude Code hook](https://code.claude.com/docs/en/hooks) that automatically blocks malicious packages before installation. When Claude Code runs `npm install`, `yarn add`, `bun add`, or `pnpm add`, the hook checks the package against Socket and blocks it if critical or high severity alerts are found (typosquats, malware, supply chain attacks).
+
+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).
+
+1. Copy the hook script:
+
+```bash
+mkdir -p ~/.claude/hooks
+cp hooks/socket-gate.ts ~/.claude/hooks/
+```
+
+2. Add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SOCKET_API_KEY=your-api-key-here node --experimental-strip-types ~/.claude/hooks/socket-gate.ts"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If `SOCKET_API_KEY` is already in your shell environment, you can omit it from the command.
+
+### How it works
+
+| Alert Severity | Decision | Example |
+|----------------|----------|---------|
+| **Critical** | Block installation | `browserlist` (typosquat of `browserslist`) |
+| **High** | Block installation | Packages with known supply chain risks |
+| **Low/None** | Allow | `express`, `lodash`, `react` |
+
+### Testing the hook
+
+```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
+
+# 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
+```
+
+Inspired by [Jimmy Vo's dependency hook](https://blog.jimmyvo.com/posts/claudes-dependency-hook/).
+
 ## Tools exposed by the Socket MCP Server
 
 ### depscore

hooks/socket-gate.test.ts

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { test } from 'node:test'
+import assert from 'node:assert'
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+
+const hookPath = join(import.meta.dirname, 'socket-gate.ts')
+
+function runHook (input: string, env?: Record<string, string>): string {
+  return execFileSync('node', ['--experimental-strip-types', hookPath], {
+    input,
+    encoding: 'utf-8',
+    timeout: 30_000,
+    env: {
+      ...process.env,
+      ...env
+    }
+  }).trim()
+}
+
+function parseOutput (output: string): { decision: string, reason?: string } {
+  const parsed = JSON.parse(output)
+  return {
+    decision: parsed.hookSpecificOutput.permissionDecision,
+    reason: parsed.hookSpecificOutput.permissionDecisionReason
+  }
+}
+
+function makeInput (command: string): string {
+  return JSON.stringify({
+    session_id: 'test',
+    tool_name: 'Bash',
+    tool_input: { command }
+  })
+}
+
+test('socket-gate hook', async (t) => {
+  const apiKey = process.env['SOCKET_API_KEY']
+
+  // ========================================
+  // Unit tests (no API key required)
+  // ========================================
+
+  await t.test('allows non-Bash tools', () => {
+    const input = JSON.stringify({ session_id: 'test', tool_name: 'Read', tool_input: { path: '/tmp/foo' } })
+    const result = parseOutput(runHook(input))
+    assert.strictEqual(result.decision, 'allow')
+  })
+
+  await t.test('allows non-install commands', () => {
+    const result = parseOutput(runHook(makeInput('ls -la')))
+    assert.strictEqual(result.decision, 'allow')
+  })
+
+  await t.test('allows lockfile-only installs', () => {
+    for (const cmd of ['npm install', 'npm i', 'npm ci', 'yarn', 'yarn install', 'bun install', 'pnpm install']) {
+      const result = parseOutput(runHook(makeInput(cmd)))
+      assert.strictEqual(result.decision, 'allow', `should allow: ${cmd}`)
+    }
+  })
+
+  await t.test('allows empty input', () => {
+    const result = parseOutput(runHook(''))
+    assert.strictEqual(result.decision, 'allow')
+  })
+
+  await t.test('allows invalid JSON', () => {
+    const result = parseOutput(runHook('not json'))
+    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)
+  // ========================================
+
+  await t.test('allows safe package (lodash)', { skip: !apiKey && 'SOCKET_API_KEY not set' }, () => {
+    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' }, () => {
+    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' }, () => {
+    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' }, () => {
+    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' }, () => {
+    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' }, () => {
+    const result = parseOutput(runHook(makeInput('bun add express')))
+    assert.strictEqual(result.decision, 'allow')
+  })
+})