CLI-245 PreToolUse secrets scanner callback

Author: kirill-knize-sonarsource

src/cli/command-tree.ts

@@ -39,6 +39,7 @@ import { parseInteger } from './commands/_common/parsing';
 import { MAX_PAGE_SIZE } from '../sonarqube/projects';
 import { apiCommand, apiExtraHelpText, type ApiCommandOptions } from './commands/api/api';
 import { GENERIC_HTTP_METHODS } from '../sonarqube/client';
+import { claudePreToolUse } from './commands/hook/claude-pre-tool-use';
 
 const DEFAULT_PAGE_SIZE = MAX_PAGE_SIZE;
 
@@ -229,14 +230,43 @@ COMMAND_TREE.command('self-update')
   .anonymousAction((options: SelfUpdateOptions) => selfUpdate(options));
 
 // Hidden callback command — internal handlers for agent and git hooks.
-// Shell hook scripts call `sonar callback <event>` to delegate all business logic to TypeScript.
-export const callbackCommand = COMMAND_TREE.command('callback', { hidden: true })
+// Shell hook scripts call `sonar hook <event>` to delegate all business logic to TypeScript.
+export const callbackCommand = COMMAND_TREE.command('hook', { hidden: true })
   .description('Internal callback handlers for agent and git hooks')
   .enablePositionalOptions()
   .anonymousAction(function (this: Command) {
     this.outputHelp();
   });
 
