Picket Compatibility Ledger

This ledger records intentional differences from the pinned Gitleaks reference. Each entry must have an oracle or regression test before the behavior is treated as deliberate.

Native Contextual Predicates

• Upstream behavior: The pinned Gitleaks config schema has allowlists but does not provide source and finding expression predicates.
• Picket behavior: Native configs can define bounded global and per-rule prefilter and filter expressions over a closed field set. Strict Gitleaks-compatible scans preserve those config fields but leave them inert.
• Mode/profile affected: Picket-native scan, rules check, rules test, and compatibility commands only when --profile picket is selected.
• Reason: Native rule packs need deterministic contextual false-positive controls without introducing a scripting runtime or changing compatibility allowlist semantics.
• User impact: A native predicate can skip a source, skip one rule, or suppress a candidate. The same config field does not change strict scan results.
• Test name: GlobalPrefilterAppliesOnlyWhenNativePredicatesAreEnabled, NativeFilterRunsBeforeRequiredRuleCorrelation, NativeScanEvaluatesPredicatesWithoutAffectingCompatibilityScan.
• Migration guidance: Continue using Gitleaks allowlists for strict compatibility. Use predicates only in configs intended for Picket-native scans.

Diagnostics Output

• Upstream behavior: Gitleaks --diagnostics=cpu,mem,trace writes Go profiler artifacts (cpu.pprof, mem.pprof, trace.out), and --diagnostics=http starts a local pprof server.
• Picket behavior: Picket --diagnostics=cpu,mem,trace writes AOT-safe structured diagnostics (cpu.json, mem.json, trace.jsonl) to --diagnostics-dir or the current directory. --diagnostics=http starts a loopback-only diagnostics server on a random local port and writes a tokened startup URL to stderr, but serves Picket JSON/JSONL snapshots instead of Go pprof profiles.
• Mode/profile affected: Gitleaks-compatible CLI commands.
• Reason: Go pprof artifacts are not a native .NET diagnostic format. Picket’s default Native AOT artifact needs deterministic, trim-safe, low-risk diagnostics that do not require dynamic runtime infrastructure.
• User impact: Automation that only needs the flag to collect local diagnostics works, and http mode exposes live CPU, heap, and trace snapshots while the process is running to callers that use the printed URL. Consumers expecting Go pprof file or wire formats need to use Picket’s JSON/JSONL diagnostics instead.
• Test name: DirectoryScanWritesDiagnosticsArtifacts, StdinScanServesHttpDiagnostics, DirectoryScanRejectsHttpDiagnosticsDirectory, DirectoryScanRejectsMixedHttpDiagnostics.
• Migration guidance: Use --diagnostics=cpu,mem,trace with --diagnostics-dir <dir> and collect cpu.json, mem.json, and trace.jsonl, or use --diagnostics=http and read the printed tokened URL, then follow the endpoint paths listed in the index.

Native Google API Key Coverage

• Upstream behavior: The pinned Gitleaks gcp-api-key rule detects Google API key shapes but also carries rule allowlists for several example-looking values in the embedded Gitleaks config.
• GitHub behavior: GitHub Secret Protection is a hosted proprietary oracle. Its secret scanning alerts classify the same credential family as google_api_key and can flag values that Gitleaks suppresses as compatibility allowlist examples.
• Picket behavior: Strict Gitleaks-compatible scans keep the Gitleaks allowlist behavior. Native scans include picket-google-api-key in the picket-default rule pack and picket-* rule packs do not inherit Gitleaks compatibility global allowlists.
• Mode/profile affected: Picket-native scan and --profile picket.
• Reason: Native coverage should track modern hosted scanner expectations where that can be done locally and safely, while strict compatibility must not change Gitleaks results.
• User impact: Native scans may report Google API key examples that strict Gitleaks-compatible scans suppress through rule-specific or global compatibility allowlists. The finding uses a Picket rule ID, provider metadata, and offline structural validation.
• Test name: ScanSeparatesNativeGoogleApiKeyDetectionFromGitleaksAllowlist.
• Migration guidance: Use strict compatibility commands for Gitleaks byte parity. Use native scan when comparing to hosted GitHub secret scanning alerts or when richer Picket metadata is preferred.

