greprules/greprules

# greprules [](https://github.com/greprules/greprules/releases) [](https://github.com/greprules/greprules/actions/workflows/ci.yml) [](https://github.com/greprules/greprules/blob/main/LICENSE) [](https://goreportcard.com/report/github.com/greprules/greprules) Agent 插件和 CLI，用于从 greprules.io 获取 SAST rule pack，并使用 OpenGrep 扫描本地代码更改。 greprules 优先为本地编码 agent 设计。Claude Code、Codex 和 Hermes 插件为 agent 提供了首次运行设置、配置 OpenGrep、根据代码上下文选择 rule pack、获取这些 pack 以及扫描本地代码更改的命令或技能。Go CLI 是这些命令背后的确定性本地 runtime。 greprules 在 greprules GitHub 组织中维护，并由 Provally 提供支持。Provally 运营着默认配置使用的托管型 greprules.io registry 和 API。正常扫描会从 greprules.io 获取 rule pack，在本地运行 OpenGrep，并将独立的项目 lock 保存在用户状态中。Agent 插件扫描可能还会在本地 `.greprules/` 路径下写入特定于 provider 的结果。 ## 快速开始 ### Claude Code ``` /plugin marketplace add greprules/greprules /plugin install greprules@greprules /reload-plugins ``` ``` /greprules:setup /greprules:configure /greprules:scan-edited ``` ### Codex ``` codex plugin marketplace add greprules/greprules --sparse .agents/plugins --sparse plugins/codex ``` Codex 应用：**Plugins** -> `greprules` -> 安装/启用。 Codex CLI TUI： ``` /plugins ``` ``` $greprules-setup $greprules-configure $greprules-scan-edited ``` ### Hermes ``` hermes plugins install greprules/greprules --enable ``` ``` /greprules setup /greprules configure /greprules scan-edited ``` 安装插件后运行一次 `setup`。以后可以使用 `configure` 检查状态或更改设置。 ## 功能说明 - 允许 agent 根据目标代码上下文从 greprules.io 选择可重用的 SAST rule pack。 - 通过 CLI 可重现地获取所选的 pack。 - 配置 OpenGrep 以进行本地扫描。 - 跟踪本地编码 agent 编辑的文件。 - 在 agent 完成工作前扫描更改的文件或显式指定的目标。 - 写入 agent 可读的结果，以便 agent 审查发现的问题并建议修复。 - 保持源代码在本地；插件仅获取 rule 并在您的机器上运行 OpenGrep。 ## 插件文档 - [Claude Code](plugins/claude-code/README.md) - [Codex](plugins/codex/README.md) - [Hermes](plugins/hermes/README.md) ## OpenGrep Runtime OpenGrep 执行实际的扫描。greprules 保持 runtime 选择的显式性，从而确保扫描可重现且易于调试。 | 模式 | 适用场景 | | --- | --- | | `managed` | 您希望 greprules 安装并使用托管的 OpenGrep 二进制文件。这是默认选项。 | | `system` | 您的 `PATH` 中已有 `opengrep` 并希望直接使用它。 | | `path` | 您希望 greprules 指向特定的 OpenGrep 可执行文件。 | 对于独立的 CLI 使用，默认的托管 runtime 会通过 `greprules scan` 自动安装，或通过 `greprules setup-opengrep` 显式安装。Agent 插件通过其 `/greprules configure` 或 `$greprules-configure` 工作流暴露 runtime 配置。 仅针对 agent/插件自动化，底层的设置命令为： ``` greprules agent-config set opengrep.mode system --global greprules agent-config set opengrep.mode managed --global greprules agent-config set opengrep.mode path --global greprules agent-config set opengrep.path /absolute/path/to/opengrep --global ``` 默认情况下，greprules 仅扫描已获取的 greprules.io pack。如果要同时包含 OpenGrep 默认自动选择的 rule： ``` greprules agent-config set opengrep.includeDefaultRules true --global ``` Hook 行为是按每个 agent 插件配置的，而不是通过共享的 CLI config 配置： ``` ~/.claude/plugins/greprules/settings.json ~/.codex/plugins/greprules/settings.json ~/.hermes/plugins/greprules/settings.json ``` 每个文件使用相同的键： ``` { "autoScan": false, "trackEditedFiles": true, "autoScanMinIntervalSeconds": 45, "autoScanMaxChangedFiles": 100 } ``` ## 结果与本地文件 重要文件包括： ``` user state: projects//lock.json user cache: packs///... .greprules/config.yaml .greprules/plugin-data//sessions//out/agent-result.json ``` 独立的 CLI 扫描遵循 OpenGrep 的输出行为：stdout 和文件由您传递的 OpenGrep 参数控制，例如 `--json`、`--sarif` 和 `--output`。独立的项目 lock 保存在以规范项目根目录为键的用户状态中，而 rule pack 制品保存在用户缓存中并跨项目重用。Agent 扫描使用隐藏的 `agent-scan` 命令，并将结构化结果写入 `.greprules/out/agent-result.json` 或特定于会话的插件输出路径下。 生成的本地路径在 git 仓库中会被自动忽略： ``` .greprules/out/ .greprules/plugin-data/ .greprules/config.local.json ``` 共享文件（例如 `.greprules/config.yaml`）不会被自动忽略。 ## 独立 CLI 当您希望使用 greprules.io rule pack 并保持正常的 OpenGrep 扫描行为时，CLI 非常有用。 ``` greprules scan . ``` 首次运行时，`scan` 会检测目标语言/framework 上下文，选择匹配的 greprules.io rule pack，在用户状态中获取并锁定它们，在需要时安装托管的 OpenGrep，然后以所选的 rule pack 作为 `--config` 参数注入来运行 `opengrep scan`。现有的项目 lock 会被重用，因此锁定的 rule pack 在同一台机器上保持可重现性。支持的 OpenGrep 扫描选项可以按正常的 OpenGrep 风格混合使用。请将高级 OpenGrep flag 放在 `--` 之后，这样 greprules 就不会将它们的值误认为是 pack 选择目标。 更多命令： ``` greprules scan --changed greprules fetch python-security greprules setup-opengrep greprules scan path/to/file greprules scan . --json greprules scan . --sarif --output result.sarif greprules scan . --severity ERROR greprules scan --json-output result.json src greprules scan . --no-prepare greprules scan . --verbose greprules scan src -- --some-future-opengrep-flag value greprules cleanup --plugin-cache --dry-run ``` ## 高级 Agent 配置参考 独立的 CLI 用户通常不需要编辑 greprules config。`scan` 会准备托管 runtime、选择 rule pack、获取缺失的 pack，然后将输出行为委托给 OpenGrep。本参考仅用于 agent/插件自动化或本地开发。 生产环境 registry 为： ``` https://api.greprules.io ``` Agent 配置按以下顺序合并： ``` CLI flags environment variables .greprules/config.local.json .greprules/config.yaml ~/.config/greprules/config.json defaults ``` 用户/全局 config 为 JSON 格式： ``` { "schemaVersion": "greprules.user.v1", "registry": "https://api.greprules.io", "opengrep": { "mode": "system", "path": "/Users/l0ch/.local/bin/opengrep", "version": "latest", "includeDefaultRules": false } } ``` 仓库共享 config 为 YAML 格式： ``` schemaVersion: greprules.config.v1 mode: auto packs: - go-security opengrep: mode: managed ``` 为了安全起见，来自共享 `.greprules/config.yaml` 的 `opengrep.path` 会被忽略。请将可执行文件路径放在用户/全局 config、仓库本地 config、环境变量或 CLI flag 中。 仅限本地 worker 开发使用： ``` GREPRULES_REGISTRY=http://127.0.0.1:8790 greprules agent-status --format json ``` ## 插件 Runtime Agent 插件提供 `bin/greprules` 包装器，而不是原生的 Go 二进制文件本身。Skills 和 hook 应直接调用该内置的包装器；用户的 shell `PATH` 中缺少 `greprules` 并不意味着插件设置失败。 包装器按以下顺序解析真实的 CLI： ``` GREPRULES_CLI_PATH system PATH, excluding the plugin wrapper itself GitHub Release bootstrap into /greprules/plugins//greprules//greprules ``` 有关特定于插件的详细信息，请参阅 [`plugins/claude-code/README.md`](plugins/claude-code/README.md)、[`plugins/codex/README.md`](plugins/codex/README.md) 和 [`plugins/hermes/README.md`](plugins/hermes/README.md)。 ## 开发 ``` make test vet build claude plugin validate --strict /path/to/greprules claude plugin validate --strict /path/to/greprules/plugins/claude-code CODEX_HOME="$(mktemp -d)" codex plugin marketplace add /path/to/greprules ``` 要在发布前测试本地 CLI 构建： ``` go build -o greprules ./cmd/greprules export GREPRULES_CLI_PATH="$PWD/greprules" ``` 清理是显式的： ``` greprules cleanup --config --plugin-cache --dry-run greprules cleanup --config --plugin-cache greprules cleanup --purge greprules cleanup --repo ``` ## 维护者 greprules 由 greprules GitHub 组织中的贡献者在 [Provally](https://provally.io/) 的支持下进行维护。

标签：AI Agent插件, EVTX分析, Go, Ruby工具, SAST, 代码安全审计, 日志审计, 盲注攻击, 错误基检测, 静态代码分析