Auto-configure TruffleHog for Pre-commit Hooks (#4666)

* Trufflehog configure itself when running as a pre-commit hook * Updated readme * fallback for not auto detect
2026-01-20 11:12:06 +05:00
parent f946748dd9
commit 4da563af5a
3 changed files with 110 additions and 10 deletions
@@ -1,6 +1,6 @@
 - id: trufflehog
  name: TruffleHog
  description: Detect secrets in your data with TruffleHog.
-  entry: trufflehog git file://. --since-commit HEAD --results=verified --fail
+  entry: trufflehog git file://. --since-commit HEAD --results=verified --fail --trust-local-git-config
  language: golang
  pass_filenames: false
@@ -39,16 +39,41 @@ touch ~/.git-hooks/pre-commit
 chmod +x ~/.git-hooks/pre-commit
 ```

-3. Add the following content to `~/.git-hooks/pre-commit`:
+3. Configure Git Hook Script
+
+### **Standard Installation**
+#### **Option A: Auto-configured (Recommended)**
+
+TruffleHog automatically detects the `TRUFFLEHOG_PRE_COMMIT` environment variable and applies optimal pre-commit settings.

 ```bash
 #!/bin/sh
-
-trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail
+export TRUFFLEHOG_PRE_COMMIT=1
+trufflehog git file://.
 ```

-If you are using Docker, use this instead:
+#### **Option B: Manual-configuration**

+Manual configuration (only if you need custom behavior). Do NOT set `TRUFFLEHOG_PRE_COMMIT` if using manual configuration.
+```bash
+#!bin/sh
+trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail --trust-local-git-config
+```
+
+### **Docker Installation**
+
+#### **Option A: Auto-configured (Recommended)**
+```bash
+#!/bin/sh
+# Set environment variable inside container (recommended)
+docker run --rm \
+  -v "$(pwd):/workdir" \
+  -e "TRUFFLEHOG_PRE_COMMIT=1" \
+  trufflesecurity/trufflehog:latest \
+  git file:///workdir
+```
+
+#### **Option B: Manual-configuration**
 ```bash
 #!/bin/sh

@@ -88,6 +113,7 @@ To set up TruffleHog as a pre-commit hook for a specific repository:

 1. Create a `.pre-commit-config.yaml` file in the root of your repository:

+TruffleHog automatically detects when running under the pre-commit.com framework and applies optimal settings. No additional configuration is needed.
 ```yaml
 repos:
  - repo: local
@@ -95,7 +121,20 @@ repos:
      - id: trufflehog
        name: TruffleHog
        description: Detect secrets in your data.
-        entry: bash -c 'trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail'
+        entry: bash -c 'trufflehog git file://.'
+        language: system
+        stages: ["pre-commit", "pre-push"]
+```
+
+If TruffleHog doesn't auto-detect your pre-commit.com environment, you can manually specify the recommended pre-commit settings:
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: trufflehog
+        name: TruffleHog
+        description: Detect secrets in your data.
+        entry: bash -c 'trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail --trust-local-git-config'
        language: system
        stages: ["pre-commit", "pre-push"]
 ```
@@ -133,14 +172,20 @@ npx husky init

 1. Add the following content to `.husky/pre-commit`:

+TruffleHog automatically detects when running under the Husky framework and applies optimal settings. No additional configuration is needed.
 ```bash
-echo "trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail" > .husky/pre-commit
+echo "trufflehog git file://." > .husky/pre-commit
 ```

-3. For Docker users, use this content instead:
+If TruffleHog doesn't auto-detect your husky framework, you can manually specify the recommended pre-commit settings:
+```bash
+echo "trufflehog git file://. --since-commit HEAD --results=verified,unknown --fail --trust-local-git-config" > .husky/pre-commit
+```
+
+2. For Docker users, use this content instead:

 ```bash
-echo 'docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir --since-commit HEAD --results=verified,unknown --fail' > .husky/pre-commit
+echo 'docker run --rm -v "$(pwd):/workdir" -i --rm trufflesecurity/trufflehog:latest git file:///workdir' > .husky/pre-commit
 ```

 ## Best Practices
@@ -160,7 +205,7 @@ In rare cases, you may need to bypass pre-commit hooks:
 git commit --no-verify -m "Your commit message"
 ```

-### Running in Audit Mode
+### Running in Audit Mode (Without TRUFFLEHOG_PRE_COMMIT env variable)

 You can run the TruffleHog pre-commit hook in an "audit" or "non-enforcement" mode to test the git hook with the following commands:

@@ -765,6 +765,24 @@ func runSingleScan(ctx context.Context, cmd string, cfg engine.Config) (metrics,
 			PrintLegacyJSON:     *jsonLegacy,
 			TrustLocalGitConfig: *gitTrustLocalGitConfig,
 		}
+
+		// detect if trufflehog is running git source as a pre-commit hook
+		if isPreCommitHook() {
+			ctx.Logger().Info("Running as a pre-commit hook, overriding default flags for hook context")
+
+			// Override git configuration for pre-commit hook context
+			gitCfg.TrustLocalGitConfig = true
+			gitCfg.BaseRef = "HEAD" // Only scan staged changes
+
+			// Override result filters for pre-commit hook context
+			// In hook mode, we only want to show verified secrets and unknown findings
+			*results = "verified,unknown"
+
+			// Override failure behavior for pre-commit hook context
+			// In hook mode, we want to fail the commit if any secrets are found
+			*fail = true
+		}
+
 		if ref, err := eng.ScanGit(ctx, gitCfg); err != nil {
 			return scanMetrics, fmt.Errorf("failed to scan Git: %v", err)
 		} else {
@@ -1209,3 +1227,40 @@ func validateClonePath(clonePath string, noCleanup bool) error {

 	return nil
 }
+
+// isPreCommitHook detects if trufflehog is running as a pre-commit hook
+func isPreCommitHook() bool {
+	// Pre-commit.com framework detection
+	// Docs: https://pre-commit.com/#pre-commit
+	// Sets PRE_COMMIT=1 environment variable when running hooks
+	if os.Getenv("PRE_COMMIT") == "1" {
+		return true
+	}
+
+	// Husky framework detection (modern versions)
+	// Docs: https://typicode.github.io/husky/get-started.html#disabling-hooks
+	// Sets HUSKY=1 environment variable for all hooks
+	if os.Getenv("HUSKY") == "1" {
+		return true
+	}
+
+	// Husky legacy detection (versions < 4.0)
+	// Sets HUSKY_GIT_PARAMS for git hooks, containing commit parameters
+	// Reference: https://github.com/typicode/husky/tree/v0.14.3
+	if os.Getenv("HUSKY_GIT_PARAMS") != "" {
+		return true
+	}
+
+	// Local Git hook detection (non-framework)
+	// Native Git hooks don't set specific environment variables by default.
+	// To detect local hooks without frameworks, we must explicitly set
+	// an environment variable in the hook script:
+	// Example in .git/hooks/pre-commit:
+	//   export TRUFFLEHOG_PRE_COMMIT=1
+	// Than we can detect it
+	if os.Getenv("TRUFFLEHOG_PRE_COMMIT") == "1" {
+		return true
+	}
+
+	return false
+}