feat: implement trust-on-first-use for project hooks and enhance SSRF protection in fetch_url tool

Author: VladoIvankovic

CHANGELOG.md

@@ -11,6 +11,33 @@ For releases before v1.3.35, see [GitHub Releases](https://github.com/VladoIvank
 > as the social-share summary (IFTTT → X/Bluesky), capped at 220 chars.
 > If omitted, the feed falls back to the first paragraph.
 
+## [2.1.3] — 2026-05-22
+
+> Security hardening: project hooks now require trust before they run, the web-fetch tool blocks internal/metadata addresses, and usage stats are sent with your sync token.
+
+### Security
+
+- **Hooks now require trust-on-first-use.** Project-local `.codeep/hooks/*` run
+  arbitrary shell, so a freshly-cloned repo could previously execute its scripts
+  on your first tool call. Hooks in an unapproved workspace are now **skipped**
+  until you run `/hooks trust` (revoke with `/hooks untrust`). `/hooks` and the
+  welcome banner show the trust state. Your own already-set-up projects just need
+  a one-time `/hooks trust`.
+- **SSRF guard on the `fetch_url` web tool.** The agent can no longer be steered
+  (e.g. via prompt injection) into fetching `localhost`, private/RFC1918, or
+  link-local addresses — including the cloud metadata endpoint
+  `169.254.169.254`. Only `http`/`https` are allowed, on the initial request and
+  redirects. Your configured provider endpoints (Ollama, custom vLLM/Tailscale)
+  are unaffected — they don't go through this tool.
+
+### Changed
+
+- **Stats reporting now sends the `x-sync-token` header.** The dashboard derives
+  your GitHub id from the token instead of trusting the `githubId` in the request
+  body, closing a spoofing gap where anyone could forge usage events (or unarchive
+  projects) for another user. Stats keep working on older CLIs — they're just
+  recorded anonymously until you upgrade. No behavior change for you locally.
+
 ## [2.1.2] — 2026-05-21
 
 > ACP server enhancements that power the new Codeep VS Code 2.2 features — editor clients can now list models per provider and pin a provider, model, or custom endpoint over the protocol.

README.md

@@ -449,9 +449,14 @@ Example — auto-format on edit (`.codeep/hooks/post_edit.sh`):
 prettier --write "$CODEEP_HOOK_FILE" 2>/dev/null
 ```
 
-Run `/hooks` to see which hooks are installed in the current workspace. Hooks
-trigger a security banner on session start since they're arbitrary shell that
-runs whenever an agent tool fires.
+Run `/hooks` to see which hooks are installed in the current workspace.
+
+**Trust required (security).** Because hooks run arbitrary shell, a freshly
+cloned repo's hooks are **not** run until you approve the workspace. Run
+`/hooks trust` to enable them for the current project (revoke with
+`/hooks untrust`); `/hooks` and the welcome banner show the trust state. Your
+own projects just need a one-time `/hooks trust`. Global `~/.codeep/hooks/` are
+never run for the same reason.
 
 ### Skill Bundles (new in 2.0)
 Beyond the built-in skills and custom slash commands, Codeep now supports

src/acp/commands.ts

@@ -983,8 +983,18 @@ Anything else the agent should know — edge cases, gotchas, things to double-ch
     }
 
     case 'hooks': {
-      const { listInstalledHooks, formatHookList } = await import('../utils/hooks.js');
-      return { handled: true, response: formatHookList(listInstalledHooks(session.workspaceRoot)) };
+      const { listInstalledHooks, formatHookList, formatHookTrust, trustWorkspaceHooks, untrustWorkspaceHooks } = await import('../utils/hooks.js');
+      const sub = (args[0] || '').toLowerCase();
+      if (sub === 'trust') {
+        trustWorkspaceHooks(session.workspaceRoot);
+        return { handled: true, response: 'Hooks trusted for this workspace — they will now run.' };
+      }
+      if (sub === 'untrust') {
+        untrustWorkspaceHooks(session.workspaceRoot);
+        return { handled: true, response: 'Hooks untrusted — they will be skipped until you trust again.' };
+      }
+      const trust = formatHookTrust(session.workspaceRoot);
+      return { handled: true, response: formatHookList(listInstalledHooks(session.workspaceRoot)) + (trust ? `\n\n${trust}` : '') };
     }
 
     case 'mcp': {

src/config/index.ts

@@ -56,6 +56,10 @@ interface ConfigSchema {
    *  small background API call (uses the active model) once per session.
    *  Default true; set false to avoid any unsolicited API calls. */
   autoSessionTitle: boolean;
+  /** Absolute workspace roots whose project-local `.codeep/hooks/*` the user
+   *  has approved to run. Untrusted projects' hooks are skipped (a cloned repo
+   *  can't execute shell on first tool call). Granted via `/hooks trust`. */
+  trustedHookProjects: string[];
   currentSessionId: string;
   temperature: number;
   maxTokens: number;
@@ -277,6 +281,7 @@ function createConfig(): Conf<ConfigSchema> {
     language: 'en',
     autoSave: true,
     autoSessionTitle: true,
+    trustedHookProjects: [],
     currentSessionId: '',
     temperature: 0.7,
     maxTokens: 32768,

src/renderer/commands.ts

@@ -1138,8 +1138,21 @@ Format: use headers per category, only include categories where you found issues
     }
 
     case 'hooks': {
-      const { listInstalledHooks, formatHookList } = await import('../utils/hooks');
-      ctx.app.addMessage({ role: 'system', content: formatHookList(listInstalledHooks(ctx.projectPath)) });
+      const { listInstalledHooks, formatHookList, formatHookTrust, trustWorkspaceHooks, untrustWorkspaceHooks } = await import('../utils/hooks');
+      const sub = (args[0] || '').toLowerCase();
+      if (sub === 'trust') {
+        trustWorkspaceHooks(ctx.projectPath);
+        ctx.app.notify('Hooks trusted for this workspace — they will now run.');
+        break;
+      }
+      if (sub === 'untrust') {
+        untrustWorkspaceHooks(ctx.projectPath);
+        ctx.app.notify('Hooks untrusted — they will be skipped until you trust again.');
+        break;
+      }
+      const trust = formatHookTrust(ctx.projectPath);
+      const body = formatHookList(listInstalledHooks(ctx.projectPath)) + (trust ? `\n\n${trust}` : '');
+      ctx.app.addMessage({ role: 'system', content: body });
       break;
     }
 

src/utils/codeepCloud.ts

@@ -140,9 +140,13 @@ export function reportStats(payload: StatsPayload): void {
   const githubId = getGithubId();
   if (!githubId) return; // not linked, skip silently
 
+  // Send the sync token so the server can attribute the event to us. The
+  // server derives github_id from the token and ignores the body value (the
+  // body githubId is kept only for backward-compat with older servers).
+  const syncToken = getSyncToken();
   fetchWithRetry(`${API_BASE}/api/stats`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: { 'Content-Type': 'application/json', ...(syncToken ? { 'x-sync-token': syncToken } : {}) },
     body: JSON.stringify({ ...payload, githubId, isGit: payload.isGit ?? false }),
   }).catch(() => {});
 }
