feat(build): inline all external tool checksums at build time

jdalton · jdalton · commit aa07ba0655b4 · 2026-03-24T14:09:27.000-04:00
Add build-time inlined checksums for all security tools:
- SFW (Socket Firewall)
- OpenGrep
- Trivy
- TruffleHog

Each tool now has a dedicated checksum getter module with:
- get*Checksums(): Returns checksum map from inlined env var
- require*Checksum(): Hard error in prod if checksum missing

This ensures production builds have integrity verification for
all external tool downloads, while allowing dev mode flexibility.
diff --git a/packages/cli/scripts/environment-variables.mjs b/packages/cli/scripts/environment-variables.mjs
@@ -108,9 +108,14 @@ export class EnvironmentVariables {
       publishedBuild ? '' : ':dev'
     }`
 
-    // Get checksums for tools that have them.
+    // Get checksums for all external tools that have them.
+    // All GitHub-released tools have checksums for integrity verification.
+    const opengrepChecksums = externalTools.opengrep?.checksums || {}
     const pythonChecksums = externalTools.python?.checksums || {}
+    const sfwChecksums = externalTools.sfw?.checksums || {}
     const socketPatchChecksums = externalTools['socket-patch']?.checksums || {}
+    const trivyChecksums = externalTools.trivy?.checksums || {}
+    const trufflehogChecksums = externalTools.trufflehog?.checksums || {}
 
     // Return all environment variables with raw values.
     return {
@@ -119,19 +124,23 @@ export class EnvironmentVariables {
       INLINED_SOCKET_CLI_CYCLONEDX_CDXGEN_VERSION: cdxgenVersion,
       INLINED_SOCKET_CLI_HOMEPAGE: packageJson.homepage,
       INLINED_SOCKET_CLI_NAME: packageJson.name,
+      INLINED_SOCKET_CLI_OPENGREP_CHECKSUMS: JSON.stringify(opengrepChecksums),
       INLINED_SOCKET_CLI_OPENGREP_VERSION: opengrepVersion,
       INLINED_SOCKET_CLI_PUBLISHED_BUILD: publishedBuild ? '1' : '',
       INLINED_SOCKET_CLI_PYCLI_VERSION: pyCliVersion,
       INLINED_SOCKET_CLI_PYTHON_BUILD_TAG: pythonBuildTag,
       INLINED_SOCKET_CLI_PYTHON_CHECKSUMS: JSON.stringify(pythonChecksums),
       INLINED_SOCKET_CLI_PYTHON_VERSION: pythonVersion,
       INLINED_SOCKET_CLI_SENTRY_BUILD: sentryBuild ? '1' : '',
+      INLINED_SOCKET_CLI_SFW_CHECKSUMS: JSON.stringify(sfwChecksums),
       INLINED_SOCKET_CLI_SFW_NPM_VERSION: sfwNpmVersion,
       INLINED_SOCKET_CLI_SFW_VERSION: sfwVersion,
       INLINED_SOCKET_CLI_SOCKET_PATCH_CHECKSUMS: JSON.stringify(socketPatchChecksums),
       INLINED_SOCKET_CLI_SOCKET_PATCH_VERSION: socketPatchVersion,
       INLINED_SOCKET_CLI_SYNP_VERSION: synpVersion,
+      INLINED_SOCKET_CLI_TRIVY_CHECKSUMS: JSON.stringify(trivyChecksums),
       INLINED_SOCKET_CLI_TRIVY_VERSION: trivyVersion,
+      INLINED_SOCKET_CLI_TRUFFLEHOG_CHECKSUMS: JSON.stringify(trufflehogChecksums),
       INLINED_SOCKET_CLI_TRUFFLEHOG_VERSION: trufflehogVersion,
       INLINED_SOCKET_CLI_VERSION: socketPackageJson.version,
       INLINED_SOCKET_CLI_VERSION_HASH: versionHash,
diff --git a/packages/cli/src/env/opengrep-checksums.mts b/packages/cli/src/env/opengrep-checksums.mts
@@ -0,0 +1,63 @@
+/**
+ * OpenGrep SHA-256 checksums getter function.
+ * Uses direct process.env access so esbuild define can inline values.
+ * IMPORTANT: esbuild's define plugin can only replace direct process.env['KEY'] references.
+ * If we imported from env modules, esbuild couldn't inline the values at build time.
+ * This is critical for embedding checksums into the binary for integrity verification.
+ */
+
+import process from 'node:process'
+
+import type { OpengrepChecksums } from '../types.mjs'
+
+/**
+ * Get OpenGrep checksums from inlined environment variable.
+ * Returns a map of asset filename to SHA-256 hex checksum.
+ *
+ * @throws Error if checksums are missing in production builds.
+ */
+export function getOpengrepChecksums(): OpengrepChecksums {
+  const checksums = process.env['INLINED_SOCKET_CLI_OPENGREP_CHECKSUMS']
+  if (!checksums) {
+    // In development mode (not inlined), return empty object.
+    // Build validation will catch missing checksums at build time.
+    return {}
+  }
+  try {
+    return JSON.parse(checksums) as OpengrepChecksums
+  } catch {
+    throw new Error(
+      'Failed to parse OpenGrep checksums. This indicates a build configuration error.',
+    )
+  }
+}
+
+/**
+ * Lookup an OpenGrep checksum by asset name.
+ * In production builds (checksums inlined), throws a hard error if asset is missing.
+ * In dev mode (checksums not inlined), returns undefined to allow development.
+ *
+ * @param assetName - The asset filename to look up.
+ * @returns The SHA-256 hex checksum, or undefined in dev mode.
+ * @throws Error if checksum is not found in production builds.
+ */
+export function requireOpengrepChecksum(assetName: string): string | undefined {
+  const checksums = getOpengrepChecksums()
+
+  // In dev mode, checksums are not inlined so the object is empty.
+  // Allow downloads without verification during development.
+  if (Object.keys(checksums).length === 0) {
+    return undefined
+  }
+
+  // In production mode, checksums are inlined.
+  // Require checksum for every asset - missing checksum is a HARD ERROR.
+  const sha256 = checksums[assetName]
+  if (!sha256) {
+    throw new Error(
+      `Missing SHA-256 checksum for OpenGrep asset: ${assetName}. ` +
+        'This is a security requirement. Please update external-tools.json with the correct checksum.',
+    )
+  }
+  return sha256
+}
diff --git a/packages/cli/src/env/sfw-checksums.mts b/packages/cli/src/env/sfw-checksums.mts
@@ -0,0 +1,63 @@
+/**
+ * SFW SHA-256 checksums getter function.
+ * Uses direct process.env access so esbuild define can inline values.
+ * IMPORTANT: esbuild's define plugin can only replace direct process.env['KEY'] references.
+ * If we imported from env modules, esbuild couldn't inline the values at build time.
+ * This is critical for embedding checksums into the binary for integrity verification.
+ */
+
+import process from 'node:process'
+
+import type { SfwChecksums } from '../types.mjs'
+
+/**
+ * Get SFW checksums from inlined environment variable.
+ * Returns a map of asset filename to SHA-256 hex checksum.
+ *
+ * @throws Error if checksums are missing in production builds.
+ */
+export function getSfwChecksums(): SfwChecksums {
+  const checksums = process.env['INLINED_SOCKET_CLI_SFW_CHECKSUMS']
+  if (!checksums) {
+    // In development mode (not inlined), return empty object.
+    // Build validation will catch missing checksums at build time.
+    return {}
+  }
+  try {
+    return JSON.parse(checksums) as SfwChecksums
+  } catch {
+    throw new Error(
+      'Failed to parse SFW checksums. This indicates a build configuration error.',
+    )
+  }
+}
+
+/**
+ * Lookup an SFW checksum by asset name.
+ * In production builds (checksums inlined), throws a hard error if asset is missing.
+ * In dev mode (checksums not inlined), returns undefined to allow development.
+ *
+ * @param assetName - The asset filename to look up.
+ * @returns The SHA-256 hex checksum, or undefined in dev mode.
+ * @throws Error if checksum is not found in production builds.
+ */
+export function requireSfwChecksum(assetName: string): string | undefined {
+  const checksums = getSfwChecksums()
+
+  // In dev mode, checksums are not inlined so the object is empty.
+  // Allow downloads without verification during development.
+  if (Object.keys(checksums).length === 0) {
+    return undefined
+  }
+
+  // In production mode, checksums are inlined.
+  // Require checksum for every asset - missing checksum is a HARD ERROR.
+  const sha256 = checksums[assetName]
+  if (!sha256) {
+    throw new Error(
+      `Missing SHA-256 checksum for SFW asset: ${assetName}. ` +
+        'This is a security requirement. Please update external-tools.json with the correct checksum.',
+    )
+  }
+  return sha256
+}
diff --git a/packages/cli/src/env/trivy-checksums.mts b/packages/cli/src/env/trivy-checksums.mts
@@ -0,0 +1,63 @@
+/**
+ * Trivy SHA-256 checksums getter function.
+ * Uses direct process.env access so esbuild define can inline values.
+ * IMPORTANT: esbuild's define plugin can only replace direct process.env['KEY'] references.
+ * If we imported from env modules, esbuild couldn't inline the values at build time.
+ * This is critical for embedding checksums into the binary for integrity verification.
+ */
+
+import process from 'node:process'
+
+import type { TrivyChecksums } from '../types.mjs'
+
+/**
+ * Get Trivy checksums from inlined environment variable.
+ * Returns a map of asset filename to SHA-256 hex checksum.
+ *
+ * @throws Error if checksums are missing in production builds.
+ */
+export function getTrivyChecksums(): TrivyChecksums {
+  const checksums = process.env['INLINED_SOCKET_CLI_TRIVY_CHECKSUMS']
+  if (!checksums) {
+    // In development mode (not inlined), return empty object.
+    // Build validation will catch missing checksums at build time.
+    return {}
+  }
+  try {
+    return JSON.parse(checksums) as TrivyChecksums
+  } catch {
+    throw new Error(
+      'Failed to parse Trivy checksums. This indicates a build configuration error.',
+    )
+  }
+}
+
+/**
+ * Lookup a Trivy checksum by asset name.
+ * In production builds (checksums inlined), throws a hard error if asset is missing.
+ * In dev mode (checksums not inlined), returns undefined to allow development.
+ *
+ * @param assetName - The asset filename to look up.
+ * @returns The SHA-256 hex checksum, or undefined in dev mode.
+ * @throws Error if checksum is not found in production builds.
+ */
+export function requireTrivyChecksum(assetName: string): string | undefined {
+  const checksums = getTrivyChecksums()
+
+  // In dev mode, checksums are not inlined so the object is empty.
+  // Allow downloads without verification during development.
+  if (Object.keys(checksums).length === 0) {
+    return undefined
+  }
+
+  // In production mode, checksums are inlined.
+  // Require checksum for every asset - missing checksum is a HARD ERROR.
+  const sha256 = checksums[assetName]
+  if (!sha256) {
+    throw new Error(
+      `Missing SHA-256 checksum for Trivy asset: ${assetName}. ` +
+        'This is a security requirement. Please update external-tools.json with the correct checksum.',
+    )
+  }
+  return sha256
+}
diff --git a/packages/cli/src/env/trufflehog-checksums.mts b/packages/cli/src/env/trufflehog-checksums.mts
@@ -0,0 +1,63 @@
+/**
+ * TruffleHog SHA-256 checksums getter function.
+ * Uses direct process.env access so esbuild define can inline values.
+ * IMPORTANT: esbuild's define plugin can only replace direct process.env['KEY'] references.
+ * If we imported from env modules, esbuild couldn't inline the values at build time.
+ * This is critical for embedding checksums into the binary for integrity verification.
+ */
+
+import process from 'node:process'
+
+import type { TrufflehogChecksums } from '../types.mjs'
+
+/**
+ * Get TruffleHog checksums from inlined environment variable.
+ * Returns a map of asset filename to SHA-256 hex checksum.
+ *
+ * @throws Error if checksums are missing in production builds.
+ */
+export function getTrufflehogChecksums(): TrufflehogChecksums {
+  const checksums = process.env['INLINED_SOCKET_CLI_TRUFFLEHOG_CHECKSUMS']
+  if (!checksums) {
+    // In development mode (not inlined), return empty object.
+    // Build validation will catch missing checksums at build time.
+    return {}
+  }
+  try {
+    return JSON.parse(checksums) as TrufflehogChecksums
+  } catch {
+    throw new Error(
+      'Failed to parse TruffleHog checksums. This indicates a build configuration error.',
+    )
+  }
+}
+
+/**
+ * Lookup a TruffleHog checksum by asset name.
+ * In production builds (checksums inlined), throws a hard error if asset is missing.
+ * In dev mode (checksums not inlined), returns undefined to allow development.
+ *
+ * @param assetName - The asset filename to look up.
+ * @returns The SHA-256 hex checksum, or undefined in dev mode.
+ * @throws Error if checksum is not found in production builds.
+ */
+export function requireTrufflehogChecksum(assetName: string): string | undefined {
+  const checksums = getTrufflehogChecksums()
+
+  // In dev mode, checksums are not inlined so the object is empty.
+  // Allow downloads without verification during development.
+  if (Object.keys(checksums).length === 0) {
+    return undefined
+  }
+
+  // In production mode, checksums are inlined.
+  // Require checksum for every asset - missing checksum is a HARD ERROR.
+  const sha256 = checksums[assetName]
+  if (!sha256) {
+    throw new Error(
+      `Missing SHA-256 checksum for TruffleHog asset: ${assetName}. ` +
+        'This is a security requirement. Please update external-tools.json with the correct checksum.',
+    )
+  }
+  return sha256
+}
diff --git a/packages/cli/src/types.mts b/packages/cli/src/types.mts
@@ -9,8 +9,12 @@ export type BaseFetchOptions = {
 
 // Checksum types for external tool integrity verification.
 // Maps asset filename to SHA-256 hex checksum.
+export type OpengrepChecksums = Record<string, string>
 export type PythonChecksums = Record<string, string>
+export type SfwChecksums = Record<string, string>
 export type SocketPatchChecksums = Record<string, string>
+export type TrivyChecksums = Record<string, string>
+export type TrufflehogChecksums = Record<string, string>
 
 // CResult is akin to the "Result" or "Outcome" or "Either" pattern.
 // Main difference might be that it's less strict about the error side of
