foam-otel 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82f1791c9e7d9929a655760c4e2f67295bb70f55dee75a2738bfcae33f5658f6
-  data.tar.gz: 16917b6e7a4e1dc1f0c6160f7026d4fe90c6213a16fa0664807e459359c5ea92
+  metadata.gz: 180e8af99c1f5c9bfc35de221c4985fb3ebac7b52ddf6fc99d6552a52aaea836
+  data.tar.gz: 14a5d81c673af1a20a75e483e076d2c6b1820fa14e5a587e2a23451da3cccf77
 SHA512:
-  metadata.gz: 38df8e89604a42d3db4698f5f12934f2bf3e25e288124caf10694a0e698e50f3a732fdd9f1dd2455fb52af90777cba00a3e825f23b967817d6fbda25b567fbdf
-  data.tar.gz: 5034a35f4d3a7c9d1f18fb0e7adc6691e75aacf0130eb74312ce14ad0ab902e787a25b75af45d6f618cd70a13df12b8323fc172d1cb0abee2950991bb839db6d
+  metadata.gz: a307d175e903abbbbd1c382e65694664f47aba18408fc7153f9a43e9fb72f8131fedcfc71a59e16ee4f7446dee0f3460233883f96a7048e1284fff75b54e16c7
+  data.tar.gz: 7322e0a91e04092d494150ad9b003e4a6fd61b23ebc7468a8c715eec2d5ab8aac64d1edc4c9fb3cb1a844c3d3a56c167b9bbf05bed2bb1d4cb491eba20695f5d

data/GOTCHAS.md

@@ -582,6 +582,59 @@ anthropic 1.59.0, gemini-ai 4.3.0, ruby_llm 1.16.0).
   rack end-to-end with real `traceparent`+`baggage` headers, the no-op and
   never-raise cases.
 
+## F13: The value-pattern secret layer + coverage fix + TLS pin (1.4.0, security ruling 2026-07-27)
+
+The credential floor masks by NAME and is value-shape-blind; a live secret
+under an innocuous key (`note`, `detail`) sailed past it. Foam telemetry is
+read downstream by LLMs, so ONE leaked credential is prompt-injection
+exfiltratable — the value-pattern secret layer is the required second control
+(`docs/decisions/security-fixes-design.md` CONTRACT V).
+
+- **What / where**: `Redaction.scan_value_secrets` masks credential-SHAPED
+  spans (`SECRET_VALUE_RULES` + the PEM/PuTTY linear scans + the H1/H2
+  heuristics) to `[REDACTED]` in EVERY leaf string the engine walks —
+  attribute values, `status.message`, exception events, log bodies (string +
+  structured leaves), SQL, LLM content (BEFORE serialization, F-RB2), URL
+  query AND fragment pair values (Contract C1), resource identity strings
+  (once at build), exemplar `filtered_attributes`. It rides the SAME exporter-
+  boundary seam as the floor — one pass, ordered floor → C1 tokenizer → value
+  scan → user keys, each hit terminal (`redaction.rb` `mask_one`/
+  `redact_leaf_string`). METRIC DATAPOINT ATTRIBUTES are the one mandated
+  exemption (`metrics.rb`/`mask_metric_data` pass `value_scan: false`) —
+  low-cardinality by construction; a value mask there would break aggregation
+  dimensions.
+- **Non-disableable Tier 1**: the rules are frozen module constants, not
+  Config — no config path can narrow them (same posture as the floor). ONLY
+  the H1/H2 heuristic tier honors `secret_heuristics: false`, logged loud at
+  init.
+- **ReDoS-bounded / fail-closed**: compile-once, a lowercase-literal anchor
+  pre-filter (no anchor → zero regexes), a 256 KiB value cap (oversize +
+  anchor ⇒ whole-value mask, never regex-scanned), a match-flood cap, a
+  256-pair query/fragment cap, a per-Regexp `timeout:` on Ruby ≥ 3.2. ANY
+  scanner fault (timeout included) masks the value, never a raw pass-through.
+- **F-RB1 TLS pin (CWE-295)**: the vendored OTLP exporter honored
+  `OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE` as a PRESENCE check — one env var
+  would silently strip cert verification off the token-bearing export
+  connection. Every exporter constructor (door 1 `pipelines.rb`, door 2
+  `ingest.rb`) now pins `ssl_verify_mode: OpenSSL::SSL::VERIFY_PEER`; the var
+  is INERT and warned about (`init.rb` `warn_inert_ssl_verify_none`). There is
+  no foam option to weaken it.
+- **Mitigation**: `lib/foam/otel/constants.rb` (the frozen ruleset),
+  `lib/foam/otel/redaction.rb` (the engine + coverage tokenizer),
+  `lib/foam/otel/pipelines.rb` + `lib/foam/otel/ingest.rb` (the TLS pin),
+  `lib/foam/otel/llm.rb` (C4 pre-serialization masking).
+- **Sources**: `docs/decisions/security-fixes-design.md`;
+  gitleaks/detect-secrets/secretlint provenance in `THIRD-PARTY-NOTICES`;
+  vendored exporter presence-check at
+  opentelemetry-exporter-otlp `exporter.rb:39-47`.
+- **Test**: `spec/value_secret_layer_spec.rb` (the per-rule corpus, caps,
+  precedence, coverage contract, off-surface pin, structural gates),
+  `spec/security_regressions_spec.rb` (F-RB1 + F-RB2 verbatim repros),
+  `spec/vuln_suite_spec.rb` (the adversarial exfil/ReDoS/bypass suite +
+  mutation spot-checks).
+
+---
+
 ## General gotchas (applicable to Ruby)
 
 - **G1 — init after target import / pre-init no-op**: the API's proxy providers

