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

你应该能看到版本、构建日期和变更日志 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": "..."}
# 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）。各命令的标志表仅列出该命令特有的标志。

• auth — 登录 / 登出、检查状态
• token — API 令牌管理
• indices — 列出或浏览索引目录
• index — 查询单个索引
• advisory — 以 CVE Record Format 5.2 查询 v4 公告
• nvd — 查询兼容 NVD API 2.0 的端点
• 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 数组。