악성코드 권고 동기화
GitLab v19.6요약
GitLab은 Package Metadata Database(PMDB) v3 프레임워크를 기반으로 GitLab 악성코드 권고(GLAM)의 비공개 데이터베이스를 인스턴스에 동기화합니다. 의존성 방화벽은 이렇게 동기화된 권고를 사용해 악성 패키지를 차단합니다.
GitLab은 Package Metadata Database(PMDB) v3 프레임워크를 기반으로 GitLab 악성코드 권고(GLAM)의 비공개 데이터베이스를
인스턴스에 동기화합니다. cron 워커가 동기화 서비스를 시작하고, 이 서비스는 패키지 레지스트리를 한 번에 하나씩 처리합니다.
레지스트리마다 커넥터가 PMDB Distribution Service(PDS)에서 권고 아카이브를 가져오거나, 에어 갭 인스턴스에서는
로컬에 압축 해제된 스냅샷을 읽습니다. 동기화는 항목을 테이블에 upsert하고 진행 상황을 pm_checkpoints에 기록하므로,
중단된 실행은 멈춘 지점에서 재개됩니다.
의존성 방화벽은 이렇게 동기화된 권고를 사용해 악성 패키지를 차단합니다. 사용자 관점의 개요는 GitLab 악성코드 권고를 참고합니다.
흐름#
소스 코드 보기
%%{init: { "flowchart": { "curve": "linear" } } }%%
flowchart LR
accTitle: Malware advisory sync flow
accDescr: The sync worker triggers the sync service, which fetches data per purl type through a connector, then fabricates and ingests advisory objects into the pm_malware tables while tracking progress in pm_checkpoints.
Worker[MalwareAdvisoriesSyncWorker] --> Service[MalwareAdvisorySyncService]
Service -->|per purl_type| Connector["Connector (MalwarePds or OfflineV3)"]
Connector --> Fabricator[MalwareAdvisoryDataObjectFabricator]
Fabricator --> Ingestion[MalwareAdvisoryIngestionService]
Ingestion --> Tables[(pm_malware_advisories and pm_malware_affected_packages)]
Service -.tracks progress.-> Checkpoints[(pm_checkpoints)]
워커#
PackageMetadata::MalwareAdvisoriesSyncWorker(ee/app/workers/)는 ExclusiveLeaseGuard를 사용하는
cron job(include CronjobQueue)입니다. sidekiq_options retry: false, urgency :low,
worker_has_external_dependencies!, idempotent!를 설정합니다.
워커는 다음 조건을 모두 충족할 때만 실행됩니다.
dependency_scanning라이선스를 사용할 수 있습니다.- 개발 환경에서는
PM_SYNC_IN_DEV환경 변수가true입니다.
PM_SYNC_IN_DEV 환경 변수는 두 가지 역할을 합니다. 개발 환경에서 동기화를 활성화하고,
서비스가 작업 단위 사이에 적용하는 0.25초 스로틀도 건너뜁니다. 따라서 개발 환경의 동기화 실행 시간은
프로덕션보다 훨씬 짧으며 프로덕션을 대표하지 않습니다.
GitLab Self-Managed와 GitLab Dedicated에서는 워커가 실행 전에 인스턴스별로 최대 5분의 지터를 추가하므로, 인스턴스 전체가 같은 시점에 배포 서비스를 호출하지 않습니다. GitLab.com과 스테이징은 지터 없이 기본 cron 주기로 실행됩니다.
서비스#
PackageMetadata::MalwareAdvisorySyncService.execute(lease:)(ee/app/services/)가 동기화를 실행합니다.
이 서비스는 실행 흐름을 담당하는 공유 PackageMetadata::V3SyncService의 얇은 하위 클래스입니다.
하위 클래스는 데이터 세트의 이름을 정하고 파브리케이터, 수집 서비스, 타이밍을 제공할 뿐입니다. 실행은
max_lease_length(배타적 리스 타임아웃)와 max_sync_duration(실행당 예산으로, 리스가 만료되기 전에 실행이 멈추도록
리스보다 짧게 유지)로 제한되는 StopSignal을 생성한 다음,
활성화된 purl 유형마다 구성 하나를 반환하는 PackageMetadata::SyncConfiguration.configs_for('malware_advisories')를 반복합니다.
현재 값은 서비스 클래스를 참고합니다.
PMDB Distribution Service(PDS)를
사용하는 실행에서는 서비스가 pds_token_available?을 사용해 Cloud Connector
인스턴스 토큰을 처음에 한 번 확인합니다. 토큰이 없으면 서비스는
aborted_no_token을 로그에 남기고 PDS를 호출하지 않은 채 중지합니다. 토큰이 있으면 PDS가 지원한다고 보고하는
레지스트리로 purl 유형을 필터링하고(GET /supported 호출이며 실패해도 계속 진행하는 fail-open 방식),
남은 작업을 레지스트리별로 최초 동기화의 /all 가져오기 또는 대량 /delta 가져오기로 나눕니다.
이 섹션에서 설명하는 엔드포인트는 OpenAPI 사양을 참고합니다. PDS 프로젝트는 비공개 리포지터리이므로 이 링크는 커뮤니티 기여자가 액세스할 수 없습니다.
커넥터#
ee/lib/gitlab/package_metadata/connector/에 있습니다.
Pds의 하위 클래스인MalwarePds는 온라인 경로입니다. Cloud Connector 인스턴스 JSON Web Token(IJWT)과 Cloud Connector ID 헤더로 PDS에 인증합니다. 구성된 기본 URI를 기준으로, 최초 동기화 스냅샷에는GET /all?purl_type=<registry_id>를 호출하고(샤드별로 서명된 Google Cloud Storage URL을 반환합니다), 증분 업데이트에는GET /delta?since=<registry_id>:<seq>를, 그리고GET /supported를 호출합니다. 아카이브는 줄바꿈으로 구분된 JSON(NDJSON)을 담은.tar.zst파일입니다.OfflineV3(Offline의 하위 클래스)는 에어 갭 경로입니다. 데이터 세트에 중립적이며 모든 v3 데이터 세트가 공유합니다.vendor/package_metadata/malware_advisories/v3/<registry_id>/full_dataset/에서 로컬에 다운로드한 스냅샷을 읽습니다. 이 위치에는checkpoint.json파일과<shard>.tar.zst아카이브가 있고, 그 옆에<unix_seconds>.tar.zst아카이브가 들어 있는 선택적deltas/디렉터리가 있습니다. 최초 동기화는 스냅샷만 읽고deltas/는 무시하며, 이전 실행이 중단된 경우 마지막으로 수집한 샤드부터 재개합니다. 그 이후에는 스냅샷과 델타를 하나의 타임라인으로 읽고 체크포인트보다 최신인 모든 아카이브를 오래된 순으로 적용합니다. 시간이 같으면 스냅샷이 먼저이므로, 더 최신 스냅샷을 복사해 넣으면 전체 재동기화가 강제됩니다. 다운로드 스크립트에서 델타를 가져오는 기능은 이슈 616703에서 제안되었습니다. 다운로드 절차는 GitLab v3 악성코드 권고 다운로드에 문서화되어 있습니다.SyncConfiguration::Location은 vendor 디렉터리가 있으면:offline을, 없으면:pds를 선택합니다.- PDS는 원시 purl 유형이 아니라 레지스트리 ID로 권고의 키를 지정합니다. 예를 들어
gem은rubygem에,golang은go에,composer는packagist에 대응합니다.SyncConfiguration.registry_id가 이 매핑을 수행합니다.
전체 동기화가 중단되면 해당 레지스트리는 다음 실행에서 /delta로 전환하지 않고 /all을 계속 요청합니다.
full_sync_target_sequence 마커가 해당 스냅샷이 끝날 때까지 설정된 상태로 유지되기 때문입니다. 이것이 동기화 전체를 막지는 않습니다.
체크포인트는 purl 유형별로 키가 지정되므로, 다른 레지스트리는 독립적으로 델타를 계속 실행합니다.
체크포인트와 재개 가능성#
동기화 진행 상황은 Checkpoint.for_dataset('malware_advisories', 'v3')로 범위가 지정되는
pm_checkpoints 테이블(gitlab_pm 데이터베이스)에서 추적합니다. full_dataset_pending?가 레지스트리가
/all을 사용할지 /delta를 사용할지 결정합니다.
최초 동기화의 /all 부트스트랩은 샤드별로 재개할 수 있으며 체크포인트 chunk 필드에서 추적합니다.
full_sync_target_sequence 마커는 샤드가 여러 개인 부트스트랩이 중단되어도 full_dataset_pending?를 true로 유지하므로,
재개된 동기화는 /delta로 일찍 전환하지 않고 /all을 계속 가져옵니다. 델타 동기화는 아카이브 sequence별로 재개합니다.
두 경우 모두 체크포인트는 이미 영구 저장된 데이터에 대해서만 진행됩니다.
수집#
MalwareAdvisoryDataObjectFabricator는 각 NDJSON 항목을 MalwareAdvisoryDataObject로 변환합니다.
그런 다음 MalwareAdvisoryIngestionService가 검증 후 건너뛰기 및 대량 upsert 수집 작업을 통해 이 객체를
pm_malware_advisories와 pm_malware_affected_packages 테이블(gitlab_sec_cell_local 데이터베이스)에
upsert합니다.
로깅#
동기화는 event: malware_advisory_sync 태그를 붙여 구조화된 로그를 Gitlab::AppJsonLogger(application_json.log)로 내보냅니다.
레지스트리 실행마다 수명 주기 단계인 started, completed를 기록하고,
실행 도중 중지 신호가 발생하면 interrupted를 기록합니다. Cloud Connector 토큰을 사용할 수 없을 때는
서비스가 aborted_no_token도 기록합니다. 특정 기간의 동기화 성공률은
completed 이벤트 수와 started 이벤트 수를 비교해 구할 수 있습니다.
관측 가능성#
의존성 방화벽은 악성코드 권고 데이터에 의존하므로, 동기화가 조용히 실패하면 인스턴스는 오래된 권고를 기준으로 대조하게 됩니다.
동기화 진행 상황과 데이터 최신성 확인#
Rails 콘솔에서 다음을 실행합니다. sequence는 동기화된 최신 데이터의 유닉스 초 단위 커서이므로, Time.at(sequence)가 해당 레지스트리 권고의 최신성입니다. 최근 시각이고 실행할 때마다 진행되면 동기화가 정상입니다.
PackageMetadata::Checkpoint.for_dataset('malware_advisories', 'v3').order(:purl_type).each do |c|
freshness = c.sequence.to_i.zero? ? 'never' : Time.at(c.sequence)
puts "#{c.purl_type}: data_through=#{freshness} full_dataset_pending=#{c.full_dataset_pending?} chunk=#{c.chunk} updated_at=#{c.updated_at}"
end
# Rows ingested so far:
PackageMetadata::MalwareAdvisory.count
PackageMetadata::MalwareAffectedPackage.count
data_through가 더 이상 움직이지 않거나 계속 never이면 동기화가 멈춘 것입니다.
동기화가 활성화되어 있는지 확인#
License.feature_available?(:dependency_scanning) # must be true
선택 사항. 동기화를 즉시 인라인으로 실행하려면(GitLab Self-Managed 지터 건너뜀) 다음을 실행합니다.
PackageMetadata::MalwareAdvisoriesSyncWorker.new.perform(true)
로그 확인#
구조화된 로그는 Omnibus 인스턴스의 /var/log/gitlab/gitlab-rails/application_json.log에 있습니다. 다음으로 필터링합니다.
grep malware_advisory_sync /var/log/gitlab/gitlab-rails/application_json.log \
| jq -r 'select(.event == "malware_advisory_sync") | "\(.phase) \(.purl_type // "-") \(.message)"'
GitLab.com에서는 GitLab 팀원이 Kibana의
GLAM sync on GitLab Rails
뷰를 사용할 수 있으며, 이 뷰는 이미 해당 항목으로 필터링되어 있습니다. json.phase 또는
json.batch_id로 더 좁힙니다.
정상적인 실행은 레지스트리마다 started 다음에 completed를 기록합니다.
문제 해결#
| 신호 | 의미 | 해결 방법 |
|---|---|---|
phase: aborted_no_token(오류) |
Cloud Connector 인스턴스 토큰이 없으므로 데이터를 가져오지 않습니다 | 인스턴스가 활성화되어 있고 Cloud Connector 서비스에 연결할 수 있는지 확인하고, 구독과 토큰을 확인합니다. |
completed 없이 phase: interrupted가 반복됨 |
각 실행이 시간 예산에 도달합니다. 규모가 큰 최초 동기화에서 흔하며 다음 실행에서 재개됩니다 | 최초 부트스트랩 중에는 예상되는 동작입니다. 끝내 완료되지 않으면 느린 네트워크나 지나치게 큰 스냅샷이 없는지 확인합니다. |
malware_advisory_sync 로그 줄이 전혀 없음 |
워커가 실행되지 않습니다 | 위의 라이선스를 확인하고, package_metadata_malware_advisories_sync_worker cron이 활성화되어 있는지 확인합니다. |
동기화 로그 줄 없이 PackageMetadata::MalwareAdvisoriesSyncWorker의 Sidekiq job이 실패함 |
배포 서비스에 연결할 수 없습니다. 전송 오류는 로그에 기록되기 전에 발생합니다 | 배포 서비스로의 이그레스를 확인합니다. 이 경우의 구조화된 로깅은 이슈 621513에서 추적합니다. |
data_through가 먼 과거이며 진행되지 않음 |
데이터가 오래되었습니다 | 위의 신호를 차례로 점검합니다. 오래된 권고는 새로 게시된 악성 패키지를 놓칠 수 있습니다. |