@@ -151,9 +155,10 @@ export async function reportStatsAsync(payload: StatsPayload): Promise<void> {
   const githubId = getGithubId();
   if (!githubId) return;
 
+  const syncToken = getSyncToken();
   await fetchWithRetry(`${API_BASE}/api/stats`, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: { 'Content-Type': 'application/json', ...(syncToken ? { 'x-sync-token': syncToken } : {}) },
     body: JSON.stringify({ ...payload, githubId, isGit: payload.isGit ?? false }),
   });
 }

src/utils/hooks.test.ts

@@ -7,6 +7,8 @@ import {
   listInstalledHooks,
   formatHookList,
   summarizeHooks,
+  trustWorkspaceHooks,
+  untrustWorkspaceHooks,
   HookEvent,
 } from './hooks';
 
@@ -17,9 +19,13 @@ beforeEach(() => {
   workspaceRoot = mkdtempSync(join(tmpdir(), 'codeep-hooks-'));
   hooksDir = join(workspaceRoot, '.codeep', 'hooks');
   mkdirSync(hooksDir, { recursive: true });
+  // Hooks are skipped in untrusted workspaces (trust-on-first-use). These tests
+  // exercise the run path, so trust the temp workspace up front.
+  trustWorkspaceHooks(workspaceRoot);
 });
 
 afterEach(() => {
+  untrustWorkspaceHooks(workspaceRoot);
   rmSync(workspaceRoot, { recursive: true, force: true });
 });
 
