GitLab 유효성 검사는 액세스 토큰 같은 시크릿이 활성 상태인지 판단합니다. 시크릿은 다음 조건을 모두 만족할 때 활성 상태입니다.

• 만료되지 않았습니다.
• 인증에 사용할 수 있습니다.

활성 시크릿은 정상 사용자를 가장하는 데 쓰일 수 있으므로 비활성 시크릿보다 보안 위험이 큽니다. 여러 시크릿이 한꺼번에 유출된 경우, 어떤 시크릿이 활성 상태인지 파악하는 것은 심사와 대응에서 중요한 부분입니다.

유효성 검사 활성화#

사전 요구 사항:

• 파이프라인 보안 스캔이 활성화된 프로젝트가 있어야 합니다.
• 인스턴스에서 파트너 검증 API로 아웃바운드 네트워크 액세스가 가능해야 합니다.

프로젝트에 유효성 검사를 활성화하려면 다음 단계를 따릅니다.

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. 왼쪽 사이드바에서 Secure > Security configuration을 선택합니다.
3. Pipeline Secret Detection 아래에서 Validity checks 토글을 켭니다.

GitLab은 secret_detection CI/CD job 이 완료되면 탐지된 시크릿의 상태를 확인합니다. 시크릿 상태를 보려면 취약점 상세 페이지를 확인합니다. 시크릿을 폐기한 뒤와 같이 상태를 갱신하려면 secret_detection CI/CD job을 다시 실행합니다.

그룹 수준에서 유효성 검사를 켜려면 Maintainer 이상 권한으로 GraphQL API 뮤테이션을 사용합니다.

mutation {
  setGroupValidityChecks(input: {
    validityChecksEnabled: true,
    namespacePath: "my-group/my-subgroup",
    projectsToExclude: [100, 105, 108]
  }) {
    clientMutationId
    validityChecksEnabled
  }
}

커버리지#

유효성 검사는 다음 시크릿 유형을 지원합니다.

GitLab 토큰:

• GitLab 개인 액세스 토큰
• 라우팅 가능한 GitLab 개인 액세스 토큰
• GitLab 배포 토큰
• GitLab Runner 인증 토큰
• 라우팅 가능한 GitLab Runner 인증 토큰
• GitLab Kubernetes 에이전트 토큰
• GitLab SCIM OAuth 토큰
• GitLab CI/CD job 토큰
• GitLab 수신 이메일 토큰
• GitLab 피드 토큰(v2)
• GitLab 파이프라인 트리거 토큰

외부 서비스 토큰:

• Adafruit IO 키
• Anthropic API 키
• Asana 개인 액세스 토큰
• AWS IAM 장기 액세스 키 ID(AKIA로 시작)
• Datadog API 키
• EasyPost API 토큰
• EasyPost 테스트 API 토큰
• GitHub App 설치 토큰
• GitHub 세분화된 개인 액세스 토큰
• GitHub OAuth 액세스 토큰
• GitHub 개인 액세스 토큰(클래식)
• Google Cloud API 키
• HashiCorp Terraform 사용자 및 조직 API 토큰
• Heroku API 키
• npm 액세스 토큰
• OpenAI 관리자 API 키
• OpenAI 프로젝트 API 키
• OpenAI 서비스 계정 키
• OpenAI 사용자 API 키
• Postman API 토큰
• SendGrid API 토큰
• Stripe 라이브 게시 가능 키
• Stripe 라이브 제한 키
• Stripe 라이브 시크릿 키
• Stripe 라이브 짧은 시크릿 키
• Stripe 테스트 게시 가능 키
• Stripe 테스트 제한 키
• Stripe 테스트 시크릿 키
• Stripe 테스트 짧은 시크릿 키

AWS IAM 액세스 키 ID, Google Cloud API 키, Postman API 토큰에 대한 유효성 검사는 모든 시크릿 탐지 분석기에서 동작합니다. 그 밖의 외부 서비스 토큰 유형은 앞으로 추가되는 토큰 유형을 포함해 소스 코드용 GitLab Secret Scanning이 시크릿을 탐지한 경우에만 GitLab 이 검증합니다.

아웃바운드 네트워크 액세스 구성#

유효성 검사는 오프라인 환경에서는 지원되지 않습니다. 이 기능은 탐지된 토큰이 활성 상태인지 확인하기 위해 파트너 검증 API 로의 아웃바운드 네트워크 액세스가 필요합니다.

