VulnCheck Logo

VulnCheck CLI

vulncheck는 명령줄에서 VulnCheck API에 접근할 수 있게 해줍니다. 인덱스 탐색, 백업 관리, 취약점 스캔 기능을 터미널로 가져옵니다.

설치

제공되는 설치 스크립트

설치 스크립트를 사용하면 vulncheck를 쉽게 설치할 수 있습니다. 운영 체제에 맞는 스크립트와 방법을 선택하세요:

macOS 및 Linux

터미널을 열고 다음을 실행하세요:

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash

시스템 전체 설치(sudo 필요) 또는 로컬 사용자 설치 중에서 선택하라는 메시지가 표시됩니다.

[!NOTE] 설치 스크립트는 비대화형 설치 옵션도 지원합니다:

--sudo — 프롬프트 없이 시스템 전체 설치

--non-sudo — 프롬프트 없이 로컬 사용자 설치

--help 또는 -h — 사용 가능한 모든 옵션 보기
curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash -s -- --help

Windows

PowerShell을 열고 다음을 실행하세요:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.ps1'))

탭 완성을 활성화하려면 PowerShell 프로필에서 번들 스크립트를 dot-source 하세요:

Add-Content -Path $PROFILE -Value ". '$env:LOCALAPPDATA\Programs\vulncheck\share\powershell\vulncheck.ps1'"

vulncheck 바이너리는 MacOS, Linux, Windows용으로도 제공됩니다. 릴리스 페이지에서 미리 컴파일된 바이너리를 다운로드할 수 있습니다.

설치 확인

설치가 완료되면 바이너리가 원하는 버전을 출력하는지 확인하세요:

vulncheck version

버전, 빌드 날짜, 변경 로그 URL이 표시되어야 합니다. "command not found"가 표시되면 새 PATH가 적용되도록 셸을 다시 열고 다시 시도하세요.

구성

vulncheck auth login을 실행하여 VulnCheck 계정으로 인증하세요.
또는 vulncheck는 VULNCHECK_API_TOKEN 환경 변수를 인식합니다 — VulnCheck SDK와 MCP 서버에서 사용하는 것과 동일한 이름입니다. 레거시 VC_TOKEN도 여전히 작동하며, 둘 다 설정된 경우 우선합니다.
vulncheck auth만 실행하면 상태 확인 및 로그아웃과 같은 다른 옵션이 표시됩니다.

두 환경 변수 중 하나가 저장된 구성 파일보다 우선합니다. 따라서 auth login과 auth logout은 둘 중 하나가 설정되어 있으면 거부합니다 — 그렇지 않으면 아무 효과도 없는 변경을 하고 성공을 보고하게 되기 때문입니다. vulncheck auth status를 실행하여 활성 토큰이 어느 소스, 어느 변수에서 왔는지 확인하세요.

에이전트 / 스크립트 사용

CLI는 스크립트와 AI 에이전트에서 안전하게 구동할 수 있도록 설계되었습니다. 이 섹션은 계약입니다 — 아래 표면은 릴리스 간에 안정적으로 유지될 예정입니다(추가는 호환성을 깨는 변경이 아니며, 이름 변경/제거는 그렇습니다).

전역 플래그

플래그	효과
`--json`	stdout에 JSON을 출력하고, 정보/진행 줄은 stderr로 라우팅하며, 오류는 구조화된 봉투로 출력합니다.
`--quiet`	정보 출력을 억제합니다. 오류와 페이로드는 여전히 렌더링됩니다.
`--no-color`	ANSI 스타일링을 비활성화합니다. `NO_COLOR` 환경 변수도 인식합니다.
`--no-interactive`	TUI 프롬프트에서 차단을 거부하며, 프롬프트가 필요한 명령은 대신 오류를 반환합니다. `--json`, 비 TTY stdin/stdout, 그리고 `CI` / `BUILD_NUMBER` / `RUN_ID` 환경 변수 중 하나라도 있으면 암시됩니다.

환경 변수

변수	효과
`VULNCHECK_API_TOKEN`	API 토큰이며 권장 이름입니다 — VulnCheck SDK 및 MCP 서버와 공유됩니다. `~/.config/vulncheck/vulncheck.yaml`보다 우선하며, 설정되어 있는 동안 `auth login`과 `auth logout`은 무시될 파일을 작성하는 대신 거부합니다.
`VC_TOKEN`	레거시 별칭으로, 여전히 완전히 지원되며 둘 다 설정된 경우 `VULNCHECK_API_TOKEN`보다 우선합니다, 따라서 기존 설정의 자격 증명이 변경되지 않습니다. 구성 파일로 대체하려면 둘 다 지우세요. `auth status`는 어느 것이 사용 중인지 보고합니다.
`NO_COLOR`	비어 있지 않은 값이면 ANSI 스타일링이 비활성화됩니다.
`CI` / `BUILD_NUMBER` / `RUN_ID`	이 중 하나라도 설정되면 비대화형 모드(프롬프트 없음)를 의미합니다.

종료 코드

코드	의미
0	성공.
1	일반 / 내부 오류.
2	유효성 검사 실패(잘못된 인수, 필수 플래그 누락, 잘못된 요청).
3	인증 실패(토큰 없음 또는 서버가 토큰을 거부함).
4	리소스를 찾을 수 없음(HTTP 404, 해당 인덱스 없음).
5	속도 제한(HTTP 429).
6	네트워크 실패(DNS, 연결 거부, 시간 초과).
130	SIGINT로 취소됨(POSIX `128 + 2`).