@@ -50,6 +56,35 @@ describe('runHook — no script present', () => {
   });
 });
 
+describe('runHook — trust gate', () => {
+  it('skips an existing hook when the workspace is not trusted', () => {
+    writeHook('post_edit', 'echo "should not run"');
+    untrustWorkspaceHooks(workspaceRoot);
+    const result = runHook({ event: 'post_edit', workspaceRoot });
+    expect(result.executed).toBe(false);
+    expect(result.untrusted).toBe(true);
+    expect(result.stdout).toBe('');
+  });
+
+  it('does not block a tool call when an untrusted blocking hook is skipped', () => {
+    writeHook('pre_tool_call', 'exit 1'); // would block if it ran
+    untrustWorkspaceHooks(workspaceRoot);
+    const result = runHook({ event: 'pre_tool_call', workspaceRoot });
+    expect(result.executed).toBe(false);
+    expect(result.blocked).toBe(false);
+  });
+
+  it('runs the hook again once the workspace is re-trusted', () => {
+    writeHook('post_edit', 'echo "trusted run"');
+    untrustWorkspaceHooks(workspaceRoot);
+    expect(runHook({ event: 'post_edit', workspaceRoot }).executed).toBe(false);
+    trustWorkspaceHooks(workspaceRoot);
+    const result = runHook({ event: 'post_edit', workspaceRoot });
+    expect(result.executed).toBe(true);
+    expect(result.stdout).toMatch(/trusted run/);
+  });
+});
+
 describe('runHook — script present', () => {
   it('runs the script and captures stdout/stderr', () => {
     writeHook('post_edit', 'echo "hello from hook"; echo "err msg" >&2');

src/utils/hooks.ts

@@ -49,6 +49,33 @@
 import { existsSync, readdirSync, statSync, accessSync, constants } from 'fs';
 import { join } from 'path';
 import { spawnSync } from 'child_process';
+import { config } from '../config/index.js';
+
+// ─── Trust-on-first-use ──────────────────────────────────────────────────────
+// Project-local hooks run arbitrary shell, so a freshly-cloned hostile repo
+// must NOT execute its scripts on the first tool call. A workspace's hooks run
+// only after the user explicitly trusts it (`/hooks trust`); the approval is
+// stored per-workspace-root in config. Mirrors VS Code Workspace Trust /
+// `direnv allow`.
+
+export function isHooksTrusted(workspaceRoot: string): boolean {
+  try {
+    const trusted = config.get('trustedHookProjects') as string[] | undefined;
+    return Array.isArray(trusted) && trusted.includes(workspaceRoot);
+  } catch {
+    return false;
+  }
+}
+
+export function trustWorkspaceHooks(workspaceRoot: string): void {
+  const cur = (config.get('trustedHookProjects') as string[] | undefined) ?? [];
+  if (!cur.includes(workspaceRoot)) config.set('trustedHookProjects', [...cur, workspaceRoot]);
+}
+
+export function untrustWorkspaceHooks(workspaceRoot: string): void {
+  const cur = (config.get('trustedHookProjects') as string[] | undefined) ?? [];
+  config.set('trustedHookProjects', cur.filter((p) => p !== workspaceRoot));
+}
 
 export type HookEvent = 'pre_tool_call' | 'post_edit' | 'on_error' | 'pre_commit';
 export const HOOK_EVENTS: readonly HookEvent[] = ['pre_tool_call', 'post_edit', 'on_error', 'pre_commit'];
@@ -79,6 +106,9 @@ export interface HookResult {
   blocked: boolean;
   /** Path that was executed (useful for error messages). */
   scriptPath?: string;
+  /** True when a hook script exists but the workspace isn't trusted, so it was
+   *  skipped (not run). Lets callers surface "run /hooks trust to enable". */
+  untrusted?: boolean;
 }
 
 const NOT_EXECUTED: HookResult = { executed: false, exitCode: 0, stdout: '', stderr: '', blocked: false };
@@ -118,6 +148,13 @@ export function runHook(ctx: HookContext, opts: { timeoutMs?: number } = {}): Ho
   const script = findHookScript(ctx.workspaceRoot, ctx.event);
   if (!script) return NOT_EXECUTED;
 
+  // Trust gate: never run a project's hooks until the user has approved this
+  // workspace. A non-blocking skip — the agent proceeds without the hook
+  // rather than being held hostage by an untrusted (or hostile) script.
+  if (!isHooksTrusted(ctx.workspaceRoot)) {
+    return { executed: false, exitCode: 0, stdout: '', stderr: '', blocked: false, untrusted: true, scriptPath: script };
+  }
+
   const env: Record<string, string> = {
     ...process.env as Record<string, string>,
     CODEEP_HOOK_EVENT: ctx.event,
@@ -235,12 +272,32 @@ export function formatHookList(hooks: ReturnType<typeof listInstalledHooks>): st
   return lines.join('\n');
 }
 
+/**
+ * Build the trust banner for `/hooks` and the welcome screen. `workspaceRoot`
+ * is needed to read trust state; returns '' if no hooks are installed.
+ */
+export function formatHookTrust(workspaceRoot: string): string {
+  const hooks = listInstalledHooks(workspaceRoot);
+  if (hooks.length === 0) return '';
+  if (isHooksTrusted(workspaceRoot)) {
+    return '✓ This workspace is **trusted** — its hooks will run. Use `/hooks untrust` to revoke.';
+  }
+  return [
+    '⚠️ This workspace is **not trusted**, so its hooks are **skipped** (they run arbitrary shell).',
+    'If you wrote these hooks (or trust this repo), run `/hooks trust` to enable them.',
+  ].join('\n');
+}
+
 /**
  * Short one-line summary used in the welcome banner when hooks are present.
  * Returns empty string if no hooks installed.
  */
 export function summarizeHooks(workspaceRoot: string): string {
   const hooks = listInstalledHooks(workspaceRoot);
   if (hooks.length === 0) return '';
-  return `${hooks.length} hook${hooks.length === 1 ? '' : 's'} active (${hooks.map(h => h.event).join(', ')})`;
+  const list = hooks.map(h => h.event).join(', ');
+  if (!isHooksTrusted(workspaceRoot)) {
+    return `${hooks.length} hook${hooks.length === 1 ? '' : 's'} present but NOT trusted — run /hooks trust to enable (${list})`;
+  }
+  return `${hooks.length} hook${hooks.length === 1 ? '' : 's'} active (${list})`;
 }

src/utils/toolExecution.test.ts

@@ -4,14 +4,19 @@ import { join } from 'path';
 import { tmpdir } from 'os';
 import { executeTool, FsCallbacks } from './toolExecution';
 import { ToolCall } from './tools';
+import { trustWorkspaceHooks, untrustWorkspaceHooks } from './hooks';
 
 let tmpRoot: string;
 
 beforeEach(() => {
   tmpRoot = mkdtempSync(join(tmpdir(), 'codeep-toolexec-'));
+  // Project hooks only run in trusted workspaces; the integration tests below
+  // exercise the hook path, so trust the temp workspace.
+  trustWorkspaceHooks(tmpRoot);
 });
 
 afterEach(() => {
+  untrustWorkspaceHooks(tmpRoot);
   rmSync(tmpRoot, { recursive: true, force: true });
 });
 

src/utils/toolExecution.ts

@@ -18,6 +18,67 @@ import { ToolCall, ToolResult, ActionLog } from './tools';
 import { logger } from './logger';
 import { runHook } from './hooks';
 import { isMcpToolName, callSessionTool, isVirtualMcpToolName, callSessionVirtualTool } from './mcpRegistry';
+import { lookup as dnsLookup } from 'dns/promises';
+
+/**
+ * SSRF guard for the agent's `fetch_url` tool. The URL there comes from model
+ * output / page content (untrusted, prompt-injectable), so the agent must not
+ * be able to reach internal services or the cloud metadata endpoint
+ * (169.254.169.254). NOTE: this does NOT apply to user-configured provider
+ * base URLs (Ollama localhost, custom vLLM/Tailscale endpoints) — those are
+ * trusted config and never routed through fetch_url.
+ */
+function isBlockedIp(ip: string): boolean {
+  const s = ip.trim().toLowerCase();
+  if (s.includes(':')) {
+    // IPv6
+    if (s === '::1' || s === '::') return true;                       // loopback / unspecified
+    if (s.startsWith('fe80') || s.startsWith('fc') || s.startsWith('fd')) return true; // link-local / ULA
+    const mapped = s.match(/::ffff:(\d+\.\d+\.\d+\.\d+)$/);            // IPv4-mapped
+    if (mapped) return isBlockedIp(mapped[1]);
+    return false;
+  }
+  const parts = s.split('.').map(Number);
+  if (parts.length !== 4 || parts.some((n) => Number.isNaN(n) || n < 0 || n > 255)) return false;
+  const [a, b] = parts;
+  if (a === 127) return true;                        // loopback
+  if (a === 10) return true;                         // RFC1918
+  if (a === 172 && b >= 16 && b <= 31) return true;  // RFC1918
+  if (a === 192 && b === 168) return true;           // RFC1918
+  if (a === 169 && b === 254) return true;           // link-local incl. metadata 169.254.169.254
+  if (a === 0) return true;                          // 0.0.0.0/8
+  return false;
+}
+
+/** Returns an error string if the URL must not be fetched, else null. */
+async function assertFetchUrlAllowed(rawUrl: string): Promise<string | null> {
+  let u: URL;
+  try { u = new URL(rawUrl); } catch { return 'Invalid URL format'; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    return `Blocked: only http/https URLs can be fetched (got "${u.protocol}")`;
+  }
+  const host = u.hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+  if (host === 'localhost' || host.endsWith('.localhost')) {
+    return 'Blocked: localhost is not fetchable by the agent';
+  }
+  if (/^[0-9.]+$/.test(host) || host.includes(':')) {
+    // Literal IP — check directly.
+    if (isBlockedIp(host)) return `Blocked: ${host} is a private/loopback/link-local address`;
+    return null;
+  }
+  // Resolve and check every address (catches internal hostnames + single-record rebinding).
+  try {
+    const addrs = await dnsLookup(host, { all: true });
+    for (const a of addrs) {
+      if (isBlockedIp(a.address)) {
+        return `Blocked: ${host} resolves to a private/internal address (${a.address})`;
+      }
+    }
+  } catch {
+    // DNS failure — let curl attempt and fail naturally; not an SSRF risk.
+  }
+  return null;
+}
 
 const debug = (...args: unknown[]) => {
   if (process.env.CODEEP_DEBUG === '1') {
@@ -578,9 +639,13 @@ async function dispatchTool(
         const url = parameters.url as string;
         if (!url) return { success: false, output: '', error: 'Missing required parameter: url', tool, parameters };
 
-        try { new URL(url); } catch { return { success: false, output: '', error: 'Invalid URL format', tool, parameters }; }
+        const blockedReason = await assertFetchUrlAllowed(url);
+        if (blockedReason) return { success: false, output: '', error: blockedReason, tool, parameters };
 
-        const result = await executeCommandAsync('curl', ['-s', '-L', '-m', '30', '-A', 'Codeep/1.0', '--max-filesize', '1000000', url], {
+        // Restrict to http/https on the initial request AND redirects, and cap
+        // redirect hops — defends against protocol-smuggling and limits
+        // redirect-based SSRF reach (initial host is already IP-checked above).
+        const result = await executeCommandAsync('curl', ['-s', '-L', '--proto', '=http,https', '--proto-redir', '=http,https', '--max-redirs', '5', '-m', '30', '-A', 'Codeep/1.0', '--max-filesize', '1000000', url], {
           cwd: projectRoot,
           projectRoot,
           timeout: 35000,