GitLab 인스턴스가 방화벽 뒤에 있지만 인터넷에 접근할 수 있다면, 각 파트너의 검증 API URL을 허용 목록에 추가합니다. 지원되는 URL은 다음과 같습니다.

• https://api.anthropic.com/v1/models
• https://api.datadoghq.com/api/v1/validate
• https://api.easypost.com/v2/addresses
• https://api.getpostman.com/me
• https://api.github.com/installation/repositories
• https://api.github.com/user
• https://api.heroku.com/account
• https://api.openai.com/v1/models
• https://api.openai.com/v1/organization/admin_api_keys
• https://api.sendgrid.com/v3/scopes
• https://api.stripe.com/v1/balance
• https://app.asana.com/api/1.0/users/me
• https://app.terraform.io/api/v2/account/details
• https://io.adafruit.com/api/v2/user
• https://registry.npmjs.org/-/whoami
• https://sts.amazonaws.com/
• https://www.googleapis.com/discovery/v1/apis

이러한 엔드포인트로의 아웃바운드 액세스를 허용할 수 없다면 이 기능을 활성화하지 않습니다. 제한된 네트워크 환경에서 유효성 검사를 활성화하면 검증 과정에서 네트워크 오류가 발생합니다.

유효성 검사 워크플로#

시크릿 탐지 분석기가 시크릿으로 보이는 값을 탐지하면 GitLab은 해당 시크릿의 상태를 공급자에 확인한 뒤 다음 상태 중 하나를 부여합니다.

• 활성 가능성 있음: GitLab 이 시크릿 상태를 확인하지 못했거나, 해당 시크릿 유형이 유효성 검사에서 지원되지 않습니다.
• 활성: 시크릿이 만료되지 않았고 인증에 사용할 수 있습니다.
• 비활성: 시크릿이 만료되었거나 폐기되어 인증에 사용할 수 없습니다.

활성 시크릿과 활성 가능성이 있는 시크릿은 가능한 한 빨리 교체해야 합니다.

%%{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<br>with vendor}
C --&gt;|Cannot verify or unsupported type| D[Possibly active]
C --&gt;|Valid and not expired| E[Active]
C --&gt;|Expired or revoked| F[Inactive]</code></pre></details></div>

시크릿 상태 새로 고침#
히스토리
GitLab 18.2에서 secret_detection_validity_checks_refresh_token이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
GitLab 18.7에서 일반 제공되었습니다. 기능 플래그 secret_detection_validity_checks_refresh_token 이 제거되었습니다.
유효성 검사가 실행된 뒤에는 토큰이 폐기되거나 만료되더라도 토큰 상태가 자동으로 갱신되지 않습니다.
토큰 상태를 갱신하려면 다음과 같이 수동으로 새로 고칩니다.

취약점 리포트에서 새로 고치려는 취약점을 선택합니다.
토큰 상태 옆에서 Retry([retry])를 선택합니다.

유효성 검사가 다시 실행되고 토큰 상태가 갱신됩니다.
문제 해결#
유효성 검사를 사용할 때 다음과 같은 문제가 발생할 수 있습니다.
예상치 못한 토큰 상태#
GitLab 이 토큰의 유효성을 확인하지 못하면 해당 토큰은 활성 가능성 있음 상태가 됩니다.
원인은 다음과 같습니다.

시크릿 검증 job 이 실행되지 않았습니다.
해당 시크릿 유형이 유효성 검사에서 지원되지 않습니다.
토큰 공급자에 연결하는 데 문제가 있었습니다.

이 문제를 해결하려면 secret_detection job을 다시 실행합니다. 몇 차례 시도한 뒤에도 상태가 그대로라면
시크릿을 수동으로 검증해야 할 수 있습니다.
토큰이 활성 상태가 아니라고 확신할 수 없다면, 활성 가능성이 있는 시크릿은 가능한 한 빨리 폐기하고 교체해야 합니다.
외부 서비스 토큰 유효성 검사 지연#
외부 서비스가 적용하는 속도 제한 때문에 외부 서비스 토큰 검증은 GitLab 토큰 검증보다 오래 걸릴 수
있습니다. 외부 서비스 토큰이 일시적으로 possibly active 상태로 표시되는 것은
정상입니다. 검증은 큐에 들어가 곧 완료됩니다. 상태가 마지막으로 갱신된 시점은 Last verified at
타임스탬프에서 확인하거나, 잠시 후 페이지를 새로 고쳐 확인합니다.