data/README.md

@@ -4,12 +4,15 @@ Foam's OpenTelemetry core for Ruby services. A thin, safe wrapper over the
 official OpenTelemetry libraries: foam owns the pipeline (providers, batch
 processors, OTLP export to the foam fleet endpoint), turns on automatic
 tier-1/2 instrumentation, and hands you a small set of never-throw helpers —
-and nothing else. **Redaction is fully opt-in above one always-on exception:
-by default foam captures every value RAW** (no value-pattern masking, no PII
-preset) **except the credential floor** — a fixed list of credential/secret
-header and field NAMES that is always masked to `[REDACTED]` (see "The
-default credential denylist" below); you enumerate any further fields to mask
-via `redact_keys`/`redact_pii_keys`.
+and nothing else. **Redaction is fully opt-in above two always-on exceptions:
+by default foam captures every value RAW** (no PII preset) **except (1) the
+credential floor** — a fixed list of credential/secret header and field NAMES
+always masked to `[REDACTED]` (see "The default credential denylist" below) —
+**and (2) the value-pattern secret layer** — credential-SHAPED value spans
+(cloud keys, tokens, JWTs, private-key blocks, `user:pass@` URLs…) masked to
+`[REDACTED]` regardless of field name (see "The value-pattern secret layer"
+below); you enumerate any further fields to mask via
+`redact_keys`/`redact_pii_keys`.
 
 Built to `docs/BASE_PACKAGE_SPEC.md`. This README is the manual you integrate
 from.
@@ -147,6 +150,7 @@ API):** the allowlist must include BOTH headers —
 | `additional_instrumentations:` | Array | no | `[]` | Constructed tier-2 instrumentation instances to register (fault-isolated: one that throws is skipped with a `[foam]` warning). |
 | `ignored_outbound_hosts:` | Array<String> | no | `[]` | Hosts whose outbound calls produce no spans — EXTENDS the built-in export-loop guard. For a co-resident agent's intake or a tenant exporter's endpoint. Applies to the clients whose official instrumentation supports host suppression: **Net::HTTP and Excon**. Faraday/HTTP (httprb)/HTTPX have no upstream `untraced_hosts` option — foam warns loudly at init when one of those is bundled (GOTCHAS G13); foam's own export loop is guarded for every client regardless. |
 | `diagnostics:` | Boolean | no | false | Verbose `[foam]` self-reporting of init/health. Warnings and errors are always loud regardless. |
+| `secret_heuristics:` | Boolean | no | true | The value-pattern secret layer's HEURISTIC tier (generic keyword+entropy detection, see "The value-pattern secret layer"). `false` disables ONLY the heuristics — the named provider patterns, the credential floor and the redaction-coverage contract have no off switch. Disabling logs one loud `[foam]` line at init (an explicit, audited decision for telemetry whose legitimate values collide with the heuristics). |
 
 Examples for the remaining options (each is runnable as-is):
 
@@ -157,6 +161,16 @@ Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: EN
                 redact_pii_keys: %w[customer_email full_name])               # fully [REDACTED]
 ```
 
+```ruby
+# Only if your legitimate telemetry collides with the generic secret
+# heuristics (e.g. base64 content-addressed ids masked as high-entropy
+# tokens): disable the HEURISTIC tier only. The named provider patterns and
+# the credential floor stay on — they have no off switch. Logs one loud
+# [foam] line.
+Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: ENV.fetch("FOAM_OTEL_TOKEN"),
+                secret_heuristics: false)
+```
+
 ```ruby
 # Constructed tier-2 instrumentation instances (fault-isolated; one that
 # throws is skipped with a [foam] warning, never a crashed boot):
