Skip to content

Find, verify, and analyze leaked credentials

Mark results whose verification was skipped (#5448)

Dave Hubbard3bba824fbc1e
diff --git a/pkg/detectors/detectors.go b/pkg/detectors/detectors.go
index 8d5d97790..6146d4070 100644
--- a/pkg/detectors/detectors.go
+++ b/pkg/detectors/detectors.go
@@ -116,6 +116,14 @@ type Result struct {
// VerificationFromCache indicates whether this result's verification result came from the verification cache rather
// than an actual remote request.
VerificationFromCache bool
+ // VerificationSkipped indicates that the engine produced this result without attempting remote verification,
+ // either because verification was disabled for the result's source or detector, or because the engine withheld
+ // verification after multiple detectors matched the same secret. It lets consumers that measure verifier activity
+ // tell "the verifier did not run" apart from "the verifier ran and the credential did not verify". It is purely
+ // informational: Verified and the verification error keep whatever the detector or engine assigned, so a skipped
+ // result still reports as unverified (or with an overlap verification error) exactly as it would without this
+ // field.
+ VerificationSkipped bool
// Raw contains the raw secret identifier data. Prefer IDs over secrets since it is used for deduping after hashing.
Raw []byte
// RawV2 contains the raw secret identifier that is a combination of both the ID and the secret.
diff --git a/pkg/engine/engine.go b/pkg/engine/engine.go
index c7d9fafff..43c2703ab 100644
--- a/pkg/engine/engine.go
+++ b/pkg/engine/engine.go
@@ -1141,6 +1141,10 @@ func (e *Engine) verificationOverlapWorker(ctx context.Context) {
if e.verificationOverlapTracker != nil {
e.verificationOverlapTracker.Add(1)
}
+ // The overlap error stays the verdict; VerificationSkipped additionally records that no
+ // verifier ran, so consumers counting verifier outcomes don't read errOverlap as a provider
+ // failure.
+ res.VerificationSkipped = true
res.SetVerificationError(errOverlap)
e.processResult(
ctx,
@@ -1249,6 +1253,15 @@ func (e *Engine) detectChunk(ctx context.Context, data detectableChunk) {
resultsProduced.WithLabelValues(detectorNameStr).Add(float64(len(results)))
}
+ // With verification disabled for this chunk and detector, results carry whatever verdict the detector assigned
+ // without contacting the provider (normally unverified). Leave that verdict untouched and only record that the
+ // verifier never ran. Verifying paths, including cache hits, leave VerificationSkipped false.
+ if !data.verify {
+ for i := range results {
+ results[i].VerificationSkipped = true
+ }
+ }
+
detectorExecutionCount.WithLabelValues(
detectorNameStr,
sourceTypeStr,
diff --git a/pkg/engine/engine_test.go b/pkg/engine/engine_test.go
index 0612a31ff..fb2dab20e 100644
--- a/pkg/engine/engine_test.go
+++ b/pkg/engine/engine_test.go
@@ -21,6 +21,7 @@ import (
"google.golang.org/protobuf/testing/protocmp"
"pgregory.net/rapid"
+ "github.com/trufflesecurity/trufflehog/v3/pkg/cache/simple"
"github.com/trufflesecurity/trufflehog/v3/pkg/config"
"github.com/trufflesecurity/trufflehog/v3/pkg/context"
"github.com/trufflesecurity/trufflehog/v3/pkg/custom_detectors"
@@ -983,12 +984,13 @@ func TestProcessResult_AllFieldsCopied(t *testing.T) {
// Arrange: Create a Result
result := detectors.Result{
- DetectorType: detector_typepb.DetectorType(-1),
- ExtraData: map[string]string{"key": "value"},
- Raw: []byte("something"),
- RawV2: []byte("something:else"),
- Redacted: "someth***",
- Verified: true,
+ DetectorType: detector_typepb.DetectorType(-1),
+ ExtraData: map[string]string{"key": "value"},
+ Raw: []byte("something"),
+ RawV2: []byte("something:else"),
+ Redacted: "someth***",
+ Verified: true,
+ VerificationSkipped: true,
}
// Act
@@ -1005,6 +1007,7 @@ func TestProcessResult_AllFieldsCopied(t *testing.T) {
assert.Equal(t, []byte("something:else"), r.RawV2)
assert.Equal(t, "someth***", r.Redacted)
assert.True(t, r.Verified)
+ assert.True(t, r.VerificationSkipped)
assert.Equal(t, detector_typepb.DetectorType(-1), r.DetectorType)
assert.Equal(t, sources.SourceID(1), r.SourceID)
assert.Equal(t, sources.JobID(2), r.JobID)
@@ -1849,6 +1852,29 @@ func (p passthroughDetector) Keywords() []string { return p.keyw
func (p passthroughDetector) Type() detector_typepb.DetectorType { return p.detectorType }
func (p passthroughDetector) Description() string { return "fake detector for testing" }
+// fixedVerdictDetector reports the same verdict whether or not verification was requested, so tests can confirm the
+// engine passes verdicts through untouched while recording whether verification was attempted.
+type fixedVerdictDetector struct {
+ verified bool
+ verificationErr error
+}
+
+func (d fixedVerdictDetector) FromData(_ aCtx.Context, _ bool, data []byte) ([]detectors.Result, error) {
+ result := detectors.Result{
+ DetectorType: detector_typepb.DetectorType(-1),
+ Raw: data,
+ Verified: d.verified,
+ }
+ result.SetVerificationError(d.verificationErr)
+ return []detectors.Result{result}, nil
+}
+
+func (d fixedVerdictDetector) Keywords() []string { return []string{"keyword"} }
+func (d fixedVerdictDetector) Type() detector_typepb.DetectorType {
+ return detector_typepb.DetectorType(-1)
+}
+func (d fixedVerdictDetector) Description() string { return "fixed verdict detector for testing" }
+
type passthroughDecoder struct{}
func (p passthroughDecoder) FromChunk(chunk *sources.Chunk) *decoders.DecodableChunk {
@@ -1910,6 +1936,102 @@ func TestEngine_DetectChunk_UsesVerifyFlag(t *testing.T) {
}
}
+// TestEngine_DetectChunk_MarksVerificationSkippedWithoutChangingVerdict validates that detectChunk marks results
+// produced with verification disabled as VerificationSkipped, leaves results produced with verification enabled
+// unmarked, and in every case preserves the verdict (Verified and the verification error) the detector assigned.
+func TestEngine_DetectChunk_MarksVerificationSkippedWithoutChangingVerdict(t *testing.T) {
+ ctx := context.Background()
+
+ testCases := []struct {
+ name string
+ verify bool
+ detector fixedVerdictDetector
+ wantSkipped bool
+ }{
+ {name: "verify=false, unverified", verify: false, detector: fixedVerdictDetector{}, wantSkipped: true},
+ {name: "verify=false, detector reports verified", verify: false, detector: fixedVerdictDetector{verified: true}, wantSkipped: true},
+ {name: "verify=false, detector reports error", verify: false, detector: fixedVerdictDetector{verificationErr: fmt.Errorf("boom")}, wantSkipped: true},
+ {name: "verify=true, unverified", verify: true, detector: fixedVerdictDetector{}, wantSkipped: false},
+ {name: "verify=true, verified", verify: true, detector: fixedVerdictDetector{verified: true}, wantSkipped: false},
+ {name: "verify=true, error", verify: true, detector: fixedVerdictDetector{verificationErr: fmt.Errorf("boom")}, wantSkipped: false},
+ }
+
+ for _, tc := range testCases {
+ t.Run(tc.name, func(t *testing.T) {
+ // Arrange: Create a minimal engine with a passthrough verification cache.
+ e := &Engine{
+ results: make(chan detectors.ResultWithMetadata, 1),
+ verificationCache: verificationcache.New(nil, &verificationcache.InMemoryMetrics{}),
+ }
+
+ // Arrange: Create a detector match. We can't create one directly, so we have to use a minimal A-H core.
+ ahcore := ahocorasick.NewAhoCorasickCore([]detectors.Detector{tc.detector})
+ detectorMatches := ahcore.FindDetectorMatches([]byte("keyword"))
+ require.Len(t, detectorMatches, 1)
+
+ // Act
+ e.detectChunk(ctx, detectableChunk{
+ detector: detectorMatches[0],
+ verify: tc.verify,
+ wgDoneFn: func() {},
+ })
+ close(e.results)
+
+ // Assert: The skip marker reflects whether verification was attempted, and the verdict is unchanged.
+ result, ok := <-e.results
+ require.True(t, ok, "expected a result but did not get one")
+ assert.Equal(t, tc.wantSkipped, result.VerificationSkipped)
+ assert.Equal(t, tc.detector.verified, result.Verified)
+ if tc.detector.verificationErr == nil {
+ assert.NoError(t, result.VerificationError())
+ } else {
+ assert.EqualError(t, result.VerificationError(), tc.detector.verificationErr.Error())
+ }
+ })
+ }
+}
+
+// TestEngine_DetectChunk_CacheHitIsNotVerificationSkipped validates that a verdict served from the verification cache
+// is not marked VerificationSkipped: a cache hit replays an earlier real verification rather than skipping it, and
+// consumers distinguish the two cases with VerificationFromCache.
+func TestEngine_DetectChunk_CacheHitIsNotVerificationSkipped(t *testing.T) {
+ ctx := context.Background()
+
+ // Arrange: Create a minimal engine whose verification cache actually stores results.
+ e := &Engine{
+ results: make(chan detectors.ResultWithMetadata, 2),
+ verificationCache: verificationcache.New(simple.NewCache[detectors.Result](), &verificationcache.InMemoryMetrics{}),
+ }
+
+ // Arrange: Create a detector match. We can't create one directly, so we have to use a minimal A-H core.
+ ahcore := ahocorasick.NewAhoCorasickCore([]detectors.Detector{fixedVerdictDetector{verified: true}})
+ detectorMatches := ahcore.FindDetectorMatches([]byte("keyword"))
+ require.Len(t, detectorMatches, 1)
+ chunk := detectableChunk{
+ detector: detectorMatches[0],
+ verify: true,
+ wgDoneFn: func() {},
+ }
+
+ // Act: The first pass verifies and populates the cache; the second is served from it.
+ e.detectChunk(ctx, chunk)
+ e.detectChunk(ctx, chunk)
+ close(e.results)
+
+ // Assert
+ first, ok := <-e.results
+ require.True(t, ok, "expected a first result")
+ second, ok := <-e.results
+ require.True(t, ok, "expected a second result")
+
+ assert.False(t, first.VerificationFromCache)
+ assert.True(t, second.VerificationFromCache)
+ for _, result := range []detectors.ResultWithMetadata{first, second} {
+ assert.False(t, result.VerificationSkipped)
+ assert.True(t, result.Verified)
+ }
+}
+
// TestEngine_ScannerWorker_DetectableChunkHasCorrectVerifyFlag validates that scannerWorker generates detectableChunk
// structs that have the correct verify flag set. It also validates that the original chunks' SourceVerify flags are
// unchanged.
@@ -2022,10 +2144,16 @@ func TestEngine_VerificationOverlapWorker_DetectableChunkHasCorrectVerifyFlag(t
close(e.detectableChunksChan)
close(processedDetectableChunks)
- // Assert: Confirm that every generated result is unverified (because overlap detection precluded it).
+ // Assert: Confirm that every generated result is unverified (because overlap detection precluded it), keeps the
+ // overlap error as its verdict, and is marked as never having been verified.
+ var overlapResults int
for result := range e.results {
+ overlapResults++
assert.False(t, result.Verified)
+ assert.EqualError(t, result.VerificationError(), errOverlap.Error())
+ assert.True(t, result.VerificationSkipped)
}
+ assert.NotZero(t, overlapResults, "expected the overlap path to emit at least one result")
// Assert: Confirm that every generated detectable chunk's Chunk.SourceVerify flag is unchanged and that its
// verify flag is correctly set.