regexp

Active contributors: Zachary Rice, Richard Gomez

Purpose

regexp/ is a tiny package — two files totaling ~25 lines — that lets every other package compile regexes through a single import while the actual engine is selected at compile time via a Go build tag.

Directory layout

regexp/
├── stdlib_regex.go      # default; uses Go's standard regexp (RE2-based)
└── wasilibs_regex.go    # build tag `gore2regex`; uses wasilibs/go-re2 (WASM RE2)

Key abstractions

Symbol	File	Description
Version	both	Constant string identifying which backend is active ("stdlib" or "github.com/wasilibs/go-re2"). Logged at startup via cmd/root.go.
Regexp	both	Type alias for the chosen package's Regexp
MustCompile(s)	both	Wraps the chosen package's MustCompile

How it works

The two files use mutually exclusive build tags:

// stdlib_regex.go
//go:build !gore2regex

// wasilibs_regex.go
//go:build gore2regex

A normal go build produces a binary with the standard library backend. go build -tags gore2regex produces one with the wasilibs/go-re2 backend, which embeds a WebAssembly build of Google's RE2 library.

Both files declare the same exported symbols (Version, Regexp, MustCompile) so the rest of the codebase imports github.com/zricethezav/gitleaks/v8/regexp and never knows the difference.

Why two engines

Go's standard library regexp is RE2-based and has linear time complexity, which makes it safe against catastrophic backtracking. It's also pure Go and the most portable choice. wasilibs/go-re2, by embedding RE2 directly as WebAssembly, can be faster on certain workloads — particularly when the same patterns are evaluated many times — at the cost of bringing a WASM runtime into the binary.

The user-facing trade-off is documented in the gore2regex tag and surfaced in scan logs:

using <Version> regex engine

This is logged once at startup by initConfig in cmd/root.go.

Constraints

Both engines are RE2-based, so neither supports lookahead/lookbehind. The README is explicit about this when describing custom rules: "Note Golang's regex engine does not support lookaheads." Don't write rules that depend on lookarounds — they'll fail to compile under either backend.

Integration points

The package has no consumers other than the rest of Gitleaks itself. Every regex compilation in the codebase goes through regexp.MustCompile from this package — config/config.go, config/allowlist.go, detect/detect.go (newLineRegexp), detect/codec/encodings.go, sources/git.go (the SSH URL pattern), and the offline rule generator under cmd/generate/config/rules/.

Entry points for modification

• Adding a third backend: add a third file with a unique build tag, declare the same three symbols, and ensure it compiles standalone. Update CI to run the test matrix against the new tag.
• Switching the default: swap the build-tag conditions on the two files. The CI workflows (.github/workflows/test.yml) build with the default tag set, so changing it has wide impact.
• Wrapping with metrics: if you wanted to instrument regex compile or match calls, this is the chokepoint to do it without touching every call site. Each backend file would need to wrap MustCompile (and possibly the *Regexp type) accordingly.