@@ -242,10 +256,11 @@ floor name in `redact_keys` does NOT downgrade it to a tail mask — the floor
 is terminal. `enabled: false` stays fully inert exactly as before (nothing
 exports at all — the floor masks data that leaves; inert mode has none).
 
-**Everything else stays RAW.** The floor matches NAMES only — it never scans
-values: bodies, query values, SQL text, LLM content, and PII under unlisted
-names export byte-identical raw, exactly as documented everywhere else in
-this README.
+**Everything else stays RAW — above the floor and the value layer.** The
+floor matches NAMES only, never values. Credential-SHAPED value spans are the
+value-pattern secret layer's job (next section); UNSHAPED values — bodies,
+query values, SQL text, LLM content, and PII under unlisted names — export
+byte-identical raw, exactly as documented everywhere else in this README.
 
 **Why.** Coverage-over-masking remains the mission, but raw `Authorization`
 headers, cookies, and API keys on the wire are a breach in waiting for every
@@ -278,6 +293,78 @@ concept in every core — the floor itself has NO init surface anywhere):
 
 ---
 
+## The value-pattern secret layer (always-on)
+
+The credential floor masks by NAME and is deliberately value-shape-blind — a
+live AWS key under the field name `note` would sail past it. Foam telemetry is
+read downstream by LLMs, so a leaked credential is exfiltratable by prompt
+injection; "no leakage at all" is the bar. The value-pattern secret layer is
+the second always-on control (fleet ruling 2026-07-27,
+`docs/decisions/security-fixes-design.md`):
+
+**What it masks.** Credential-SHAPED value spans, regardless of the field
+name they hide under: AWS access-key ids and keyword-anchored AWS secrets,
+GCP API keys, Azure client/storage secrets, GitHub tokens and fine-grained
+PATs, GitLab tokens, Slack tokens + webhooks, Stripe secret keys
+(publishable `pk_` keys are deliberately NOT masked), JWTs, PEM private-key
+blocks (`-----BEGIN … PRIVATE KEY` — a truncated block masks to the end of
+the value, fail-closed; `PUBLIC KEY`/`CERTIFICATE` blocks never match) and
+PuTTY PPK keys, `scheme://user:pass@` URI credentials (the whole userinfo,
+username included), `Bearer`/`Basic` auth values, and Anthropic/OpenAI API
+keys. The matched span becomes the literal `[REDACTED]` — no tail, no
+prefix, zero reconstructable bytes; surrounding text keeps its diagnostic
+value (`conn to postgres://[REDACTED]@db:5432 refused`).
+
+**The heuristic tier** additionally catches the long tail: a
+keyword-anchored generic pass (`password = hunter2SecretXyz99` inside a log
+body masks its value — gitleaks-derived, entropy-gated, with placeholder/
+stopword/key-context false-positive suppression) and a whole-value
+high-entropy base64 token pass (detect-secrets-derived; pure hex and UUIDs
+are deliberately exempt — trace ids and digests are telemetry's ambient
+vocabulary). Only this tier is disableable: `secret_heuristics: false`
+(one loud `[foam]` line; the named patterns above are not configurable).
+
+**Where it runs.** Every value-bearing string on every export path, both
+doors: span/event/link attribute values, `status.message`, exception
+messages, log bodies (string and structured leaves), SQL (`db.statement`),
+LLM content (BEFORE serialization and again at the boundary), URL query AND
+fragment pair values, baggage-derived attributes, exemplar
+`filtered_attributes`, and resource identity strings (once, at init).
+Metric datapoint attributes (metric labels) are the one exempt surface —
+low-cardinality by construction; a value mask there would break your
+aggregation dimensions.
+
+**Bounded by design.** Compile-once rules, a literal-anchor pre-filter (no
+anchor in the value → zero regexes run), a 256 KiB value cap (an oversized
+value with an anchor hit anywhere masks WHOLE, fail-closed; without one it
+passes untouched), a match-flood cap, a 256-pair query/fragment tokenizer
+cap, and a per-Regexp timeout on Ruby ≥ 3.2. ANY scanner fault masks the
+value rather than shipping it raw.
+
+**Provenance.** The ruleset derives from MIT/Apache-licensed OSS secret
+scanners (gitleaks, detect-secrets, secretlint) — see `THIRD-PARTY-NOTICES`.
+Rules are frozen module constants, byte-consistent across the foam cores,
+changed only by fleet ruling.
+
+> **Migration note — 1.4.0 (minor): value-pattern secret masking + redaction
+> coverage fix + TLS pin.** foam now masks credential-SHAPED values
+> (AWS/GCP/Azure keys, GitHub/GitLab tokens, Slack, Stripe, Anthropic/OpenAI
+> keys, JWTs, private-key blocks, `user:pass@` URI credentials, bearer/basic
+> tokens) to `[REDACTED]` in every exported string value — regardless of
+> field name — plus a generic keyword+entropy heuristic you can disable with
+> `secret_heuristics: false` (the named patterns and the credential floor
+> cannot be disabled). Redaction now also reaches URL FRAGMENTS (OAuth
+> implicit-flow tokens, hash-router params), bare `k=v` pair lists, nested
+> attribute containers (fail-closed), and structured LLM content BEFORE
+> serialization. Query/fragment tokenizing is capped at 256 pairs (the
+> overflow remainder masks whole). Metric labels are not value-scanned. TLS
+> peer verification is now PINNED on every exporter:
+> `OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE` is INERT and loudly warned about.
+> If a dashboard keyed off a raw token value (it should not have), it will
+> now see `[REDACTED]`.
+
+---
+
 ## The helpers
 
 All helpers never raise, and no-op silently before `init` and when disabled.