Native GitHub Token Coverage

• Upstream behavior: The pinned Gitleaks default config includes GitHub App, OAuth, refresh, fine-grained PAT, and classic PAT rules under github-* rule IDs, with Gitleaks metadata and selected compatibility allowlists.
• Picket behavior: Strict Gitleaks-compatible scans keep those upstream github-* rules unchanged. The embedded native default disables the inherited GitHub token rules and replaces them with picket-github-* rules in picket-default, including Picket provider metadata, remediation links, and offline/live validation support.
• Mode/profile affected: Picket-native scan, verify, and analyze when no target-local or environment config replaces the embedded native default.
• Reason: Native findings should be stable Picket records with Picket-owned rule IDs and metadata, while strict compatibility must continue to report the pinned Gitleaks IDs.
• User impact: Native default scans report GitHub token findings once under picket-github-* IDs instead of duplicating them under both native and compatibility IDs. Custom configs that explicitly define github-* rules are still validated and verified.
• Test name: PicketConfigLoaderEmbeddedDefaultUsesNativeGitHubRules, NativeScanUsesEmbeddedGitHubPersonalAccessTokenRule.
• Migration guidance: Use strict compatibility commands for exact Gitleaks rule identity. Use native scan, verify, or analyze for Picket metadata, validation states, and stable native rule IDs.

Native Sourcegraph Token Coverage

• Upstream behavior: The pinned Gitleaks sourcegraph-access-token rule can report either prefixed sgp_ Sourcegraph tokens or any 40-hex value when a Sourcegraph keyword appears in the same scan fragment.
• Picket behavior: Strict Gitleaks-compatible scans keep the inherited sourcegraph-access-token rule unchanged. The embedded native default disables that inherited rule and replaces it with picket-sourcegraph-access-token, which requires the sgp_ token prefix.
• Mode/profile affected: Picket-native scan, verify, and analyze when no target-local or environment config replaces the embedded native default.
• Reason: Native defaults should avoid reporting ordinary commit hashes as access tokens while keeping strict Gitleaks compatibility intact.
• User impact: Native default scans no longer report bare 40-hex hashes as Sourcegraph credentials. Prefixed Sourcegraph access tokens still produce findings with Picket-owned rule metadata.
• Test name: ScanUsesNativeSourcegraphAccessTokenRule, ScanSkipsBareCommitHashForNativeSourcegraphAccessTokenRule, ScanFindsNativeSourcegraphAccessToken.
• Migration guidance: Use strict compatibility commands for pinned Gitleaks behavior. Use native scan, verify, or analyze for lower-noise Sourcegraph token detection.

Native C# String-Literal Concatenation

• Upstream behavior: Gitleaks scans source bytes and does not evaluate C# string-literal concatenations before matching.
• GitHub behavior: GitHub Secret Protection can alert on credentials built from deterministic source-code string literals.
• Picket behavior: Strict Gitleaks-compatible scans keep byte-oriented Gitleaks behavior. Native .cs scans evaluate literal-only string.Concat(...) calls and binary + literal chains as derived input, then attach csharp-string-concat decode provenance to any findings.
• Mode/profile affected: Picket-native scan, verify, analyze, and rules test when the logical path ends in .cs.
• Reason: Native hosted-alert parity should catch simple split literals without requiring live services, dynamic code, or a general C# compiler.
• User impact: Native scans can report additional findings in C# source when a credential is split across deterministic string literals. Findings point to the literal construction span; hosted scanners may report a downstream call site for the same secret. Hosted historical alerts should be compared against native git-history reports, not current-tree filesystem scans, because GitHub alert locations include the commit that introduced the secret.
• Test name: ScanFindsNativeRuleMatchInCSharpStringConcat.
• Migration guidance: Use strict compatibility commands for Gitleaks byte parity. Use native scan when source-code literal normalization is desired.