오류 봉투

--json 모드에서 오류는 stdout으로 다음과 같이 출력됩니다:

{
  "schema_version": 1,
  "error": {
    "code": "auth_required",
    "message": "...",
    "http_status": 401,
    "hint": "..."
  }
}

code는 다음 중 하나입니다: internal, validation, auth_required, auth_invalid, not_found, rate_limited, network, bad_request, cancelled. http_status는 비 HTTP 오류의 경우 생략됩니다. hint는 선택적 해결 컨텍스트로, 메시지만으로는 실행 가능하지 않을 때만 존재합니다(예: 거부된 토큰을 제공한 변수 이름 지정). --json 모드 외부에서는 stderr에 hint: ...로 렌더링됩니다.

프로브 명령

작업을 디스패치하기 전에 CLI 자체를 검사하려면 다음을 사용하세요:

vulncheck version --json
# {"schema_version": 1, "version": "...", "build_date": "...", "changelog_url": "..."}

vulncheck auth status --json
# {"schema_version": 1, "authenticated": true, "token_source": "env",
#  "token_env_var": "VC_TOKEN", "user": "...", "email": "..."}
# authenticated=false인 경우에도 종료 코드 0 — 에이전트는 bool로 디스패치합니다.
# token_env_var는 token_source가 "env"일 때 토큰을 제공한 변수 이름을 지정하며,
# 그렇지 않으면 생략됩니다. authenticated=false일 때도 설정되므로 거부된
# 토큰을 보유한 변수로 추적할 수 있습니다.
# token_shadowed: true는 환경 토큰이 vulncheck.yaml에 저장된 *다른* 토큰을
# 재정의할 때 추가됩니다 — "로그인했는데 아무것도 바뀌지 않았다"의 일반적인 원인입니다.
# 그렇지 않으면 생략되므로 CI 형태(환경 토큰만, 구성 파일 없음)는
# 섀도잉을 보고하지 않습니다.

vulncheck commands
# {"schema_version": 1, "root": {"name":"vulncheck", "subcommands":[...]}, ...}
# 전체 명령 트리의 기계 판독 가능 덤프 — 모든 하위 명령, 모든 플래그
# (타입 + 기본값 + 사용법 포함), 별칭, 사용 중단. --help를 파싱하는 대신
# 이것을 사용하세요. 인증은 필요하지 않습니다.

페이지네이션

vulncheck token list --json --limit 10 --page 2
vulncheck token list --json --all       # 자동 페이지네이션, 단일 결합 배열
vulncheck index list <index> --json --all

배치 입력

purl, cpe, tag, pdns는 위치 인수, stdin(파이프된 경우), 또는 --from-file <path>를 통해 여러 입력을 받습니다. 파일의 빈 줄과 #로 시작하는 주석은 무시됩니다. 배치 모드에는 --json이 필요합니다.

# Stdin
cat purls.txt | vulncheck purl --json

# File
vulncheck cpe --from-file ./cpes.txt --json

배치 봉투는 입력 순서대로 입력당 한 행씩 있는 안정적인 배열입니다:

[
  {"input": "pkg:npm/[email protected]", "data": { ... }},
  {"input": "pkg:bad/string", "error": "no result returned for this purl"}
]

취소

SIGINT / SIGTERM은 컨텍스트 전파를 통해 진행 중인 HTTP 요청을 깔끔하게 취소합니다. 장기 실행 작업(scan, offline sync, backup download)은 취소를 존중하며, 해당되는 경우 종료 시 부분 파일이 제거됩니다.

JSON 출력 규율

--json이 설정되면:

stdout은 오직 JSON 페이로드(또는 위의 오류 봉투)만 전달합니다.
stderr는 모든 정보 줄, 진행 표시줄, 스피너, 프롬프트, 경고를 전달합니다.
TUI 요소(bubbletea, huh 프롬프트)는 자동으로 억제됩니다.

즉, vulncheck <cmd> --json | jq는 항상 작동합니다 — tail/sed 정리가 필요하지 않습니다.

사용 가능한 명령

아래의 모든 명령은 전역 플래그(--json, --quiet, --no-color, --no-interactive, --help/-h)를 받습니다. 명령별 플래그 표는 해당 명령에 특정한 것만 나열합니다.

auth — 로그인 / 로그아웃, 상태 확인
token — API 토큰 관리
indices — 인덱스 카탈로그 나열 또는 탐색
index — 하나의 인덱스 쿼리
advisory — CVE Record Format 5.2로 v4 권고 쿼리
backup — 인덱스 또는 권고 피드 백업 다운로드 또는 서명된 URL 가져오기
cpe — CPE에 대한 CVE 조회(단일 또는 배치)
purl — PURL에 대한 CVE 조회(단일 또는 배치)
tag — IP 인텔리전스 태그 멤버십 조회
pdns — 패시브 DNS 목록 멤버십 조회
rule — 초기 접근 인텔리전스 규칙 조회
scan — 디렉터리 스캔(SBOM + 취약점 조회)
offline — 인덱스를 로컬로 동기화하고 API를 호출하지 않고 쿼리
version — CLI 버전 출력
upgrade — CLI를 제자리에서 업데이트

인기

cli