Add Mailgun Webhook Token detector

[asivaprasad09]

Summary

This PR adds a detector for Mailgun webhook signing tokens used to verify webhook payload signatures.

Key features:

• Detects 32-character hexadecimal tokens (case-insensitive)
• Requires "mailgun" keyword in nearby context to reduce false positives
• Implements CustomFalsePositiveChecker interface for additional validation
• Non-verifying detector (webhook tokens cannot be verified via API)
• Includes comprehensive test coverage

Changes

• Added MailgunWebhookToken (ID 1053) to proto/detector_type.proto
• Created detector implementation at pkg/detectors/mailgunwebhooktoken/
• Integrated detector into default detector list in pkg/engine/defaults/defaults.go
• Updated proto-generated files with new detector type
• Added comprehensive unit tests with 100% pass rate

Pattern Details

The detector uses a context-aware regex pattern:

mailgun.*\b([a-fA-F0-9]{32})(?:['"|\n\r\s\x60;]|$)

This requires "mailgun" to appear before the token to avoid false positives from generic 32-character hex strings commonly found in examples and test fixtures.

Testing

All tests pass successfully:

go test ./pkg/detectors/mailgunwebhooktoken -tags=detectors -v

Test coverage includes:

• Valid pattern detection in multiple contexts (env vars, assignments, config files)
• Case-insensitive hex matching (both uppercase and lowercase)
• Multiple tokens in the same file
• Deduplication of repeated tokens
• Rejection of invalid patterns (wrong length, non-hex characters, missing context)
• Proper detector type and keyword registration

Design Rationale

Why context-aware matching?
Mailgun webhook tokens are 32-character hex strings, a format shared by many other types of secrets (MD5 hashes, other webhook tokens, UUIDs without hyphens). Requiring "mailgun" in nearby context significantly reduces false positives while maintaining high recall for actual Mailgun tokens.

Why no verification?
Webhook signing tokens are used to verify HMAC signatures of incoming webhook payloads. They cannot be verified independently via an API call - they only prove valid when used to verify an actual webhook signature with the corresponding message body and timestamp. Therefore, this detector does not implement verification.

SecretParts Population

The detector properly populates SecretParts with:

SecretParts: map[string]string{"token": token}

And includes a rotation guide in ExtraData:

ExtraData: map[string]string{
    "rotation_guide": "https://help.mailgun.com/hc/en-us/articles/360018328934-How-can-I-verify-webhooks",
}

🤖 Generated with Claude Code

---

Note

Low Risk
Additive detector-only change with no auth or engine behavior changes beyond one more default scanner; main risk is extra findings or false positives on generic 32-hex strings near "mailgun".

Overview
Adds Mailgun webhook signing token detection as a new detector type (MailgunWebhookToken, ID 1053), separate from the existing Mailgun API key detector.

The scanner matches 32-character hex strings only when mailgun appears in nearby context (PrefixRegex), deduplicates hits, and emits results with SecretParts, a Mailgun rotation guide link, and no API verification (signing keys are not verifiable out of band). It also implements CustomFalsePositiveChecker via the shared default false-positive list.

Wiring includes registering the scanner in default detectors, extending detector_type.proto and generated protobuf enums, plus unit tests for pattern matching, keywords, and type registration.

^{Reviewed by Cursor Bugbot for commit c3e3f96. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit c3e3f96. Configure here.}

[cursor]

Overly broad keywords cause unnecessary detector invocations

Medium Severity

Keywords() returns ["mailgun", "webhook", "signing"] but the regex (via PrefixRegex) requires "mailgun" to be present in the data for any match. The keywords "webhook" and "signing" are extremely common words that will trigger this detector on many irrelevant chunks where no "mailgun" context exists, causing unnecessary regex processing that can never produce results. Only "mailgun" is needed as a keyword.

Additional Locations (1)

• pkg/detectors/mailgunwebhooktoken/mailgun_webhook_token.go#L22-L23

 

^{Reviewed by Cursor Bugbot for commit c3e3f96. Configure here.}