# @codacy/tools-opengrep-1 中文文档

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

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

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

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

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

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

## 中文简介

Opengrep 适配器—— CLI- mode 多语言 SAST 扫描器

## 安装

```sh
npm install @codacy/tools-opengrep-1
```

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

## README

# @codacy/tools-opgrep-1 (英语)

## 目录

-   [概览](https://npmcn.com/package/%40codacy/tools-opengrep-1/#readme-overview)
-   [规则捆绑](https://npmcn.com/package/%40codacy/tools-opengrep-1/#readme-rule-bundling)
-   [更新图案](https://npmcn.com/package/%40codacy/tools-opengrep-1/#readme-updating-patterns)
-   [更新规则](https://npmcn.com/package/%40codacy/tools-opengrep-1/#readme-updating-rules)
-   [更新 Opengrep 版本](https://npmcn.com/package/%40codacy/tools-opengrep-1/#readme-updating-the-opengrep-version)
-   [发展](https://npmcn.com/package/%40codacy/tools-opengrep-1/#readme-development)
-   [维护者的注释](https://npmcn.com/package/%40codacy/tools-opengrep-1/#readme-notes-for-maintainers)

* * *

## 概览

多语言的 SAST (Static 应用程序安全测试) 扫描仪 [打开( O)](https://opengrep.dev/) 二进制. 通过YAML规则文件支持30+语言. 使用CLI执行策略.

| 财产 | 数值 |
| --- | --- |
| 工具标识 | `Semgrep` (legacy,用于Codacy平台相容性) |
| 显示名称 | `Opengrep` |
| 编码 UUID | `6792c561-236d-41b7-ba5e-9d6bee0d548b` |
| 战略 | 国 际 |
| 语文 | 30+ (Python, JavaScript, TypeScript, Java, Go, Ruby, C, C++等) |
| 二进制 | `opengrep` |
| 文件图案 | 由上述语言衍生出来的 ~70 扩展 `Dockerfile` |
| 图案计数 | ~2500 时 |
| 额外依赖性 | `yaml` (用于 YAML 规则配置解析/ 生成) |

## 规则捆绑

Opengrep使用YAML规则文件进行检测. 适配器将~2500规则捆入 `src/rules.yaml`,来源于:

1.  **打开/打开规则** - 登记规则,与Codacy图像相同
2.  **GitLab SAST 规则** 麻省理工学院有执照,从 `gitlab.com/gitlab-org/security-products/sast-rules`
3.  **编码习惯规则** —— 说 `docs/codacy-rules*.yaml` 内 `codacy/codacy-opengrep`

捆绑起来 `src/rules.yaml` 实值 **承诺保存库** 为了一致性和可复制性.

### 保持与科达西图像同步

所有三个来源,他们的被钉住的承诺 和他们的文件过滤器都是从 `codacy/codacy-opengrep`是因为 `internal/docgen/parsing.go`。保持这样:图像是 参考执行情况,以及 `scripts/fetch-rules.mjs` 说每个部件的上游函数 是从哪来的.

镜像成本中的三个错误 **2534种模式中的296种(12%)**他们都沉默了.. 模式在 `patterns.json`, (中文(简体) ), `init --auto` 允许它, 配置 声称它是活跃的 它只是永远不要开火:

-   **规则 ID 来源于文件路径 .** GitLab ids 在文件中写入, 必须是 逐字记录。 路径导出对顶层树的右侧(`java/crypto/rule-X.yml` 真的很坚持 `java_crypto_rule-X`),对于许可级别之一是错误的,其中 `rules/lgpl-cc/properties/spring/accesscontrol/rule-Y.yml` 持有 `properties_spring_rule-Y`编辑 最尖锐的情况是 `rule-JwtDecodeWithoutVerify.yml`,其编号使用下划线 文件名使用连字符 。 588 GitLab规则中的265条由此被丢失.
-   **登记册来源在上游 `semgrep/semgrep-rules`**而不是Opengrep的叉子 两者之分 大部分的id,所以输出看起来是可信的,而个别规则却丢失了.
-   **YAML被逐行读取并重写.** 腐败的多线流出- 已生成文件已停止解析, 然后报告 opengrep _整个运行的零结果_ 而不是错误,它每逢 `tests/` 目录,一些运出规则所在的地方.

`test/rules-coverage.test.ts` 是守护者:如果编目模式没有规则,则失败,如果 生成的文件不解析。 运行 `pnpm fetch-rules` ;脚本打印 孤儿身份证明.

## 更新图案

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

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

模式 ID 遵循格式 `Semgrep_python.lang.security.audit.exec-detected.exec-detected` (dot-分出规则路径).

## 更新规则

```bash
# Re-fetch and bundle rules from all three sources
pnpm fetch-rules

# This clones the rule repos, extracts matching rules, and writes src/rules.yaml
# Only rules whose IDs match src/patterns.json are included — and the script now
# warns loudly about the reverse, a catalogued pattern with no rule to run.

# Commit the result
git add src/rules.yaml
```

这个 `fetch-rules` 脚本( e)`scripts/fetch-rules.mjs`:

-   克隆 `semgrep/semgrep-rules` 在坚固的战火中
-   克隆人GitLab SAST规则(最新)
-   克隆 `codacy/codacy-opengrep` 习惯规则
-   提取规则, 指定基于路径的ID
-   过滤到只匹配规则 `src/patterns.json`
-   将缩写 YAML 写入 `src/rules.yaml`

要更新被绑定的规则, 请编辑 `SEMGREP_RULES_COMMIT` 内 `scripts/fetch-rules.mjs`。 。 。 .

## 更新 Opengrep 版本

1.  更新 `preferredVersion` 内 `src/adapter.ts`
2.  运行 `pnpm test` 以验证兼容性
3.  考虑重新运行 `pnpm fetch-rules` 如果新版本支持新的规则语法

## 发展

```bash
pnpm build        # Build with tsup
pnpm test         # Run tests (requires opengrep in PATH)
pnpm fetch-rules  # Re-bundle rules from upstream sources
pnpm prefetch     # Re-fetch pattern metadata from Codacy API
```

**安装二进制 :**

适配器自动安装打开grep `~/.codacy/tools/` 当运行时 `--install-dependencies` (不需要手工步骤):

```bash
codacy-analysis analyze . --tool opengrep --install-dependencies
```

`install()` 从 GitHub 发布时下载匹配的静态链接二进制 (无归档可解开)和 `chmod +x`因为它(不在Windows上). 这个 平台/arch/libc — 资产映射镜 opengrep 官方 `install.sh` 财务报告和审定财务报表 `install.ps1`数字 :

| 平台 | 资产 |
| --- | --- |
| macOS x64 | `opengrep_osx_x86` |
| 马可斯臂64 | `opengrep_osx_arm64` |
| Linux x64 (glibc) (英语) | `opengrep_manylinux_x86` |
| Linux arm64 (glibc) (英语) | `opengrep_manylinux_aarch64` |
| Linux x64( 穆斯/ 阿尔卑斯) | `opengrep_musllinux_x86` |
| Linux arm64(母马/高山) | `opengrep_musllinux_aarch64` |
| 视窗 x64 | `opengrep_windows_x86.exe` |
| Windows arm64(已装入) | `opengrep_windows_x86.exe` |

要手动安装 :

```bash
curl -fsSL https://raw.githubusercontent.com/opengrep/opengrep/main/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/opengrep/opengrep/main/install.ps1 | iex
```

## 维护者的注释

-   **预设绘图`src/pattern-mappings.json`(中文(简体) )**: 前缀是上游规则路径 (单位:千美元)`Semgrep_<lang>.<framework>.…`)),它已经命名了框架,所以这个映射是 前缀只 —— Opengrep 的标签为主题(`security`, (中文(简体) ), `audit`并会过度竞争。 22个密钥 添加,从缺少框架的重置中取出 ~91 默认模式: Pyramid (16), PyCryptodome (12), Kubernetes/Helm (14,通过) `yaml.kubernetes.` + 键 `codacy.k8s.`; 数据 `kubernetes` 信号匹配 松动的列表 `k8s/`编号 :`kubernetes/`编号 :`manifests/`不仅仅是 `kustomization.yaml`,或 最常见的布局会失去全部 14), GitHub 动作 (5),AWS CDK (5),Jinja2 (2),以及较小的Boto3/Twilio/Android/Sequelize/Doctrine家族. YAML语言家庭最为重要:在此之前,他们发射任何含有单声道的回弹 `.yaml` 文档.
    
    这个 `*.aws-lambda.` 包( Python、 JavaScript、 Ruby 和 Go 三十四个默认) 以 **页:1** 键 - `serverless-framework`, (中文(简体) ), `cloudformation`, (中文(简体) ), `aws-cdk`, (中文(简体) ), `boto3`, (中文(简体) ), `aws-sdk`, (中文(简体) ), `aws-sdk-go` 财务报告和审定财务报表 `lang:Terraform`。掌上电脑代码没有自己的显示;唯一的 证据是它是如何部署的 或者它叫哪个SDK 任何七个都足够了. Terraform 赚了一把钥匙 因为布置了一辆Lambda `aws_lambda_function` 没有别的了 跟踪,SDK的分录 不得不学习npm的v2 `aws-sdk`,Go's v1 (英语) `aws-sdk-go` 还有PyPI的 `botocore`编号 :`aws-lambda-powertools` - 兰布达跑步时间 预装机器人3,所以它经常缺席 从 `requirements.txt` 完全没有.
    
    `Semgrep_python.jinja2.` 索赔人 `jinja2` **财务报告和审定财务报表** `flask`: 火焰硬依赖金贾2, 如此直视 `jinja2` 单是声明就放弃了两个错误- 严重性自定义规则 从最真实的火焰回放.
    
    蓄意地仍然普遍, 以测试为戒, 所以它保持这样: `*.lang.*` (通用每语包), `csharp.dotnet.` (平台,不是图书馆), `terraform.*` (已登入 `Terraform` 语言, `problem-based-packs.*` (各语种),和 `apex.` 编号 : `generic.visualforce.` - 顶级和视觉力量 仅限销售 _语言_,所以语言门 已经瞄准它们 并按键它们上 `salesforce` 只会增加一种方式 想念他们 在销售力回购 没有 `sfdx-project.json`。 。 。 .
    
-   **工具标识是 `Semgrep`** 与 Codacy 平台的相容性。 这个 `displayName` 设置为 `Opengrep` 用于 CLI 显示。 不与Codacy平台团队协调,永远不要更改工具ID.
    
-   **配置化**: 当指定codacy 模式时,适配器加载 `src/rules.yaml`,过滤以启用规则,并写入过滤后配置 `.codacy/generated/opengrep-rules.yaml`。 。 。 .
    
-   **检查为空规则 ID**: 每张引用证 `--no-rewrite-rule-ids`。没有它 Opengrep 前缀 `check_id` 与配置文件的目录相对 cwd (`.codacy/generated/x.yaml` → `codacy.generated.`)),而适配器曾复制该路径数学以再次剥去前缀——从未在Windows上核实过,其中不匹配会在被启用的样板检查时默不作声地放下每个发现. 用旗子将规则ID映射到每个OS上直接显示的图案ID.
    
-   **配置文件搜索**数字 : `.semgrep.yaml`, (中文(简体) ), `.opengrep.yaml`, (中文(简体) ), `.semgrep.yml`, (中文(简体) ), `.opengrep.yml` (按此顺序排列).
    
-   **Opengrep 错误**: 从 Opengrep 的 JSON 解析错误( 语法错误, 部分解析) `errors` 数组转换为结构 `AnalysisError` 对象为 `filePath`. Stderr (扫描状态表) 仅记录在调试级别上.
    
-   **规则标识格式**: 使用Semgrep规则 `{dir}.{filename}.{ruleId}` GitLab 规则 `{dir}_{filename}` (下分数) Codacy自定义规则保留其原始ID.
    
-   **安装/ 二进制下载**数字 : `install()` 从 `https://github.com/opengrep/opengrep/releases/download/v{version}/{asset}` 财务报告和审定财务报表 `chmod +x`如果它进入 `~/.codacy/tools/`。释放标签带有 `v` 前缀( e)`v1.30.0`虽然 `preferredVersion` 没有。 在 Linux 上检测出 libc 味道 `ldd /bin/sh` 探测器`musl` → musllinux, else manylinux; 检测失败回落到glibc/manylinux. 在 Windows 上,二进制保存为 `opengrep.exe`; 上游仅建有 x64, 而 `install.ps1` 也安装在ARM64上(已装入),所以我们也这样做. **从opengrep 2.0.0开始 Windows 资产变成 `opengrep_windows_x86.zip`** (exe + DLLs)——起落架 `preferredVersion` 超过2.0需要一个取出步骤。 argv 块预算下降至 `MAX_ARGV_BYTES` (30,000) 在Windows上,其命令行被封顶为32,767个字符. 与安装.sh不同,Codacy管理的安装确实 **没有** 校验联合签名 `.cert`编号 :`.sig` 签字——如果签字核查成为一种要求,则取出这些兄弟般的资产,并在chmod之前进行验证.
    
-   **Argv 大小块( 没有目录行走)**:适配器总是通过 Opengrep a **清晰的文件列表** ——跑者已经被被git-ignored,排斥-被过滤的目标设定——因此Opengrep从不走寄存树本身. `chunkFilesByArgvBudget()` 将列表分割为 **最少,最大的一个** 每个适合的块 `ARGV_BYTE_BUDGET` (200KB,列在 `ARG_MAX`),每个块被扫描 `opengrep scan` 引用;发现和出错合并成块. 弹出 **大小, 不计数**:每次引用重新编译 `rules.yaml`,因此少/多块摊还固定成本。 先前的目录/“root”倒置被删除,因为大型倒置(Repo根的一个单一跟踪文件崩溃了最小覆盖的凹陷到 `.`它使Opengrep走出整个树——重新扫描排除/生成/复仇文件,并在跑者10分钟的限时时间出局.
    
-   **文件大小上限**: 引用通过 `--max-target-bytes 1000000` (~1 MB). 这还原了 Opengrep 的默认大小上限—— 适配器先前通过 `0`,哪个 **禁用** 如此巨大的生成/微缩的捆绑被扫描 并占据运行时间 上限适用于明确列出的文件(在v1.16.4上核实)。 说明: `--exclude-minified-files` 实值 **没有** 使用 —— 除非 `--experimental` (不同的引擎)也被通过,所以我们依靠大小盖来取而代之. (在文件到达适配器之前,跑者还集中执行每个文件更紧的150 KB限制,所以 `--max-target-bytes` 现在是一个二级防御。 )
    
-   **超时部分结果**: 每堆循环检查 `ctx.signal` (跑者暂停比赛) 在块之间,并传递给 `spawnTool`因此,飞行中扫描被迅速杀死。 中止时,适配器将结果保存在完成的块上并添加一个 `Timeout` 出错(-) `status: "partial"`而不是失去所有的东西。 这就是为什么在ARG MAX之外块块的事物:这是在保留结果的情况下可以停止长扫描的颗粒性.

## 常见问题

### @codacy/tools-opengrep-1 是什么？

Opengrep 适配器—— CLI- mode 多语言 SAST 扫描器

### 如何安装 @codacy/tools-opengrep-1？

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

### @codacy/tools-opengrep-1 支持 TypeScript 吗？

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

### @codacy/tools-opengrep-1 支持 ESM 还是 CommonJS？

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

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

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

### @codacy/tools-opengrep-1 可以商用吗？

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

### @codacy/tools-opengrep-1 的下载量有多少？

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

### @codacy/tools-opengrep-1 还在维护吗？

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