# @codacy/tools-trivy-0 中文文档

规范地址：https://npmcn.com/package/%40codacy/tools-trivy-0/

版本：0\.28\.0
npm 元数据更新时间：2026-11-09T13:47:52.626Z
中文译文更新时间：2026-11-10T05:33:21.922Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40codacy/tools-trivy-0
原文对照：https://npmcn.com/package/%40codacy/tools-trivy-0/?lang=original
项目主页：https://github.com/codacy/analysis-cli
源码仓库：https://github.com/codacy/analysis-cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：65.6 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：1 个
- 首次发布：2026-03-24T13:16:05.962Z
- 最新版本发布：2026-11-09T13:47:52.430Z
- 近 30 天下载量：11966（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

Trivy适配器——CLI-mode安全扫描仪

## 安装

```sh
npm install @codacy/tools-trivy-0
```

也可以使用：`pnpm add @codacy/tools-trivy-0`、`yarn add @codacy/tools-trivy-0`、`bun add @codacy/tools-trivy-0`

## README

# @codacy/tools-trivy-0 (英语)

## 目录

-   [概览](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-overview)
-   [伞状图案](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-umbrella-patterns)
-   [与 `codacy-trivy`](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-issue-parity-with-codacy-trivy)
    -   [`sourceId` ——为什么每期都带有CVE](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-sourceid--why-every-issue-carries-its-cve)
    -   [扫描影响所发现的旗帜](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-scan-flags-that-affect-what-is-found)
    -   [行号分辨率](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-line-number-resolution)
    -   [修正版本](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-fix-version)
    -   [已知差异](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-known-divergences)
-   [DB 更新管理](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-db-update-management)
-   [检测恶意包裹](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-malicious-package-detection)
-   [容器图像模式](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-container-image-mode)
-   [更新图案](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-updating-patterns)
-   [更新 Trivy 版本](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-updating-the-trivy-version)
-   [发展](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-development)
-   [维护者的注释](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-notes-for-maintainers)

* * *

## 概览

使用 [特里维](https://trivy.dev/) 二进制. 扫描依赖性和硬码机密中的弱点。 使用CLI执行策略,使用两个独立的扫描模式(可变性+秘密).

| 财产 | 数值 |
| --- | --- |
| 工具标识 | `Trivy` |
| 编码 UUID | `2fd7fbe0-33f9-4ab3-ab73-e9b62404e2cb` |
| 战略 | 国 际 |
| 语文 | 多语种(扫描剂依赖表) |
| 二进制 | `trivy` |
| 文件图案 | `*` (自动侦查依赖情况表) |
| 图案计数 | 6(乳房图案) |

## 伞状图案

Trivy使用伞形图案而不是单个的 CVE图案:

| 模式标识 | 严重性 | 说明 |
| --- | --- | --- |
| `Trivy_vulnerability_critical` | 错误 | 关键脆弱性 |
| `Trivy_vulnerability_high` | 高级 | 高度脆弱性 |
| `Trivy_vulnerability_medium` | 3⁄4 ̄ ̧漯B | 中度脆弱性 |
| `Trivy_vulnerability_minor` | 资讯 | 低脆弱性 |
| `Trivy_secret` | 错误 | 加密机密 |
| `Trivy_malicious_packages` | 错误 | 恶意软件包(通过OSV.dev API) |

## 与 `codacy-trivy`

混凝土云分析库 `codacy-trivy` 多克发动机,所以 本地扫描和上传的仓库必须产生相同的结果 云上扫描寄存器。 此适配器有三块仅存 该行;参考执行为: `codacy-trivy` `internal/tool/tool.go`,而端口则居住在 `src/vuln-mapping.ts` (单位:千美元)`fallbackSearchForLineNumber`, (中文(简体) ), `findLeastDisruptiveFixedVersion`, (中文(简体) ), `purlPrettyPrint`) (中文(简体) ). **只需在文件旁边改变它们.**

### `sourceId` ——为什么每期都带有CVE

Codacy通过一个MD5超过四个键得到一个结果的确定UUID:文件名, 模式 id, 线条的文字被剥去,以及 `sourceId` (单位:千美元)`codacy-worker` `shared/rules/…/rules/components/ResultUUIDRules.scala`) (中文(简体) ).

Trivy报告许多CVE 在一个四重伞模式, 所以两个CVE 在同一个锁文件行 共享这四个键中的三个. **无 `sourceId` 他们崩溃成一个Codacy的结果.** 适配器制作的每期 因此规定:

| 查找 | `sourceId` |
| --- | --- |
| 脆弱性 | `VulnerabilityID` (简历) |
| 秘诀 | 三维的 `RuleID` |
| 恶意包件 | OSV咨询编号`MAL-…`(中文(简体) ) |

`src/metadata.ts` 套装 `needsSourceIdUpload: true`,这就是为什么 `upload` 包括 v2 有效载荷中的字段( mirroring) `needs_source_id_upload` 在Go CLI的Trivy插件列表中). 适配器无 旗帜完全省略了字段——在云引擎没有的地方发送 将会给同样的发现 一个不同的UUID.

### 扫描影响所发现的旗帜

脆弱性扫描通过 **`--detection-priority comprehensive`**匹配 `codacy-trivy`是因为 `DetectionPriority: PriorityComprehensive`它的报告更多 脆弱性——其中一些可能是假阳性因素——确实存在 **gO 需要时 标准文献调查结果**: 与三维0.70核对,a `go.mod` 没有它扫描 报告 **零** `stdlib` 脆弱性(6个问题而不是26个小问题) `go 1.20` 页:1 删除旗帜会默默地放下所有 Stdlib 查找和 启动... 死密码下的处理程序.

### 行号分辨率

三次报告 **无行** 对于脆弱的依赖,所以线被重建:

1.  查查包裹 `Locations[0].StartLine`, (中文(简体) ), **由 PUL 键入** 关键是 云发动机用. `PkgID` 是稀有包 Trivy 报告的次要密钥 没有一个PLL.
2.  在错失或零时,扫描显示的上到下方的第一行 修剪后文本包含软件包名称.
3.  仍然没有什么 释放一个 **文件级别错误** (单位:千美元)`Line numbers not supported`, (中文(简体) ), 被破译为每个文件一个),不是一号线上的问题. 自信的错 地点比诚实的"未知"更糟糕; `codacy-trivy` 做相同的电话 通过 `mapIssuesWithoutLineNumber`。 。 。 .

**go.mod 标准库.** Trivy报告标准文献脆弱性 名为软件包 `stdlib`从字面上从未出现在 `go.mod`三维 [文档](https://trivy.dev/v0.59/docs/coverage/language/golang/#gomod-stdlib) 使用最小值 `toolchain` 财务报告和审定财务报表 `go` 指令,但实际上总是 用途 `toolchain` 当它存在时 因此扫描返回 `toolchain` 线条即刻 当它看到一个, 并且只落回 `go` 读取后的指示行 整个文件。 这不能从Trivy的文档中得出——不要"简化"它.

### 修正版本

三维的 `FixedVersion` 是逗号分隔的 **列表** 每个固定版本 (单位:千美元)`"1.9.0, 1.10.0, 2.0.1"`) (中文(简体) ). 信息只报告破坏最小的一条: 按语义分类,绝对大于已安装版本的最小候选人 版本。 当没有比这更大的候选人时(或者这个计划没有产生——鲁比的) `~>`, (中文(简体) ), 马文修饰者,Trivy的生值通过 `FixedVersion` 实值 空信件读取 `(no fix available)`。 。 。 .

消息格式, 匹配云引擎逐字记录 :

```
Insecure dependency {pretty-printed PURL} ({CVE}: {title}) (update to {version})
Insecure dependency {pretty-printed PURL} ({CVE}: {title}) (no fix available)
```

比较使用 Go 的端口 `golang.org/x/mod/semver` (单位:千美元)`compareSemver`(没有) npm semver:它接受两个组件版本,如 `v1.2`治疗 无法解析的版本比任何有效版本都低,因此无法解析 计划通过而不是被排序.

### 已知差异

两者都是故意的 `docs/tech-debt.md`。 。 。 .

