### Current state and problem [Validity Checks](https://docs.gitlab.com/user/application_security/vulnerabilities/validity_check/) is GA and verifies ~10 token types. The goal is to expand coverage to the [60+ token types across the vendors in scope](https://gitlab.com/groups/gitlab-org/-/work_items/20343#note_3335251651), but the [current framework](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/secret_detection_validity_checks/) has accumulated debt that makes each new check slower and riskier than it should be: - Verifiers recheck hand-copied token regexes that the detection rule already matched. At best this is redundant, at worst the two copies drift and findings silently never get checked ([GCP](https://gitlab.com/gitlab-org/gitlab/-/work_items/588454), [Heroku](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/251856)). - The status model conflates "we checked and the vendor was ambiguous" with "no check exists for this token type". Both display as ["Possibly active secret"](https://docs.gitlab.com/user/application_security/vulnerabilities/validity_check/#validity-check-workflow), so neither customers nor our own metrics can tell coverage gaps from inconclusive checks. - [Per-vendor rate limits](https://gitlab.com/groups/gitlab-org/-/work_items/20343#note_3323286126) were set ad hoc, and we have no clear picture of current usage, headroom, or what happens to Sidekiq queues as vendor count grows. - There is no enforced link between [detection rules](https://gitlab.com/gitlab-org/security-products/secret-detection/secret-detection-rules) and validity checks, so new rules can ship without a corresponding check and nobody notices until someone audits by hand. - Longer-term architecture questions (extraction from the monolith, EventStore for triggering, entry points beyond the vulnerability report) keep resurfacing without a decision, and each vendor added in the current shape makes a later move more expensive. During the 2026 R&D Summit, we built an [AI-assisted verifier generator](https://gitlab.com/ghavenga/summit-ch6-validity-checks-demo/-/tree/main): an LLM reads a vendor's API docs and emits a structured vendor spec, and a deterministic generator turns that spec into a verifier class, its spec file, and a registry entry, all held to an unknown-never-inactive guardrail. We plan to make it the main way to add vendors. But it was vibe coded under challenge time pressure, so before we build on it every piece needs human review to confirm the design actually holds: known gaps already include multi-token-type vendors on the automated paths, the ADR-006 vendor-subdirectory layout, overwrite protection for existing clients, and response-body-based status disambiguation, and review may surface more. The primary goal is expanding vendor support. All architecture and cleanup work in this epic is scoped to what serves that goal. ### Workstreams Each workstream is a sub-epic: 1. [Research](https://gitlab.com/groups/gitlab-org/-/work_items/23342): answer the open questions before committing to build. Sequence diagram of the full check lifecycle, extraction spike (gem vs service, queueing and infra requirements across deployment models), EventStore spike, rate limit usage and headroom, Slack token type research, and reviewing the Summit challenge generator. 2. [Cleanup](https://gitlab.com/groups/gitlab-org/-/work_items/23343): pay down the debt that blocks safe expansion. Merge ADR-006 and align the GCP verifiers to it, fix the Postman verifier, extract a base client with a defined check interface, remove the redundant format rechecks (except AWS), remove the stale GA feature flag, and document the rule-plus-validity-check requirement. 3. [Expand vendor support](https://gitlab.com/groups/gitlab-org/-/work_items/23344): review the Summit challenge generator and close its known gaps, then roll out vendors one per milestone covering all of that vendor's token types. 4. [Instrumentation](https://gitlab.com/groups/gitlab-org/-/work_items/23345): fix the broken dashboards (Tableau sync or our own Snowflake-based dashboard) and add events for checks that never called a vendor and secrets skipped for lack of vendor support. 5. [UI/UX](https://gitlab.com/groups/gitlab-org/-/work_items/23394): design the customer-facing surfaces, with UX/product input. Decide how to expose "no vendor support" to users -- whether to split it out of the catch-all unknown status (scoped to new-analyzer vendors to avoid backfill) or instrument filtered-out secrets instead -- and decide where the enablement toggle should live (today it's a small toggle inside the Pipeline Secret Detection section of the Security configuration page, easy to miss). ### References - Simplified current flow diagram: https://gitlab.com/gitlab-org/gitlab/-/work_items/604600 - ADR-006, one verifier class per token type: https://gitlab.com/gitlab-com/content-sites/handbook/-/merge_requests/20444 - Generator PoC: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/247929 (10-MR stack), demo repo: https://gitlab.com/ghavenga/summit-ch6-validity-checks-demo/-/tree/main - Prior architecture discussions: [SDRS](https://gitlab.com/groups/gitlab-org/-/work_items/20343#note_3323286126), [gem extraction](https://gitlab.com/groups/gitlab-org/-/work_items/20343#note_3254120682), [YAML vs code](https://gitlab.com/gitlab-org/gitlab/-/work_items/580209#note_3114526853)