osv-scanner 실전 — pnpm, CVE 무시, 오프라인 모드, 자주 만나는 오류

대상: 이미 osv-scanner를 설치했고 막히는 부분이 생긴 사람. 설치가 아니라 도입 다음 날의 질문을 다룹니다. 모든 내용은 공식 문서를 따릅니다.

락파일을 지정하기

# a single lockfile
osv-scanner scan source -L pnpm-lock.yaml
 
# walk a directory
osv-scanner scan source -r ./my-project/

파일명으로 형식을 추론할 수 없을 때는 경로 앞에 사용할 파서를 붙입니다.

# parse an oddly named file as requirements.txt
osv-scanner scan source -L 'requirements.txt:/path/to/extra-requirements.txt'
 
# path containing a colon — lead with a bare ':' to keep filename inference
osv-scanner scan source -L ':/path/to/my:projects/package-lock.json'

자신의 설정을 확인하는 방법

결과가 이상해 보이면 플래그를 더하기 전에 다음 다섯 가지를 확인하세요. 모두 자신의 프로젝트를 들여다보기만 합니다.

종료 코드와 CI에서의 처리

문서는 1126을 결과에 관한 종료 코드로, 129255를 결과와 무관한 오류로 예약해 두고 있습니다. CI 처리를 0은 통과, 1은 탐지 결과, 그 외는 고장 난 스캔으로 세 갈래로 나누면 실패 원인을 훨씬 빨리 찾을 수 있습니다.

특정 취약점 무시하기

스캔하는 디렉터리에 osv-scanner.toml을 둡니다.

[[IgnoredVulns]]
id = "GHSA-xxxx-xxxx-xxxx"
ignoreUntil = 2026-12-31
reason = "Feature is not used and the code path is unreachable; re-evaluate at the December inventory"

• id(필수): 취약점 식별자
• ignoreUntil(선택): 이 날짜가 지나면 다시 보고됩니다
• reason(선택): 그래도 쓰세요. 다음 사람을 위해서이고, 그 사람은 대개 자신입니다

--config=/path/to/config.toml은 디렉터리별 파일을 덮어쓰고 모든 곳에 적용됩니다. 취약점을 무시하면 그 별칭(alias)으로 취급되는 취약점도 함께 무시된다는 점에 주의하세요.

오프라인 모드: 세 플래그, 세 가지 역할

혼란이 가장 많은 부분입니다.

v1 글의 플래그가 동작하지 않을 때

검색 결과의 상당수는 v1용으로 쓰였습니다. 공식 마이그레이션 가이드에 나온 주요 변경은 다음과 같습니다.

osv-scanner <dir>는 지금도 osv-scanner scan source <dir>의 단축형으로 동작합니다. 스크립트에서는 scan source를 명시하면 다음에 읽는 사람에게 의도가 분명해집니다.

흔한 실수와 고치는 법

Maven의 pom.xml은 락파일처럼 해석된 모든 버전을 나열하지 않습니다. osv-scanner는 기본적으로 deps.dev 리졸버(--data-source=native이면 Maven Central)로 전이 의존성 그래프를 계산합니다. 이 작업은 네트워크가 필요하며, --offline과 --no-resolve에서는 건너뜁니다. 완전히 차단된 환경에서 실행하면, 결과는 pom.xml에 직접 적힌 의존성만 다룬다고 보세요.

실제 사례: Log4Shell에 답하기 어려웠던 이유

2021년 12월 Log4Shell(CVE-2021-44228)이 드러났을 때, 많은 조직이 영향 여부를 빠르게 답하지 못했습니다. Log4j를 직접 추가한 적이 없었고, 프레임워크나 다른 라이브러리를 통해 들어와 있었기 때문입니다. CISA의 가이드는 조직에 설치된 소프트웨어를 빠짐없이 목록화해 영향받는 소프트웨어 목록과 대조하라고 요청했습니다.

osv-scanner에 적용하면 두 가지를 확인하는 것입니다.

• 전이 의존성이 실제로 읽히고 있는가: 생태계에 락파일이 있다면 락파일, Maven이라면 해석이 켜진 실행(오프라인도 --no-resolve도 아닌)
• 간접적으로 들어오는 라이브러리가 목록에 정말 들어 있는가: --format json --all-packages로 출력해 확인

공개 당일 "우리는 영향을 받는가?"에 몇 분 안에 답할 수 있는지는, 미리 그 목록을 제대로 갖춰 두었는지에 달려 있습니다.

주변 도구와의 차이

딱 하나만 고르는 것이 실수입니다. 데이터베이스가 다르면 드러나는 것도 다릅니다. 본 사이트는 pnpm audit을 매일 자동 점검으로 돌리고, 락파일을 가로지르는 점검에 osv-scanner를 씁니다.

출처

• OSV-Scanner 문서 — Usage / Offline Mode / Configuration
• Supported Artifacts and Manifests
• OSV-Scanner 문서 — Output(형식과 종료 코드) / Migration Guide(v1에서 v2로)
• CISA — Apache Log4j Vulnerability Guidance

다음으로 읽기

• 시작하기: osv-scanner 설치와 사용법
• 우선순위: 무엇부터 패치할지 정하기(CVSS, EPSS, KEV)
• 사고: Log4Shell(전이 의존성 때문에 무엇을 쓰는지 보이지 않았던 사례)
• 실천: 취약점 대응의 실천 / npm 공급망 웜 방어(영어)