Wrangler dependencies instrumentation으로 Cloudflare Workers 의존성 메타데이터 수집 검증하기
Wrangler dependencies instrumentation은 Wrangler 4.110.0부터 wrangler deploy와 wrangler versions upload 때 npm 의존성 메타데이터를 기본으로 수집해 Cloudflare API에 보내는 기능이에요. 패키지 소스 전체를 보내는 건 아니고, 확인된 범위는 패키지 이름과 package.json의 선언 버전 범위, node_modules에서 해석한 설치 버전입니다. 설정하지 않았는데도 업그레이드 뒤 전송될 수 있다는 점이 이번 변화의 핵심. 그냥 지나치기엔 조금 신경 쓰이는 구간이죠.
이 글은 2026년 8월 3일 기준 Cloudflare 변경 공지와 Wrangler 4.110.0·4.113.0 릴리스를 대조한 내용입니다. 이번 조사에서는 Worker를 실제로 배포하거나 요청을 캡처하지 않았어요. 아래 테스트는 공식 동작을 실계정에서 확인하기 위한 재현 설계이며, 결과를 미리 확인했다고 쓰는 글은 아님.
4.110.0에서 기본 수집, 4.113.0에서 선택 제외가 생겼어요
Cloudflare 변경 공지의 게시일은 2026년 7월 9일이고, 같은 날 공개된 [email protected]이 이 기능의 최소 확인 버전입니다. 설정을 생략해도 기본 활성화라서 이 버전으로 올린 뒤 업로드하는 순간이 운영상 변경 경계가 돼요.
12일 뒤인 2026년 7월 21일, [email protected]에는 exclude_packages가 추가됐습니다. 처음에는 전체 허용 아니면 전체 중단이었다가 특정 패키지명만 뺄 수 있게 된 셈. 버전을 고정하지 않고 latest만 적어두면 이 차이가 슬쩍 사라져 버립니다.
| Wrangler 버전 | 확인된 동작 | 운영 판단 |
|---|---|---|
| 4.110.0 미만 | 이번 기능 도입 근거 없음 | 기본 비활성이라고 단정하지 않고 지원 전으로 분류 |
| 4.110.0 이상, 4.113.0 미만 | 기본 수집, enabled: false 전체 중단 |
선택 제외 옵션은 공식 자료에서 확인되지 않음 |
| 4.113.0 이상 | 기본 수집, 전체 중단, exclude_packages 선택 제외 |
민감한 패키지명 패턴만 제외 가능 |
그래서 배포 기록에는 인증정보 없이 npx wrangler --version 결과를 남겨야 합니다. 버전 한 줄 없으면 나중에 설정이 왜 다르게 작동했는지 추적하기가 난감해짐.
보내는 정보는 세 가지, 모든 의존성을 담는 SBOM은 아닙니다
Wrangler 4.110.0 릴리스가 밝힌 수집 대상은 package.json의 dependencies와 devDependencies예요. 각 항목에서 다음 세 가지를 구성합니다.
- 패키지 이름
package.json에 선언한 버전 제약node_modules에서 해석한 정확한 설치 버전
여기서 devDependencies도 들어간다는 점이 은근 중요합니다. 런타임 번들에 포함된 패키지만 전송된다고 보면 틀려요. 반면 workspace 패키지, 로컬 패키지, 해석할 수 없는 패키지는 제외되고 한 번의 업로드에서 최대 200개까지만 담깁니다.
공식 설명은 package.json과 node_modules를 정보 원천으로 지목하지만, lockfile 전체나 패키지 소스 코드, 환경변수 값, 비밀값을 보낸다고 확대할 근거는 없습니다. 그렇다고 완전한 SBOM이라고 부르기도 어려워요. 제외 대상과 200개 상한이 있으니까요. 딱 공급망 보안에 활용할 보조 메타데이터 정도로 보는 게 안전함.
Workers 업로드 메타데이터 문서는 업로드 요청의 metadata 파트를 설명하지만, 공개된 일반 속성 목록에는 이 의존성 구조가 상세히 나오지 않습니다. 내부 JSON 키나 서버 저장 구조까지 상상해서 채워 넣으면 안 되는 구간이에요.
전체 opt-out과 패키지별 제외는 설정이 다릅니다
전체 수집을 끄려면 dependencies_instrumentation을 최상위 전용 키로 둡니다. [env.production] 아래에 넣는 환경별 설정으로 설명하면 안 돼요.
JSON 또는 JSONC 설정은 다음과 같습니다.
{
"dependencies_instrumentation": {
"enabled": false
}
}
TOML이라면 이렇게 씁니다.
[dependencies_instrumentation]
enabled = false
Wrangler 4.113.0 이상에서 일부 패키지만 제외하려면 exclude_packages를 사용할 수 있어요. 4.113.0 릴리스에서 확인되는 범위는 * 와일드카드를 쓰는 패키지명 패턴 배열까지입니다. 패턴 문법 전체나 우선순위는 공개 근거 없이 단정하지 않는 편이 맞습니다.
{
"dependencies_instrumentation": {
"exclude_packages": ["@internal/*", "secret-tool"]
}
}
조사 시점의 Wrangler 설정 참조에는 enabled만 나열돼 있지만 더 최신인 공식 릴리스에는 exclude_packages가 명시돼 있습니다. 문서 반영 시차로 보이지만 이건 두 문서 날짜를 바탕으로 한 추론이에요. 실제 적용 전에는 4.113.0 이상인지 먼저 확인해야 마음 편-안.
그리고 send_metrics = false, WRANGLER_SEND_METRICS, wrangler telemetry disable은 Wrangler 익명 사용량 텔레메트리를 제어합니다. 의존성 메타데이터는 별도의 dependencies_instrumentation 설정을 사용하므로 텔레메트리를 껐다고 함께 중단됐다고 볼 근거가 없어요. 두 통제는 따로 설정하고 따로 검증해야 합니다.
실제 배포 검증은 요청 메타데이터까지 봐야 끝나요
먼저 외부 변경 없이 할 일은 간단합니다. 프로젝트의 Wrangler 버전, 실제로 읽히는 설정 파일, dependencies와 devDependencies, 설치 상태를 확인해 테스트 매트릭스를 만드는 것. 특히 프레임워크나 빌드 도구가 .wrangler/deploy/config.json으로 생성 설정을 사용한다면 원본 설정만 보고 끝내면 안 됩니다.
실제 검증은 승인된 격리 계정과 테스트 Worker에서 진행해야 해요. 운영 서비스를 건드리지 않으면서 새 버전만 올리려면 우선 wrangler versions upload를 쓰고, 추가 케이스로 wrangler deploy를 비교합니다. 둘 다 외부 변경이라는 점은 동일함.
[email protected]과[email protected]을 각각 고정하고 실행 전 버전을 기록합니다.- 비민감 공개 패키지를
dependencies와devDependencies에 하나씩 두고 설치합니다. - workspace 또는
file:로컬 패키지, 설치하지 않았거나 해석 불가능한 항목을 비교군으로 둡니다. - 설정 없음,
enabled: false, 4.113.0의exclude_packages를 서로 분리해 업로드합니다. - 승인된 HTTPS 프록시나 Wrangler 디버그 출력으로 multipart
metadata를 확인합니다. - 인증 헤더, 쿠키, 토큰, 계정·스크립트 식별자는 즉시 마스킹하고 패키지 이름·선언 범위·설치 버전만 비교합니다.
CLI에 성공이라고 떴다는 사실만으로 어떤 값이 전송됐는지는 알 수 없습니다. 요청 메타데이터 캡처가 있어야 판정 가능. 이 부분이 귀찮지만 검증의 알맹이예요.
| 테스트 케이스 | 공식 근거에 따른 예상 | 통과 판정 |
|---|---|---|
| 4.110.0, 설정 없음 | 직접·개발 의존성 메타데이터 포함 | 두 종류의 이름·선언 범위·설치 버전이 있고 제외군은 없음 |
4.110.0, enabled: false |
의존성 메타데이터 미전송 | 같은 업로드에서 해당 목록 또는 필드가 없음 |
4.113.0, exclude_packages |
패턴 대상만 제외 | 비대상 공개 패키지는 있고 패턴 대상은 없음 |
| workspace·로컬·해석 불가 | 제외 | 각 비교군이 목록에 없음 |
| 200개 초과 | 최대 200개 | 항목 수가 200 이하이며 선택 순서는 관측값으로만 기록 |
wrangler dev나 wrangler versions deploy, Pages 명령까지 같은 수집 시점이라고 넓히지는 않습니다. 공식 변경 자료에서 확인된 명령은 wrangler deploy와 wrangler versions upload뿐이에요. 200개 초과 시 어떤 항목이 선택되는지, 패키지 관리자별 hoisting·symlink 해석, 서버 저장 기간과 대시보드 표시 여부도 아직 확정할 수 없습니다.
패키지명 노출 위험에 따라 유지·제외·보류를 고르면 됩니다
| 프로젝트 상황 | 권장 판단 | 이유 |
|---|---|---|
| 공개 npm 패키지만 사용하고 이름·버전 전송을 허용 | 기본 활성화 유지 가능 | 별도 설정 없이 향후 분석·공급망 보안 기능의 입력으로 활용 가능 |
| 사내 패키지명이 조직·제품 정보를 드러낼 수 있고 4.113.0 이상 | exclude_packages 우선 검토 |
전체 기능을 끄지 않고 민감한 이름 패턴만 제외 가능 |
| 데이터 처리·보존 조건이 내부 정책상 미확인 | enabled: false로 보류 |
공개 자료만으로 저장 기간과 서버 측 이용 범위를 충분히 확인할 수 없음 |
| 완전한 SBOM이나 즉시 취약점 알림이 필요 | 별도 SCA·SBOM 통제 유지 | 제외 규칙과 200개 상한이 있고 알림은 향후 기능의 기반으로만 발표됨 |
| 모노레포 또는 생성 설정 사용 | 실제 배포 설정 확인 후 적용 | 최상위 전용 키와 생성 설정 리디렉션 때문에 수정 위치가 달라질 수 있음 |
이 기능이 취약점 탐지나 차단, 패치 자동화까지 현재 제공한다고 보기는 어렵습니다. 기본 수집은 편하지만 조직 내부 패키지명이 메타데이터에 드러날 수 있다면 그냥 켜두기엔 찜찜할 수 있어요. 버전을 고정하고, 민감도에 따라 선택 제외나 전체 보류를 고른 뒤, 격리 배포의 요청 데이터로 확인하는 흐름이 가장 현실적입니다.
배포 전 의존성 경고 운영까지 점검하려면 HuntLab의 Dependabot malware alerts 글을 함께 확인하세요.
FAQ
의존성 소스 코드나 lockfile 전체가 Cloudflare로 전송되나요?
공식 자료에서 확인된 필드는 패키지 이름, package.json의 선언 버전 범위, node_modules에서 해석한 설치 버전입니다. 소스 코드나 lockfile 전체, 환경변수 값, 비밀값까지 전송된다고 볼 근거는 없습니다.
dependencies와 devDependencies 중 어느 범위가 포함되나요?
둘 다 포함됩니다. 다만 workspace·로컬·해석 불가능한 패키지는 제외되고 업로드당 최대 200개라는 제한이 있어 완전한 의존성 목록으로 보면 안 돼요.
send_metrics를 끄면 의존성 메타데이터도 중단되나요?
그렇다고 확인할 근거가 없습니다. send_metrics와 wrangler telemetry는 익명 사용량 텔레메트리 설정이고, 의존성 수집은 별도의 dependencies_instrumentation 설정으로 제어합니다.
exclude_packages는 어느 버전부터 쓸 수 있나요?
공식 릴리스에서 확인된 최소 버전은 Wrangler 4.113.0입니다. 4.110.0 도입 시점에는 enabled: false를 이용한 전체 opt-out만 확인됩니다.
wrangler versions deploy도 메타데이터를 수집하나요?
확인한 공식 변경 자료만으로는 그렇다고 말할 수 없습니다. 수집 시점으로 명시된 명령은 wrangler deploy와 wrangler versions upload입니다.
의존성이 200개를 넘으면 어떤 패키지가 선택되나요?
업로드당 최대 200개라는 상한은 확인되지만 선택·정렬 순서는 공개 자료에 없습니다. 격리 테스트에서 실제 목록을 관측값으로 기록하되 그 순서를 보장된 규칙처럼 일반화하지 않아야 합니다.
