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'))

要启用 Tab 补全，请从你的 PowerShell 配置文件中点源加载随附的脚本：

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

vulncheck 二进制文件也适用于 MacOS、Linux 和 Windows。你可以从我们的 releases 页面 下载预编译的二进制文件。

验证安装

安装完成后，确认二进制文件打印出所需的版本：

vulncheck version

你应该会看到版本、构建日期和 changelog URL。如果出现 "command not found"，请重新打开你的 shell，以便加载新的 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 错误，http_status 会被省略。hint 是可选的补救上下文，仅在消息本身不足以采取行动时出现（例如，指出提供被拒绝令牌的变量）。在 --json 模式之外，会以 hint: ... 的形式渲染到 stderr。

探测命令

在分派工作之前，使用这些命令检查 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 —— 代理根据布尔值进行分派。
# 当 token_source 为 "env" 时，token_env_var 指出提供令牌的变量；
# 否则省略。在 authenticated=false 时也会设置，因此被拒绝的令牌
# 可以追溯到持有它的变量。
# 当环境令牌覆盖了保存在 vulncheck.yaml 中的*不同*令牌时，
# 会添加 token_shadowed: true —— 这是 "我登录了但什么都没变" 的常见原因。
# 否则省略，因此 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 携带所有信息行、进度条、spinner、提示和警告。
• 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

auth

vulncheck auth login
vulncheck auth logout
vulncheck auth status [--json]

login 会引导你完成浏览器或粘贴令牌流程——在 --no-interactive 下会拒绝。status --json 调用 /me 以实际验证令牌；有效负载始终具有 .authenticated: bool 并且无论如何都退出 0（参见探测命令）。

token

vulncheck token list [--limit N] [--page N] [--all]
vulncheck token create <label>
vulncheck token remove <id>
vulncheck token browse

list --json --all 会自动分页并返回一个合并的 JSON 数组。

create --json 返回 {schema_version, id, label, token_on_stderr: true}，并将实际密钥以单行形式打印到 stderr。这样，像 vulncheck token create ci-runner --json > token.json 这样的管道就永远不会将密钥捕获到 JSON 文件中。如果你希望将令牌嵌入 JSON 有效负载中（{... "token": "vc_..."}），请传递 --allow-token-on-stdout——你需要对重定向负责。

browse 是交互式的；在 --no-interactive 下会以退出码 2 拒绝。

indices

vulncheck indices list [<search>]
vulncheck indices browse [<search>]

列出（或交互式浏览）可用索引的目录。list 接受模糊搜索词。

index

vulncheck index list <index> [--full] [--all] [query flags]
vulncheck index browse <index> [query flags]