-   **修复版本命令.** `codacy-trivy` 排序候选字符串 _在此之前_ 添加 `v` 前缀,所以 `x/mod/semver` 把它们都看成无效的,比较一下 并回到一个词典上的结节——挑 `1.10.0` 结束 `1.9.0`。我们按前缀的值排序,然后返回真正最小的值.
-   **包裹没有聚氨酯.** `codacy-trivy` 完全摆脱了这些弱点. 我们保留它们,按名称解决线 并把包裹变成 `name@version`因为默默地降低真正的脆弱程度比 与"云"不同的信息.
-   **密电短信.** 我们把秘密的分类附在一起 (单位:千美元)`Possible hardcoded secret: {title} ({category})`);云引擎停止在 标题.
-   **离线扫描.** `codacy-trivy` 套装 `OfflineScan: true` (其容器为: 我们没有,所以Trivy可能解决一些Java/Maven的依赖关系 网络和汇报这些生态系统的更准确的结果。 没有 在此更改: 使本地扫描的准确度降低, 以匹配空格限制 不会是错交易.

## DB 更新管理

适配器读了Trivy的 `metadata.json` (单位:千美元) `{cacheDir}/db/metadata.json`改为: 确定脆弱性数据库是否仍然新鲜。 这个 `NextUpdate` 字段 告诉我们Trivy什么时候 期待下一次DB更新.

| 假设 | 行为 |
| --- | --- |
| DB 新鲜 (`now < NextUpdate`(中文(简体) ) | `--skip-db-update --skip-java-db-update` 通过了——没有网络检查 |
| DB stale (英语:`now >= NextUpdate`(中文(简体) ) | 常规更新的 Trevy 检查 |
| 第一运行( 无元数据) | Trivy 下载 DB (~ 40MB) |
| 容器模式 | 总是跳过 DB 更新( DB 预封) |

## 检测恶意包裹

通过查询检测已知的恶意软件包 [OSV.dev 批次 API](https://api.osv.dev/v1/querybatch)。 。 。 . 弱点扫描输出上的回扣——来自 `--list-all-pkgs` 与 OpenSSF 恶意软件包索引相参照(`MAL-*` 身份证.

-   涵盖14个生态系统:npm、PyPI、Go、RubyGems、coxes.io、Nuget、Maven、Packagist、Pub、Hex、CoanCenter、CocoaPods、SwiftURL、Conda
-   每个API呼叫使用10秒超时
-   在 API 失败( 网络出错, 超时) 上, 记录一个警告并跳过 —— 绝不屏蔽核心扫描
-   信件格式 : `Malicious package detected: {name}@{version} ({MAL-ID}). {summary}`

## 容器图像模式

除了仓库扫描之外,适配器执行可选 `containerImage` 能力 (单位:千美元)`src/image.ts`),这支持了CLI的 `container-scan` 财务报告和审定财务报表 `upload-sbom` 命令。 描述符 广告上 `scansContainerImages: true`。 。 。 .

| 方法 | 召集 |
| --- | --- |
| `scan` | `trivy image --format json --cache-dir … [--skip-db-update --skip-java-db-update] --scanners vuln [--ignore-unfixed] --severity … --pkg-types … <image>` |
| `generateSbom` | `trivy image --format cyclonedx|spdx-json --output <path> --cache-dir … <image>` |

-   图像引用被重新验证 `validateImageReference` 在它变成一个正弦之前 元素,即使跑者先验证它.
-   `--exit-code` 是故意的,这是故意的 **没有** 通过了。 发现计数来自解析的JSON,所以任何 非0出局是一个真正的失败——没有像 cli-v2 这样的 stderr heuristics 来决定 _是否为_ 失败了.
-   调查结果再利用 `describeVulnerability` (单位:千美元)`src/findings.ts`),同样的映射仓库扫描 用途:按严重程度分列的伞状图案, `codacy-trivy`'消息格式, CVE 为 `sourceId`, (中文(简体) ), `UNKNOWN` 掉下来了 地点是Trivy的 `Target` (OS层或内相显示) 第1行.
-   `generateSbom` 只有在 Trivy 退出 0 时才成功 **财务报告和审定财务报表** 写入非空文件 .
-   每个特丽薇产卵(两种模式) `TRIVY_SKIP_VERSION_CHECK=true`和失败的分解 结束 `summarizeTrivyStderr` (单位:千美元)`src/trivy-errors.ts`)而不是被回放:特瑞的"斯德"(Trivy's stderr is 一个日志流(INFO行,ANSI版本通知,然后是FATAL Go出错- wrap链),以及文本 在240个字符中, 物质会切换出错误, 这在事发前是用来切除的。 洞穴 而不是说 `--skip-version-check`因为一个更古老的全球Trivy会拒绝这个旗帜.
-   `test/fixtures/image-scan.json` 从真实中修剪 `trivy image` 运行对手 `nginx:1.21.0-alpine`,加上一个合成 `UNKNOWN` 找到和合成图书馆找到. `CODACY_TRIVY_IMAGE_IT=1 pnpm test` 对真实登记册进行选入整合测试.

## 更新图案

```bash
# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json
```

## 更新 Trivy 版本

1.  更新 `preferredVersion` 内 `src/metadata.ts`
2.  如果发布格式改变, 更新下载 URL 模板
3.  运行 `pnpm test` 以验证兼容性

## 发展

```bash
pnpm build    # Build with tsup
pnpm test     # Run tests (requires trivy in PATH or auto-install)
```

## 维护者的注释

-   特里维跑道 **两个单独的扫描引用**:一个是脆弱性(`--scanners vuln --detection-priority comprehensive`)和为机密(`--scanners secret`)) 在vuln扫描输出上发现恶意包回扣(没有额外引用). 扫描的运行取决于启用哪个伞模式 .
    
-   脆弱性数据库在第一次运行时懒散地下载到 `--cache-dir ~/.codacy/cache/trivy/`. 首先需要上网。 DB 固态通过 `metadata.json` → `NextUpdate`。 。 。 .
    
-   三角扫描 **目录**,没有文件列表,也没有包含旗帜。 两次扫描都把寄存器根作为目标,所以 `Target` ,结果被过滤到 `ctx.targetFiles` 后来 这个 **秘密扫描** 也通过 `--skip-dirs` 对于每个没有目标文件的目录( )`src/scan-scope.ts`, (中文(简体) ), `computeSkipDirs`) (中文(简体) ). 这是没有损失的,因为一个秘密 被报告在它的文件。 在此之前,分析一个文件 走了整个树两次, `node_modules` 包括,在一个大型仓库上花费了几分钟时间。 跑步有两起
    
    -   **脆弱性扫描从未被检查过.** 其发现取决于其他目录中的文件. 纱线工作室的成员 `package.json` 文件决定 `yarn.lock` 条目是 dev- only, 所以跳过 `packages/` 使Trivy报告依赖性的脆弱性.
    -   **当一个本地人出现时, 便不打探 `trivy.yaml` 正在使用中.** 命令行 `--skip-dirs` _替换_ {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}这个配置 `skip-dirs` 而不是加入,所以用户的排除会停止应用.
    
    如果跳过列表不符合Windows命令行,扫描也会被取消.
    
