doc/user/application_security/vulnerabilities/validity_check.md
{{< details >}}
{{< /details >}}
{{< history >}}
validity_checks. Disabled by default.validity_checks_security_finding_status. Disabled by default.validity_checks_security_finding_status removed.validity_checks is enabled by default.validity_checks in GitLab 18.8.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
GitLab validity checks determines whether a secret, like an access token, is active. A secret is active when:
Because active secrets can be used to impersonate a legitimate user, they pose a greater security risk than inactive secrets. If several secrets are leaked at once, knowing which secrets are active is an important part of triage and remediation.
Prerequisites:
To enable validity checks for a project:
GitLab checks the status of detected secrets when the secret_detection CI/CD job is complete.
To view a secret's status, view the vulnerability details page. To update the status of a secret,
for example after revoking it, re-run the secret_detection CI/CD job.
To turn on validity checks at the group level, as a Maintainer or higher role, use a GraphQL API mutation:
mutation {
setGroupValidityChecks(input: {
validityChecksEnabled: true,
namespacePath: "my-group/my-subgroup",
projectsToExclude: [100, 105, 108]
}) {
clientMutationId
validityChecksEnabled
}
}
{{< history >}}
secret_detection_partner_token_verification. Enabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history.
Validity checks support the following secret types:
GitLab tokens:
External service tokens:
When the secret detection analyzer detects a potential secret, GitLab verifies the status of the secret with its vendor, and assigns the detection one of the following statuses:
You should rotate active and possibly active secrets as soon as possible.
%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TD
accTitle: Validity checks workflow
accDescr: Process flow for secret detection showing three possible outcomes.
A[Secret detection analyzer runs] --> B[Secret detected]
B --> C{Verification
with vendor}
C -->|Cannot verify or unsupported type| D[Possibly active]
C -->|Valid and not expired| E[Active]
C -->|Expired or revoked| F[Inactive]
{{< history >}}
secret_detection_validity_checks_refresh_token. Disabled by default.secret_detection_validity_checks_refresh_token removed.{{< /history >}}
After validity checks runs, the status of a token is not automatically updated, even if the token is revoked or expires. To update a token, you can manually refresh the status:
Validity checks is re-run, and the token status is updated.
When working with validity checks, you might encounter the following issues.
A token has the possibly active status when GitLab can't verify its validity. This might be because:
To resolve this issue, re-run the secret_detection job. If the status persists after a few attempts,
you might need to validate the secret manually.
Unless you're certain the token isn't active, you should revoke and replace possibly active secrets as soon as possible.
External service token verification might take longer than GitLab token verification due to rate limits imposed by external services. If an external service token shows possibly active status temporarily, this is typical. The verification is queued and completes shortly. Check the Last verified at timestamp to see when the status was last updated, or refresh the page after a few moments.