+callbackCommand
+  .command('claude-pre-tool-use')
+  .description('PreToolUse handler: scan files for secrets before agent reads them')
+  .anonymousAction(() => claudePreToolUse());
+
+// codex-pre-tool-use reuses the same handler (same hook event, different agent name)
+callbackCommand
+  .command('codex-pre-tool-use')
+  .description('PreToolUse handler for Codex: scan files for secrets before agent reads them')
+  .anonymousAction(() => claudePreToolUse());
+
+// agent-prompt-submit and agent-post-tool-use are installed by `sonar integrate claude`.
+// They are implemented in subsequent PRs; stubs here ensure scripts don't fail with
+// "unknown command" on a CLI that only has CLI-244/245.
+callbackCommand
+  .command('agent-prompt-submit')
+  .description('UserPromptSubmit handler: scan prompts for secrets before sending')
+  .anonymousAction(() => {
+    return;
+  });
+
+callbackCommand
+  .command('agent-post-tool-use')
+  .option('-p, --project <project>', 'SonarCloud project key')
+  .description('PostToolUse handler: run SQAA analysis on modified files')
+  .anonymousAction(() => {
+    return;
+  });
+
 // Hidden flush command — only registered when running as a telemetry worker.
 if (process.env[TELEMETRY_FLUSH_MODE_ENV]) {
   COMMAND_TREE.command('flush-telemetry', { hidden: true }).anonymousAction(flushTelemetry);

src/cli/commands/hook/claude-pre-tool-use.ts

@@ -0,0 +1,70 @@
+/*
+ * SonarQube CLI
+ * Copyright (C) 2026 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+// PreToolUse callback handler — scans files for secrets before the agent reads them.
+// Replaces the bash/PowerShell logic that was previously embedded in the hook script.
+
+import { existsSync } from 'node:fs';
+import { resolveAuth } from '../../../lib/auth-resolver';
+import logger from '../../../lib/logger';
+import { readStdinJson } from './stdin';
+import { resolveSecretsBinaryPath, scanFiles, EXIT_CODE_SECRETS_FOUND } from './secrets-scan';
+
+interface PreToolUsePayload {
+  tool_name?: string;
+  tool_input?: { file_path?: string };
+}
+
+export async function claudePreToolUse(): Promise<void> {
+  let payload: PreToolUsePayload;
+  try {
+    payload = await readStdinJson<PreToolUsePayload>();
+  } catch {
+    return; // unparseable stdin — allow
+  }
+
+  if (payload.tool_name !== 'Read') return;
+
+  const filePath = payload.tool_input?.file_path;
+  if (!filePath || !existsSync(filePath)) return;
+
+  const auth = await resolveAuth().catch(() => null);
+  if (!auth) return; // not authenticated — allow gracefully
+
+  const binaryPath = resolveSecretsBinaryPath();
+  if (!binaryPath) return; // binary not installed — allow gracefully
+
+  try {
+    const exitCode = await scanFiles(binaryPath, [filePath], auth);
+    if (exitCode === EXIT_CODE_SECRETS_FOUND) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: `Sonar detected secrets in file: ${filePath}`,
+          },
+        }) + '\n',
+      );
+    }
+  } catch (err) {
+    logger.debug(`PreToolUse secrets scan failed: ${(err as Error).message}`);
+  }
+}

src/cli/commands/hook/secrets-scan.ts

@@ -0,0 +1,85 @@
+/*
+ * SonarQube CLI
+ * Copyright (C) 2026 SonarSource Sàrl
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+
+// Shared sonar-secrets invocation for all callback handlers.
+// Resolves the installed binary path silently — no download, no UI output.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ResolvedAuth } from '../../../lib/auth-resolver';
+import { spawnProcess } from '../../../lib/process';
+import { BIN_DIR } from '../../../lib/config-constants';
+import { detectPlatform } from '../../../lib/platform-detector';
+import { buildLocalBinaryName } from '../_common/install/secrets';
+
+const BINARY_AUTH_URL_ENV = 'SONAR_SECRETS_AUTH_URL';
+const BINARY_AUTH_TOKEN_ENV = 'SONAR_SECRETS_TOKEN';
+const SCAN_TIMEOUT_MS = 30000;
+
+export const EXIT_CODE_SECRETS_FOUND = 51;
+
+/**
+ * Returns the path to the installed sonar-secrets binary, or null if not present.
+ * Never downloads — use this in callback handlers where silent operation is required.
+ */
+export function resolveSecretsBinaryPath(): string | null {
+  const platform = detectPlatform();
+  const binaryPath = join(BIN_DIR, buildLocalBinaryName(platform));
+  return existsSync(binaryPath) ? binaryPath : null;
+}
+
+/**
+ * Run secrets scan on the given files. Returns the binary exit code.
+ * May throw on timeout; other errors are surfaced as non-zero exit codes.
+ */
+export async function scanFiles(
+  binaryPath: string,
+  files: string[],
+  auth: ResolvedAuth,
+): Promise<number> {
+  let killChild: (() => void) | undefined;
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const result = await Promise.race([
+      spawnProcess(binaryPath, ['--non-interactive', ...files], {
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
+        env: buildAuthEnv(auth),
+        onSpawn: (kill) => {
+          killChild = kill;
+        },
+      }),
+      new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          killChild?.();
+          reject(new Error(`Scan timed out after ${SCAN_TIMEOUT_MS}ms`));
+        }, SCAN_TIMEOUT_MS);
+      }),
+    ]);
+    return result.exitCode ?? 1;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+
+function buildAuthEnv(auth: ResolvedAuth): Record<string, string> {
+  return { [BINARY_AUTH_URL_ENV]: auth.serverUrl, [BINARY_AUTH_TOKEN_ENV]: auth.token };
+}

src/cli/commands/callback/stdin.ts src/cli/commands/hook/stdin.tssrc/cli/commands/callback/stdin.ts renamed to src/cli/commands/hook/stdin.ts

@@ -37,19 +37,24 @@ export async function readStdinJson<T>(): Promise<T> {
 }
 
 async function readRawStdin(): Promise<string> {
-  return Promise.race([
-    new Promise<string>((resolve, reject) => {
-      const chunks: Buffer[] = [];
-      process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk));
-      process.stdin.on('end', () => {
-        resolve(Buffer.concat(chunks).toString('utf-8'));
-      });
-      process.stdin.on('error', reject);
-    }),
-    new Promise<never>((_, reject) =>
-      setTimeout(() => {
-        reject(new Error(`stdin read timed out after ${STDIN_TIMEOUT_MS}ms`));
-      }, STDIN_TIMEOUT_MS),
-    ),
-  ]);
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      new Promise<string>((resolve, reject) => {
+        const chunks: Buffer[] = [];
+        process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk));
+        process.stdin.on('end', () => {
+          resolve(Buffer.concat(chunks).toString('utf-8'));
+        });
+        process.stdin.on('error', reject);
+      }),
+      new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new Error(`stdin read timed out after ${STDIN_TIMEOUT_MS}ms`));
+        }, STDIN_TIMEOUT_MS);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
 }