-   脆弱性扫描(以及重新使用其软件包清单的恶意包装检查)是 **跳过** 当每个目标文件都有源代码或文档扩展名时(`needsVulnScan`) (中文(简体) ). 这份清单是一份有意拒绝的名单:其中缺少的扩展只花费了速度,而在允许名单中被遗忘的明显名称则会默默地放弃发现。 永远不要添加数据格式( N)`.json`, (中文(简体) ), `.yaml`, (中文(简体) ), `.toml`, (中文(简体) ), `.xml`, (中文(简体) ), `.lock`, (中文(简体) ), `.txt`对它.
    
-   `Target` 改为在匹配前先向前划 `ctx.targetFiles`,因此一个Windows风格的路径永远无法默默地匹配任何事物.
    
-   二进制从 GitHub 版本下载为 `.tar.gz` 存档 .
    
-   脆弱性严重性(CRITICAL/HIGH/MEDIUM/LOW)与相应的总括图样相映射.
    
-   信件格式、行解析度和 `sourceId` 这些都是对等的关键——见 [与 `codacy-trivy`](https://npmcn.com/package/%40codacy/tools-trivy-0/#readme-issue-parity-with-codacy-trivy) 在接触他们之前.
    
-   无法解决线条的弱点变成文件级别 `AnalysisError` (单位:千美元)`kind: "LineNumbersNotSupported"`),每个文件一个,而不是1号线的一期.
    
-   恶意包检测使用OSV.dev批量API. 如果失败,它确是优雅的.
    
-   配置文件: 检查 `trivy.yaml` 在还原根.

## 常见问题

### @codacy/tools-trivy-0 是什么？

Trivy适配器——CLI-mode安全扫描仪

### 如何安装 @codacy/tools-trivy-0？

在项目目录运行 npm install @codacy/tools-trivy-0，或使用 pnpm add / yarn add / bun add。

### @codacy/tools-trivy-0 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @codacy/tools-trivy-0 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @codacy/tools-trivy-0 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @codacy/tools-trivy-0 可以商用吗？

@codacy/tools-trivy-0 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @codacy/tools-trivy-0 的下载量有多少？

根据 npm 官方下载统计，@codacy/tools-trivy-0 在 2026/10/10 – 2026/11/08 这 30 天内被下载 11,966 次，日均约 399 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @codacy/tools-trivy-0 还在维护吗？

最新版本 0\.28\.0 发布于 2026/11/09（今天）；至今共发布 36 个版本，其中过去 12 个月发布了 36 个；首次发布于 2026/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。