Native UTF-16 Input

• Upstream behavior: Gitleaks treats BOM-marked UTF-16 files as binary when its NUL-byte probe applies.
• Picket behavior: Native scans decode BOM-marked UTF-16 LE and BE with replacement fallback for malformed code units. Strict compatibility keeps Gitleaks binary-file behavior.
• Mode/profile affected: Picket-native filesystem, baseline, and standard input scans.
• Reason: Source files and generated configuration can use UTF-16 while native report coordinates still require decoded Unicode positions.
• User impact: Native scans can produce findings from UTF-16 sources. Report evidence is decoded text, while size limits and blobSha256 use the original encoded bytes.
• Test name: ScanDecodesBomMarkedUtf16OnlyInNativeMode, NativeScanDecodesSmallUtf16File, NativeFragmentedScanDecodesUtf16WithoutChangingCompatibility.

Native Git Working-Tree Changes

• Upstream behavior: Gitleaks exposes staged compatibility scanning but does not combine staged, unstaged, and untracked snapshots in one command.
• Picket behavior: picket scan --git-changes <path> scans the Git index, unstaged working-tree files, and untracked non-ignored files. Shared stable findings are paired by occurrence and retain explicit combined provenance. Strict compatibility commands and hooks keep staged-only behavior.
• Mode/profile affected: Picket-native scan.
• Reason: Developers need one deterministic review of pending work without conflating it with the exact staged content enforced by pre-commit hooks.
• User impact: A changed file can produce separate index and working-tree findings when its snapshots differ. Native reports identify git-index, git-worktree, git-untracked, or git-index+worktree provenance.
• Test name: NativeGitChangesScanMergesSharedFindingsAndPreservesUniqueSnapshots, NativeGitChangesScanPreservesRepeatedFindingOccurrences, CompatibilityStagedScanRemainsStagedOnly.
• Migration guidance: Use picket git --staged or installed hooks to guard the next commit. Use picket scan --git-changes . to review all pending work.

Git Log Option Guard

• Upstream behavior: Gitleaks forwards --log-opts tokens to git log after shell-style splitting.
• Picket behavior: Picket accepts plain revision ranges and a small allowlist of safe revision-filter options, but rejects output, pager, external-diff, and unknown option-shaped tokens before git starts.
• Mode/profile affected: picket git.
• Reason: git log options such as --output=<path> can create or overwrite files even though Picket correctly avoids shell execution.
• User impact: Common ranges such as main..HEAD and safe filters such as --all, --branches, --tags, --since, --author, --grep, and --max-count remain usable. Workflows that relied on arbitrary git log options need an explicit Picket feature instead.
• Test name: EnumerateRejectsUnsafeLogOptionsWithoutCreatingOutput.
• Migration guidance: Pass revision ranges directly through --log-opts. Avoid using --log-opts as a general git log escape hatch.

Local extend.path Resolution

• Upstream behavior: The pinned Gitleaks loader passes local [extend] path values to Viper as local file paths. Absolute paths are accepted, and relative paths resolve from the process current working directory.
• Picket behavior: Strict compatibility keeps the same local-file path semantics. Picket adds a 10 MiB per-file read cap, a two-level extend-depth cap, and cycle detection.
• Mode/profile affected: Gitleaks-compatible config loading.
• Reason: Existing Gitleaks configs can rely on this path resolution model. Changing it in compatibility mode would make otherwise-valid configs fail or load different base rules.
• User impact: Target-local configs that contain local extend.path values are trusted scanner configuration. They are not confined to the scan root. Native config loading can add a stricter mode later, but strict compatibility must preserve the pinned oracle behavior.
• Test name: LoadFileExtendsPathAndMergesRuleOverrides, LoadFileRejectsExtendPathCycles, LoadFileRejectsOversizedExtendedConfig.
• Migration guidance: Prefer explicit absolute paths or run Picket from the expected working directory when using relative extend.path values. Treat repository-provided configs the same way you treat any executable CI scanner configuration.