Grafana 插件验证器
此工具有助于加快出版插件的进程 Grafana.com (英语)它运行一系列 分析器 确保插件遵循最佳做法、检查安全和结构问题以及出版方面的具体要求。 对这些要求的概述可参见本文: https://grafana.com/docs/grafana/latest/developers/plugins/出版和签署标准/。 。 。 .
它需要指定远程或本地 ZIP 插件存档的路径, 例如 :
- 远程数字 :
https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip - 当地数字 :
file://Users/me/Downloads/grafana-clock-panel-2.1.2.zip
你们可以 额外 为工程提供源代码链接 -sourceCodeUri 以启用诸如 " 脆弱性扫描 " 等额外分析器.
安装和使用
确保您的 Go 版本符合 go.mod 避免相容性问题的文件
多克( 建议)
使用 Docker 图像来运行工具很容易,因为它包含所有 安全扫描工具 全套分析器需要 - 所以你不需要在你的系统中安装这些额外的工具.
docker run --pull=always grafana/plugin-validator-cli [options] [http://yourdomain/plugin_archive.zip]
例1(基础)
docker run --pull=always grafana/plugin-validator-cli https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip
例2(具体说明源代码位置)
docker run --pull=always grafana/plugin-validator-cli -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip
使用带有 Docker 的本地归档文件
要使用本地归档来运行工具, 您需要挂载它作为嵌入器的分量 。 举个例子:
docker run --pull=always -v /path/to/plugin_archive.zip:/archive.zip grafana/plugin-validator-cli /archive.zip
[注] 如果使用相对路径, 您的路径必须从
./
使用本地归档文件和本地源代码
docker run --pull=always -v /path/to/plugin_archive.zip:/archive.zip -v /path/to/source_code:/source_code grafana/plugin-validator-cli -sourceCodeUri file:///source_code /archive.zip
[注] 如果使用相对路径, 您的路径必须从
./
国家PX
npx -y @grafana/plugin-validator@latest -sourceCodeUri [options] [path/to/plugin_archive.zip]
当地
首先, 您必须编译并安装 :
git clone [email protected]:grafana/plugin-validator.git
cd plugin-validator/pkg/cmd/plugincheck2
go install
然后您可以运行此工具 :
plugincheck2 -sourceCodeUri [source_code_location/] [plugin_archive.zip]
MCP 服务器( 用于 AI 助手)
插件验证器可以用作MCP(模式上下文协议)服务器,允许克洛德,克莱恩等AI助手,以及其他MCP相容工具验证Grafana插件.
见 MCP 服务器读取器 用于配置指令.
生成本地文件进行校验
你必须创建一个 .zip 包含 dist/ 目录但命名为您的插件 ID :
PLUGIN_ID=$(grep '"id"' < src/plugin.json | sed -E 's/.*"id" *: *"(.*)".*/\1/')
cp -r dist "${PLUGIN_ID}"
zip -qr "${PLUGIN_ID}.zip" "${PLUGIN_ID}"
npx @grafana/plugin-validator@latest -sourceCodeUri file://. "${PLUGIN_ID}.zip"
您可以选择删除生成的文件 :
rm -r "${PLUGIN_ID}" "${PLUGIN_ID}.zip"
选项
其他选项可以传递给工具 :
❯ plugincheck2 -help
Usage plugincheck2:
-config string (optional)
Path to configuration file
-sourceCodeUri string (optional)
URI to the source code of the plugin. If set, the source code will be downloaded and analyzed. This can be a ZIP file URL, a URL to git repository or a local file (starting with `file://`)
-strict (optional)
If set, plugincheck returns non-zero exit code for warnings
-checksum string (optional)
If set, the checksum of the plugin archive will be checked against this value. MD5 and SHA256 are supported.
-analyzer string (optional)
If set, only an specific analyzer and it's dependencies will run.
-severity string (optional)
If used, it will set the severity of the analyzer (it has the highest priority).
使用配置文件
您可以用 : -config 选项。 这里可以使用几个配置示例: https://github.com/grafana/plugin-validator/tree/main/config 页面存档备份,存于互联网档案馆。 。 。 .
通过配置使分析器能够和丧失功能
如果您想要禁用特定检查( analyzer), 您可以在您的 配置文件,添加一个 analyzers 区域,并指定哪个分析或分析规则以启用和禁用.
例如,禁用 version 分析器 :
global:
enabled: true
jsonOutput: false
reportAll: false
analyzers:
version:
enabled: false
您也可以禁用特定规则或改变其严重程度 :
global:
enabled: true
jsonOutput: false
reportAll: false
analyzers:
readme:
rules:
missing-readme:
enabled: true
severity: warning
临界值可以是: error, (中文(简体) ), warning,或 ok。 。 。 .
有些规则默认被禁用, 仅在分析器或规则配置设置时运行 enabled: true。 。 。 .
注意:Grafana Labs对插件提交执行自己的配置,而您自己的配置文件无法改变这些规则.
从分析器或规则中排除插件
也可以将特定插件排除在分析器或分析器内部的特定规则之外. 当特定检查不适用于您的插件时,此功能是有用的 .
要禁用插件的全部分析器,请添加 exceptions 列表中包含插件 ID.
analyzers:
some-analyzer:
enabled: true
# This entire analyzer will be skipped for 'my-plugin-id'
exceptions:
- my-plugin-id
要禁用插件的单一规则,请添加 exceptions 列表到规则的配置.
analyzers:
some-analyzer:
rules:
some-rule:
enabled: true
# This rule will be skipped for 'my-plugin-id'
exceptions:
- my-plugin-id
源代码
您可以用 : -sourceCodeUri 选项。 这样做可以增加 分析器 以进行更完整的扫描.
支持远程 Git 服务
以下内容: 公开 支持 Git 服务 :
- GitHub 图像
- 吉特拉布语Name
- 键盘
目前不支持私人寄存器 .
确保包括 ref 对应源代码的(分支或标记).
例如: 您正在验证版本 v2.1.2 你的项目在GitHub 确保您创建相应的标签或分支并使用 URL https://github.com/grafana/clock-panel/tree/v2.1.2。 。 。 .
调试模式
您可以在调试模式下运行验证器,以获取更多关于运行中的检查和可能出错的信息.
嵌入器 :
docker run --pull=always -e DEBUG=1 grafana/plugin-validator-cli -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip
NPX : (英语)
DEBUG=1 npx -y @grafana/plugin-validator@latest -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip
当地:
DEBUG=1 plugincheck2 -sourceCodeUri https://github.com/grafana/clock-panel/tree/v2.1.2 https://github.com/grafana/clock-panel/releases/download/v2.1.2/grafana-clock-panel-2.1.2.zip
LLM 提供者配置
这个 llmreview 财务报告和审定财务报表 codediff 分析者使用LLM来审查插件源代码. 支持三个提供者: 安东尼, (中文(简体) ), 开放AI,以及 谷歌( 格米尼 )。 。 。 .
设置以下环境变量之一,以允许基于LLM的分析. 使用的是第一个发现的密钥(顺序如下):
| 环境变量 | 提供者 | 默认模式 |
|---|---|---|
ANTHROPIC_API_KEY | 安东尼 | claude-opus-4-6 |
OPENAI_API_KEY | 开放AI | gpt-5.4 |
GEMINI_API_KEY | 谷歌 | gemini-3.1-flash-lite-preview |
示例
ANTHROPIC_API_KEY=sk-ant-... plugincheck2 -sourceCodeUri https://github.com/org/repo/tree/v1.0.0 plugin.zip
您可以跳过单个 LLM 分析器 SKIP_LLM_REVIEW=1 或者说 SKIP_LLM_CODEDIFF=1。 。 。 .
安保工具
此校验器使用下列开源安全工具:
如果您在本地运行或通过 NPX 运行验证器, 您可以在您的系统中安装这些工具, 让它们成为您验证检查的一部分 .
分析器
该工具运行了一系列分析器,以确保提交的插件遵循了最佳做法,并加快批准出版插件的过程,详情见下表. 这个 分析器 栏中包含更改给定检查行为所需的名称 配置文件编辑 依赖关系 栏中指定分析器是否要求提供插件的源代码 sourceCodeUri 或任何额外的 安全扫描工具 将在场.
| 分析器 | 说明 | 依赖关系 |
|---|---|---|
归档名称 / archivename | 档案名称应当正确格式化. | 无 |
存档结构 / archive | 确保zip文件的内容具有预期布局. | 无 |
后端二进制 / backendbinary | 验证二进制文件的存在与插件.json声明是否一致,用于后端或提醒. | 无 |
后端调试 / backenddebug | 检查后端插件的独立调试文件是否不存在 . | 无 |
二进制权限 / binarypermissions | 对于带有二进制的数据源和应用程序,这保证了插件在被提取到一个系统中时能够运行. | 无 |
断开链接 / brokenlinks | 检测到是否有URL无法解析到有效位置. | 无 |
构建标记 / buildtags | 检查 对不允许的构建标记, 选择后端可执行文件 . | 无 |
构建工具 / buildtools | 检查插件是否使用Grafana的标准创建-插件构建工具. | 无 |
变化日志( 存在) / changelog | 确保 CHANGELOG.md 文件存在于zip文件中. | 无 |
校验和 / checksum | 验证所通过校验和( 作为验证器 arg) 是从归档文件中计算出来的 . | checksum |
循环依赖/ circulardependencies | 确保插件之间没有任何循环依赖关系( Q)plugin.json, (中文(简体) ), dependencies.plugins 页:1. | 无 |
代码 Diff / codediff | Anthropic(ANTHROPIC API KEY),OpenAI(OPENAI API KEY),或Google(GEMINI API KEY)之一的API密钥 | |
守则规则/ code-rules | 检查禁止访问环境变量,文件系统或使用syscall模块. | 链条, (中文(简体) ), sourceCodeUri |
开发者 Jargon / jargon | 一般来说,不鼓励在文档中使用密码术语. | 无 |
可发现性/ discoverability | 关于目录中用于插件索引的缺失关键词和描述的警告. | 无 |
显示/ go-manifest | 验证建筑清单. | 无 |
安全检查器 / go-sec | 通过扫描"去AST"来检查安全问题的源代码. | 目标, (中文(简体) ), sourceCodeUri |
脆弱性检查器/ govulncheck | 扫描 为已知弱点去后端源和插件后端二进制(govulncheck). | govuln 检查, (中文(简体) ), sourceCodeUri 用于源扫描 |
联合来文来源图/ jsMap | 需要检查 module.js.map 存档中的文件. | sourceCodeUri |
格拉法纳工具包的使用/ legacybuilder | 检测使用支持时间不长的Grafana工具包. | 无 |
遗产平台/ legacyplatform | 检测到使用角质被腐烂. | 无 |
许可证类型 / license | 请检查date=中的日期值 (帮助) BSD, MIT, Apache 2.0, LGPL3, GPL3, AGPL3. | 无 |
LLM 语言 审查/ llmreview | 通过 LLM 运行代码以检查安全问题或不允许的使用 . | Anthropic(ANTHROPIC API KEY),OpenAI(OPENAI API KEY),或Google(GEMINI API KEY)之一的API密钥 |
标记 / logos | 检测插件是否包含要显示在插件目录中的大小标识 . | 无 |
说明(签署)/ manifest | 当一个插件签名时, zip 文件将包含一个签名 MANIFEST.txt 文档. | 无 |
元数据 / metadata | 检查一下 plugin.json 存在且有效. | 无 |
元数据Grafana依赖性/ grafanadependency | 请检查date=中的日期值 (帮助) Grafana Dependency in plugin.json 无效. | 无 |
元数据路径 / metadatapaths | 确保所有路径都有效,且引用的图像存在. | 无 |
元数据有效性 / metadatavalid | 确保元数据有效并匹配插件计划 . | 无 |
模块.js(性别)/ modulejs | 所有插件都需要一个 module.js 将被装入. | 无 |
巢穴包括元数据 / includesnested | 验证嵌入插件有正确的元数据 . | 无 |
嵌入元数据 / nestedmetadata | 递归检查所有 plugin.json 已存在且有效. | 无 |
无跟踪脚本 / trackingscripts | 检测到是否有已知的跟踪脚本,这些脚本是不允许的. | 无 |
组织(存在)/ org | 验证插件 ID 中指定的 org 存在 . | 无 |
软件包.json / packagejson | 确保软件包.json存在,版本与插件.json匹配 | 无 |
插件文档 / plugindocs | 运行 @grafana/plugin-docs-cli validate --dist 命令以检查归档中包含的多页文档(仅用于设置的插件) docsPath 内 plugin.json) (中文(简体) ). | node, (中文(简体) ), npx |
插件 名称格式 / pluginname | 验证所用的插件 ID 符合我们的命名惯例 . | 无 |
证明证明 / provenance | 如果插件是用管道支持出处的证明(例如:Github Actions)来建造,则验证出处证明. | 无 |
发表/ published-plugin | 检测 Grafana 插件目录中是否存在此插件的任何版本 . | 无 |
反应 19 兼容性 / reactcompat | 检测使用 React API 在 React 19 中被移除或贬值 . | npx 数据 |
读取(性别)/ readme | 确保 README.md 文件存在于zip文件中. | 无 |
需要链接 / requiredlinks | 检查一下 plugin.json 拥有有效的 https URL 的许可证、 隐私政策和支持链接。 默认禁用 . | 无 |
限制性依赖性/ restrictivedep | 指定与此版本插件配合的 Grafana 版本的有效范围. | 无 |
安全链接 / safelinks | 检查链接从 plugin.json 这是安全的. | 无 |
截图 / screenshots | 屏幕截图在 plugin.json 用于 Grafana 插件目录. | 无 |
SDK 使用量 / sdkusage | 确保 grafana-plugin-sdk-go 是最新的. | 无 |
签署/ signature | 确保插件有有效的签名 . | 无 |
源代码 / sourcecode | 在zip文件与源代码之间进行比较,以确保所放出的内容与与之相匹配的回波相匹配. | sourceCodeUri |
类型后缀(平面/app/数据源) / typesuffix | 确保插件具有指定的有效类型. | 无 |
独一无二的读取ME.md / templatereadme | 确保插件不会从中重新使用模板 create-plugin 工具. | 无 |
不安全的 SVG / unsafesvg | 检查是否有基于元素和属性的白名单的 svg 文件是安全的 . | 无 |
版本数 / version | 确保提交的版本比当前已发布的插件更新 。 如果这是新/ 未发布的插件, 则跳过 . | 无 |
病毒扫描/ virusscan | 在插件归档和源代码上运行病毒扫描 clamscan (单位:千美元)clamav) (中文(简体) ). | 蛤丝 |
扫描仪/ osv-scanner | 检测 Go 模块和纱锁文件中的关键弱点 . | osv 扫描器, (中文(简体) ), sourceCodeUri |
产出
默认情况下,该工具输出产生如下所示的纯文本.
默认 :
warning: README.md: possible broken link: https://www.d3js.org (404 Not Found)
detail: README.md might contain broken links. Check that all links are valid and publicly accessible.
warning: README.md contains developer jargon: (yarn)
detail: Move any developer and contributor documentation to a separate file and link to it from the README.md. For example, CONTRIBUTING.md, DEVELOPMENT.md, etc.
error: osv-scanner detected a critical severity issue
detail: SEVERITY: CRITICAL in package immer, vulnerable to CVE-2021-23436
error: osv-scanner detected a critical severity issue
detail: SEVERITY: CRITICAL in package json-schema, vulnerable to CVE-2021-3918
error: Plugin version 0.0.9 is invalid.
detail: The submitted plugin version 0.0.9 is not greater than the latest published version 0.0.9 on grafana.com.
这可以通过通过一个配置文件(包括:
global:
jsonOutput: true
输出结果类似于:
{
"id": "briangann-gauge-panel",
"version": "0.0.9",
"plugin-validator": {
"brokenlinks": [
{
"Severity": "warning",
"Title": "README.md: possible broken link: https://www.d3js.org (404 Not Found)",
"Detail": "README.md might contain broken links. Check that all links are valid and publicly accessible.",
"Name": "broken-link"
}
],
"jargon": [
{
"Severity": "warning",
"Title": "README.md contains developer jargon: (yarn)",
"Detail": "Move any developer and contributor documentation to a separate file and link to it from the README.md. For example, CONTRIBUTING.md, DEVELOPMENT.md, etc.",
"Name": "developer-jargon"
}
],
"osv-scanner": [
{
"Severity": "error",
"Title": "osv-scanner detected a critical severity issue",
"Detail": "SEVERITY: CRITICAL in package immer, vulnerable to CVE-2021-23436",
"Name": "osv-scanner-critical-severity-vulnerabilities-detected"
},
{
"Severity": "error",
"Title": "osv-scanner detected a critical severity issue",
"Detail": "SEVERITY: CRITICAL in package json-schema, vulnerable to CVE-2021-3918",
"Name": "osv-scanner-critical-severity-vulnerabilities-detected"
},
],
"version": [
{
"Severity": "error",
"Title": "Plugin version 0.0.9 is invalid.",
"Detail": "The submitted plugin version 0.0.9 is not greater than the latest published version 0.0.9 on grafana.com.",
"Name": "wrong-plugin-version"
}
]
}
}
严重性
默认情况下,该工具将显示分析器产生的任何警告或出错级别结果. 要看到包括成功在内的所有结果,您可以通过一个配置文件,其中包括:
global:
reportAll: true
获取帮助
- : 打开 书:检查我们的插件 文档。 。 。 .
- :手摇:加入 社区论坛。 。 。 .
- :speech balloon:在格拉法纳斯克和我们聊天 #插件频道。 。 。 .
- 时间轴: 提交一个问题 用于任何错误或特性请求.
许可证
Grafana 插件校验器在 Apache 2.0 许可证。 。 。 .