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": "..."}
# Exit 0 even when authenticated=false — agents dispatch on the bool.
# token_env_var names which variable supplied the token when token_source is
# "env"; omitted otherwise. Set when authenticated=false too, so a rejected
# token can be traced to the variable holding it.
# token_shadowed: true is added when an environment token is overriding a
# *different* token saved in vulncheck.yaml — the usual cause of "I logged
# in but nothing changed". Omitted otherwise, so the CI shape (env token
# only, no config file) never reports shadowing.

vulncheck commands
# {"schema_version": 1, "root": {"name":"vulncheck", "subcommands":[...]}, ...}
# Machine-readable dump of the whole command tree — every subcommand,
# every flag (with type + default + usage), aliases, deprecation. Use
# this instead of parsing --help. Auth is not required.

페이지네이션

vulncheck token list --json --limit 10 --page 2
vulncheck token list --json --all       # auto-paginate, single combined array
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)를 허용합니다. 명령별 플래그 표에는 해당 명령에 특화된 항목만 나열됩니다.

인기

cli