@@ -668,6 +755,7 @@ end
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | INERT — foam wires ONE resolved endpoint into all three exporters explicitly, so per-signal endpoint vars never redirect (or split) foam's export. Set → loud `[foam]` warning that it is inert. |
 | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | INERT — as above (warns when set). |
 | `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | INERT — as above (warns when set). |
+| `OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE` | INERT — foam pins TLS peer verification (`ssl_verify_mode: VERIFY_PEER`) on every exporter constructor, both doors, so this vendored-exporter knob can never strip certificate verification off the credential-bearing export connection (1.4.0 security fix, CWE-295). Set → loud `[foam]` warning that it is inert; fix the trust chain (CA bundle) instead. |
 | every other `OTEL_*` | INERT — `OTEL_SERVICE_NAME` / `OTEL_RESOURCE_ATTRIBUTES` never override the init-declared identity; sampler/exporter/span-limit vars are ignored. |
 
 ---

data/THIRD-PARTY-NOTICES

@@ -20,6 +20,33 @@ filter_parameters (MIT). Mask FORMATS are facts, not copyrightable; no code
 was copied. None of these libraries is a runtime dependency of foam-otel.
 Provenance: RESEARCH.md.
 
+The VALUE-PATTERN SECRET LAYER ruleset (lib/foam/otel/constants.rb —
+SECRET_VALUE_RULES, SECRET_HEURISTIC_H1/H2, SECRET_VALUE_PLACEHOLDERS,
+SECRET_VALUE_STOPWORDS, SECRET_KEY_CONTEXT_ALLOWLIST; fleet ruling 2026-07-27,
+docs/decisions/security-fixes-design.md CONTRACT V) is likewise COPIED
+KNOWLEDGE derived from permissively-licensed open-source secret scanners, not
+vendored code (rule 38). Regex facts about public token formats are not
+copyrightable; the safe posture is followed anyway — every pattern derives
+from the MIT/Apache source text below or from the vendor's own public token
+format. None of these tools is a runtime dependency of foam-otel.
+
+  gitleaks       — MIT        — https://github.com/gitleaks/gitleaks (commit b58d3f1)
+                   (aws/gcp/azure/github/gitlab/slack/stripe/jwt/openai token
+                    shapes; the generic-api-key H1 template; the placeholder +
+                    stopword + key-context allowlists)
+  detect-secrets — Apache-2.0 — https://github.com/Yelp/detect-secrets (commit 5e14193)
+                   (the Base64HighEntropyString H2 entropy tier; several
+                    provider prefixes and the all-numeric entropy penalty)
+  secretlint     — MIT        — https://github.com/secretlint/secretlint (commit 7da613e)
+                   (bounded-JS-regex authoring discipline; the DB
+                    connection-string / URI-userinfo shape; the anthropic key
+                    shape)
+
+  trufflehog (AGPL-3.0) was consulted ONLY as a provider-coverage CHECKLIST —
+  NO pattern is transcribed from its source. Recorded deliberate: the AGPL
+  GCP service-account JSON pattern is NOT adopted; that secret is covered by
+  the private-key-block linear scan over its embedded PEM instead.
+
 Direct runtime dependencies (name version — license — repository):
 
   opentelemetry-api 1.11.0 — Apache-2.0 — https://github.com/open-telemetry/opentelemetry-ruby

data/lib/foam/otel/config.rb

@@ -12,7 +12,7 @@ module Foam
     Config = Struct.new(
       :name, :environment, :version, :enabled,
       :redact_keys, :redact_pii_keys, :ignored_outbound_hosts,
-      :diagnostics, :endpoint,
+      :diagnostics, :endpoint, :secret_heuristics,
       keyword_init: true
     )
 
@@ -24,7 +24,8 @@ module Foam
           name: "", environment: "", version: nil, enabled: false,
           redact_keys: [].freeze, redact_pii_keys: [].freeze,
           ignored_outbound_hosts: [].freeze,
-          diagnostics: false, endpoint: FOAM_OTEL_ENDPOINT
+          diagnostics: false, endpoint: FOAM_OTEL_ENDPOINT,
+          secret_heuristics: true
         ).freeze
       end
 
@@ -36,7 +37,7 @@ module Foam
 
       def resolve_config(name:, environment:, version:, enabled:,
                          redact_keys:, redact_pii_keys:, ignored_outbound_hosts:,
-                         diagnostics:, endpoint:)
+                         diagnostics:, endpoint:, secret_heuristics: true)
         Config.new(
           name: name,
           environment: environment,
@@ -51,7 +52,14 @@ module Foam
           redact_pii_keys: downcase_list(redact_pii_keys),
           ignored_outbound_hosts: Array(ignored_outbound_hosts).map { |h| h.to_s.downcase }.freeze,
           diagnostics: diagnostics ? true : false,
-          endpoint: endpoint
+          endpoint: endpoint,
+          # The value-pattern layer's HEURISTIC tier opt-out (security-fixes-
+          # design §V.8): false disables H1/H2 ONLY — the named Tier-1
+          # patterns, the credential floor and the coverage contract are
+          # module-constant machinery no config shape can narrow. Anything
+          # but literal false means ON (default-on preserves the fleet's
+          # no-leakage bar; disabling is an explicit, audited decision).
+          secret_heuristics: secret_heuristics == false ? false : true
         ).freeze
       end
 
@@ -61,12 +69,14 @@ module Foam
         Array(list).map { |k| k.to_s.downcase }.reject(&:empty?).uniq.freeze
       end
 
-      # A second init() refreshes ONLY the redaction lists (and diagnostics)
-      # onto the EXISTING config: enabled/endpoint/identity are process-global
-      # and immutable after the first init (see init.rb — a second init must
-      # never flip enabled and leave foam half-dark). Private: not public API
-      # surface (pinned by export_surface_spec).
-      def refresh_post_init_config(existing, redact_keys:, redact_pii_keys:, diagnostics:)
+      # A second init() refreshes ONLY the redaction lists (and diagnostics,
+      # and the heuristic-tier flag — redaction state) onto the EXISTING
+      # config: enabled/endpoint/identity are process-global and immutable
+      # after the first init (see init.rb — a second init must never flip
+      # enabled and leave foam half-dark). Private: not public API surface
+      # (pinned by export_surface_spec).
+      def refresh_post_init_config(existing, redact_keys:, redact_pii_keys:, diagnostics:,
+                                   secret_heuristics: true)
         Config.new(
           name: existing.name,
           environment: existing.environment,
@@ -76,7 +86,8 @@ module Foam
           redact_pii_keys: downcase_list(redact_pii_keys),
           ignored_outbound_hosts: existing.ignored_outbound_hosts,
           diagnostics: diagnostics ? true : false,
-          endpoint: existing.endpoint
+          endpoint: existing.endpoint,
+          secret_heuristics: secret_heuristics == false ? false : true
         ).freeze
       end
     end

data/lib/foam/otel/constants.rb

@@ -132,5 +132,215 @@ module Foam
     REDACTED = "[REDACTED]"
     MASK_BODY = "********" # always exactly eight chars — never length-revealing
     TAIL_MIN_LENGTH = 12   # below this, no tail is safe
+
+    # ---- THE VALUE-PATTERN SECRET LAYER (fleet ruling 2026-07-27) -----------
+    # docs/decisions/security-fixes-design.md CONTRACT V: the always-on second
+    # control the credential floor needs — the floor masks by NAME and is
+    # value-shape-blind by design, so a credential-SHAPED value under an
+    # innocuous key would still export raw (X1 amplifier; foam telemetry is
+    # read downstream by LLMs, so a leaked credential is exfiltratable by
+    # prompt injection). These constants are the frozen ruleset the central
+    # engine (redaction.rb scan_value_secrets) consults DIRECTLY — module-level
+    # frozen constants, never Config state, same structural non-disableability
+    # as the floor (design §V.8: Tier 1 has NO off switch; only the H1/H2
+    # heuristic tier honors the documented secret_heuristics: false opt-out).
+    #
+    # Licensing/provenance (design §V.1): every pattern derives from MIT
+    # (gitleaks b58d3f1, secretlint 7da613e) or Apache-2.0 (detect-secrets
+    # 5e14193) sources — see THIRD-PARTY-NOTICES; AGPL trufflehog was used as
+    # a coverage CHECKLIST only, no pattern transcribed. FLEET-FIXTURE NOTE:
+    # the design mandates a shared, byte-identity-gated
+    # contract/secret-patterns.json these constants mirror; that fixture is
+    # authored fleet-side (outside ruby/foam-otel's edit lane) — these
+    # constants faithfully implement design §V.2–V.4 and are this core's
+    # authoritative copy until the shared fixture lands and
+    # spec/value_secret_layer_spec.rb's identity gate flips from lint-only to
+    # byte-identity.
+
+    # Execution bounds (design §V.5 / C-caps). All overflow behaviors are
+    # FAIL-CLOSED: mask, never raw-pass, never crash.
+    SECRET_SCAN_CAPS = {
+      value_scan_cap: 262_144,             # 256 KiB (design §V.5.4) — oversize ⇒ anchor-only decision
+      pattern_max_matches_per_value: 1000, # match flood ⇒ whole value masked
+      pem_block_cap: 16_384,               # BEGIN…END search window; truncated ⇒ mask to end of value
+      h2_token_min: 24,
+      h2_token_max: 512,
+      query_pair_cap: 256,                 # C1.3 — overflow remainder masked; never an unbounded split (F-JS2 class)
+      key_len_cap: 256,                    # C-caps — skip super-linear key work past this (F-PY2 class)
+      key_token_cap: 32,                   # C-caps — matched keys are short
+    }.freeze
+
+    # Tier-1 named-provider patterns (design §V.2), byte-consistent with the
+    # python core's SECRET_VALUE_RULES. Each rule: lowercase literal :anchors
+    # (the regex NEVER runs unless an anchor occurs case-insensitively in the
+    # value — the gitleaks keywords pre-filter and the engine's linearity
+    # guarantee), a :regex whose group 1 is the secret span to mask, an
+    # optional :entropy floor over the candidate, and an optional :filter
+    # post-check (:digit / :classmix). No lookbehind, no possessive groups,
+    # bounded quantifiers (design §V.5.2 authoring rules — linted by
+    # spec/value_secret_layer_spec.rb). private-key-block and putty-private-key
+    # are LINEAR SCANS in the engine (design §V.2 normative algorithm), not
+    # table regexes.
+    SECRET_VALUE_RULES = [
+      {
+        id: "aws-access-key-id", ci: false, group: 1,
+        regex: '\b((?:A3T[A-Z0-9]|AKIA|ASIA|ABIA|ACCA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA)[A-Z2-7]{16})\b',
+        anchors: %w[akia asia abia acca agpa aida aroa aipa anpa anva a3t].freeze,
+      }.freeze,
+      {
+        id: "aws-secret-key", ci: true, group: 1, entropy: 3.5,
+        regex: '\baws[a-z0-9_ .\-]{0,25}?(?:key|secret|token)[a-z0-9_ .\-]{0,15}?[\'"]?\s{0,3}' \
+               '(?:=|:|=>|:=|,)\s{0,3}[\'"]?([A-Za-z0-9/+=]{40})(?![A-Za-z0-9/+=])',
+        anchors: %w[aws].freeze,
+      }.freeze,
+      {
+        id: "gcp-api-key", ci: false, group: 1,
+        regex: '\b(AIza[0-9A-Za-z_\-]{35})(?![0-9A-Za-z_\-])',
+        anchors: %w[aiza].freeze,
+      }.freeze,
+      {
+        id: "azure-client-secret", ci: false, group: 1, entropy: 3.0,
+        regex: '(?:^|[\s\'"`>=:(,])([A-Za-z0-9_~.]{3}[0-9]Q~[A-Za-z0-9_~.\-]{31,34})(?![A-Za-z0-9_~.\-])',
+        anchors: %w[q~].freeze,
+      }.freeze,
+      {
+        id: "azure-storage-key", ci: true, group: 1,
+        regex: '\baccount[_\-]?key[\'"]?\s{0,3}[:=]\s{0,3}[\'"]?([A-Za-z0-9+/]{86}==)',
+        anchors: %w[accountkey account_key account-key].freeze,
+      }.freeze,
+      {
+        id: "github-token", ci: false, group: 1,
+        regex: '\b((?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{36})(?![A-Za-z0-9_])',
+        anchors: %w[ghp_ gho_ ghu_ ghs_ ghr_].freeze,
+      }.freeze,
+      {
+        id: "github-fine-grained-pat", ci: false, group: 1,
+        regex: '\b(github_pat_[A-Za-z0-9_]{82})(?![A-Za-z0-9_])',
+        anchors: %w[github_pat_].freeze,
+      }.freeze,
+      {
+        id: "gitlab-token", ci: false, group: 1,
+        regex: '\b(glpat-[0-9A-Za-z_\-]{20,300}(?:\.[0-9a-z]{2,9})?|gl(?:ptt|rt|cbt)-[0-9A-Za-z_\-]{20,300}|' \
+               'GR1348941[0-9A-Za-z_\-]{20})(?![0-9A-Za-z_\-.])',
+        anchors: %w[glpat- glptt- glrt- glcbt- gr1348941].freeze,
+      }.freeze,
+      {
+        id: "slack-token", ci: false, group: 1,
+        regex: '\b(xox[abopsr]-(?:[0-9]{4,20}-){1,4}[0-9A-Za-z]{8,64}|xapp-[0-9]-[0-9A-Za-z_]{8,32}-[0-9]{8,16}-' \
+               '[0-9a-f]{32,96}|xoxe(?:\.xox[bp])?-[0-9]-[0-9A-Za-z\-]{80,250})(?![0-9A-Za-z\-])',
+        anchors: %w[xox xapp-].freeze,
+      }.freeze,
+      {
+        id: "slack-webhook", ci: true, group: 1,
+        regex: '(https://hooks\.slack\.com/(?:services|workflows|triggers)/[A-Za-z0-9+/]{20,120})(?![A-Za-z0-9+/])',
+        anchors: %w[hooks.slack.com].freeze,
+      }.freeze,
+      {
+        id: "stripe-secret-key", ci: false, group: 1,
+        regex: '\b((?:sk|rk)_(?:test|live|prod)_[a-zA-Z0-9]{10,99})(?![a-zA-Z0-9])',
+        anchors: %w[sk_test sk_live sk_prod rk_test rk_live rk_prod].freeze,
+      }.freeze,
+      {
+        id: "jwt", ci: false, group: 1,
+        regex: '\b(ey[A-Za-z0-9]{17,512}\.ey[A-Za-z0-9/_\-]{17,8192}\.(?:[A-Za-z0-9/_\-]{10,1024}={0,2})?)' \
+               '(?![A-Za-z0-9/_\-.=])',
+        anchors: %w[eyj].freeze,
+      }.freeze,
+      {
+        id: "uri-userinfo-credentials", ci: true, group: 1,
+        regex: '\b[a-z][a-z0-9+.\-]{0,30}://([^/\s:@?#]{1,128}:[^/\s@]{1,256})@',
+        anchors: %w[://].freeze,
+      }.freeze,
+      {
+        id: "bearer-token", ci: true, group: 1, filter: :digit,
+        regex: '\bbearer\s{1,4}([A-Za-z0-9._~+/=\-]{16,512})(?![A-Za-z0-9._~+/=\-])',
+        anchors: %w[bearer].freeze,
+      }.freeze,
+      {
+        id: "basic-auth-value", ci: true, group: 1, filter: :classmix,
+        regex: '\bbasic\s{1,4}([A-Za-z0-9+/]{12,512}={0,2})(?![A-Za-z0-9+/=])',
+        anchors: %w[basic].freeze,
+      }.freeze,
+      {
+        id: "anthropic-api-key", ci: false, group: 1,
+        regex: '\b(sk-ant-(?:admin|api)0[0-9]-[A-Za-z0-9_\-]{80,120}AA)(?![A-Za-z0-9_\-])',
+        anchors: %w[sk-ant-].freeze,
+      }.freeze,
+      {
+        id: "openai-api-key", ci: false, group: 1,
+        regex: '\b(sk-(?:proj|svcacct|admin)-[A-Za-z0-9_\-]{40,120}T3BlbkFJ[A-Za-z0-9_\-]{40,120}|' \
+               'sk-[A-Za-z0-9]{20}T3BlbkFJ[A-Za-z0-9]{20})(?![A-Za-z0-9_\-])',
+        anchors: %w[t3blbkfj].freeze,
+      }.freeze,
+    ].freeze
+
+    # Anchors for the two linear-scan rules (design §V.2: private-key-block —
+    # BEGIN…PRIVATE KEY blocks incl. RSA/EC/DSA/OPENSSH/ENCRYPTED/PGP, truncated
+    # block ⇒ mask to end of value, PUBLIC KEY/CERTIFICATE never match; and
+    # putty-private-key — the PPK header carries Private-Lines inline ⇒ whole
+    # value masked). Folded into the single anchor pre-filter so an OVERSIZED
+    # value carrying only a PEM block still fails closed.
+    SECRET_LINEAR_SCAN_ANCHORS = ["-----begin", "putty-user-key-file"].freeze
+
+    # Tier-2 heuristics (design §V.3) — the ONLY value-layer piece with the
+    # documented opt-out (secret_heuristics: false). H1 = gitleaks
+    # generic-api-key (MIT): keyword-anchored assignment, entropy-gated,
+    # four-layer FP suppression. H2 = detect-secrets Base64HighEntropyString
+    # (Apache-2.0): whole-value single token only.
+    SECRET_HEURISTIC_H1 = {
+      id: "generic-api-key", ci: true, group: 1, entropy: 3.5, entropy_hex: 3.0,
+      regex: '[\w.\-]{0,50}?(?:access|auth|api|credential|creds|key|passw(?:or)?d|secret|token)' \
+             '(?:[ \t\w.\-]{0,20})[\s\'"]{0,3}(?:=|>|:{1,3}=|\|\||:|=>|\?=|,)[`\'"\s=]{0,5}' \
+             '([\w.=\-]{10,150}|[a-z0-9][a-z0-9+/]{11,149}={0,3})(?:[`\'"\s;]|\\\\[nr]|$)',
+      anchors: %w[access auth api credential creds key passw secret token].freeze,
+    }.freeze
+
+    # H2 anchors are \A/\z (whole string) — Ruby's ^/$ are LINE anchors, so the
+    # fixture's ^…$ whole-value semantics translate to \A…\z here (recorded
+    # portability translation, design §V.2 conventions).
+    SECRET_HEURISTIC_H2 = {
+      id: "high-entropy-token", entropy: 4.5,
+      token_regex: '\A[A-Za-z0-9+/_\-]{24,512}={0,2}\z',
+      uuid_regex: '\A[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\z',
+      hex_regex: '\A[0-9a-fA-F]+\z',
+    }.freeze
+
+    # Placeholder shapes (design §V.4, gitleaks global allowlist): a HEURISTIC
+    # candidate matching any of these whole is never masked (env refs, template
+    # vars, printf specs, repeated fillers). Applied to H1/H2 candidates only —
+    # NEVER to Tier-1 matches (no Tier-1 value allowlist: a value allowlist is
+    # a bypass shape; AKIAIOSFODNN7EXAMPLE is deliberately a POSITIVE).
+    SECRET_VALUE_PLACEHOLDERS = [
+      '\A(?:true|false|null|nil|none|undefined)\z',
+      '\A(.)\1{3,}\z',
+      '\A\$[A-Za-z_][A-Za-z0-9_]*\z',
+      '\A\$\{[^}]{0,64}\}\z',
+      '\A\{\{[^}]{0,64}\}\}\z',
+      '\A%[A-Za-z_]{1,64}%\z',
+      '\A@[A-Za-z_]{1,64}@\z',
+      '\A%[sdifv]\z',
+      '\A<[^>]{0,64}>\z',
+    ].freeze
+
+    # Key-context allowlist (design §V.3 / H1): when the matched assignment's
+    # KEY text is one of these non-secret names, the H1 candidate is NOT
+    # masked. Vendored subset of the gitleaks generic-rule allowlist,
+    # byte-consistent with the python core.
+    SECRET_KEY_CONTEXT_ALLOWLIST = %w[
+      api_version apiversion key_id keyid public_key publickey
+      csrf_token primary_key partition_key sort_key idempotency_key
+      cache_key routing_key aggregate_key
+    ].freeze
+
+    # Stopwords (design §V.4, from the gitleaks curated list): a heuristic
+    # candidate CONTAINING any of these is rejected as a placeholder false
+    # positive. Applied to H1/H2 candidates only — never to Tier-1 matches.
+    # Byte-consistent with the python core's vendored subset; the full
+    # 1,436-entry list ships fleet-side in contract/secret-patterns.json.
+    SECRET_VALUE_STOPWORDS = %w[
+      example placeholder redacted changeme changeit
+      yourkey your_api_key your-api-key xxxxxxxx todo
+      notreal loremipsum deadbeef 0000000000 1111111111
+    ].freeze
   end
 end