Regal Capabilities 配置指南让 Regal 按目标 OPA 版本精准生效【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址: https://gitcode.com/gh_mirrors/op/opa导读Regal 是 Open Policy Agent 生态中的 Rego 代码检查Lint工具。默认情况下Regal 会基于发布时已知的最新版 OPA 的 capabilities能力清单来检查你的策略代码但这并不总是符合你的实际场景当你的项目仍运行在旧版 OPA 上时Regal 可能会推荐旧版本尚未引入的内置函数而当你的项目已经升级到 OPA 1.0 之后一些面向旧版的检查规则又变得毫无意义。本指南以 Regal 官方 Capabilities 文档 为主体系统讲解如何通过配置capabilities让 Regal 精确感知目标 OPA 引擎与版本、从文件或 URL 导入能力清单、以及用plus/minus增删内置函数从而让每条 lint 规则都只在你适用的版本范围内生效。读完本文你将掌握Regal capabilities 的完整配置语法engine/version/file/url四种来源、plus与minus的增删语义、三种受支持引擎opa/eopa/rq的适用场景以及如何通过跳过规则 报告提示的工作机制避免误报并了解该机制在仓库源码与相关规则文档中的印证。为什么需要配置 CapabilitiesRegal 的默认行为是使用发布 Regal 时已知的最新版 OPA的 capabilities 来执行检查。这意味着超前推荐如果某个内置函数是较新版本才引入的而你的项目因环境约束仍运行在旧版 OPA 上Regal 默认会推荐你使用它导致代码在目标环境不可用。文档给出的典型例子是 strings.count该函数在 OPA v0.67.0 才引入如果项目目标是更早版本推荐使用它就没有意义。滞后误报反方向同样存在。例如 OPA 1.0 之后future.keywords系列导入已不再需要此时仍让 Regal 检查 implicit-future-keywords 相关规则检查import future.keywords.if等隐式关键字导入就与实际情况不符——因为这些关键字在 OPA 1.0 中已成为默认语法的一部分。配置 capabilities 后Regal 会据此决定哪些规则参与检查凡是依赖了当前 capabilities 中不存在或不再适用特性的规则都会被自动跳过而不是产生误报或噪音。这一机制在 use-rego-v1 规则文档 中有直观的印证——当你用 capabilities 指向 OPA v0.55.0尚无rego.v1导入时Regal 的 lint 输出会是这样$ regal lint bundle 131 files linted. No violations found. 1 rule skipped: - use-rego-v1: Missing capability for import rego.v1注意被跳过的规则不会导致命令失败Regal 只是在报告中给出提示提醒你它因缺少相应 capability 而临时禁用。指定目标引擎与版本如果你明确知道项目要运行在某个具体的 OPA 版本上可以在配置文件中加入capabilities段通过from.enginefrom.version指定.regal/config.yaml或.regal.yamlcapabilities: from: engine: opa version: v0.58.0engine目标引擎标识目前官方支持opa此外还支持eopa与rq详见下文支持的引擎一节。version目标版本号需要带上v前缀如v0.58.0必须对应 capabilities 目录 中存在的版本文件。从仓库中可以确认OPA 为几乎每一个历史版本都维护了对应的 capabilities JSON 文件例如 capabilities/v0.58.0.json、capabilities/v0.59.0.json、capabilities/v0.55.0.json 等这些文件被编译期嵌入到二进制中见 capabilities/capabilities.go 中//go:embed *.json的FS变量Regal 正是基于这样的能力文件来判断哪些特性可用。capabilities JSON 里到底有什么以 capabilities/v0.58.0.json 为例一个典型的能力文件包含以下顶层字段字段含义v0.58.0 示例值builtins该版本可用的全部内置函数声明含参数与返回类型195 个内置函数future_keywords需要import future.keywords.*才能使用的关键字[contains, every, if, in]wasm_abi_versions该版本支持的 WASM ABI 版本版本列表features该版本引入的特性标记例如rule_head_ref_string_prefixes特性名数组而仓库根目录的 capabilities.json 则代表了当前最新OPA 的能力集合其中包含 206 个内置函数future_keywords为[and, not, or]features为[keywords_in_refs, rego_v1, template_strings]——对比可见在 OPA 1.0 中if/contains/every/in等关键字已经成为默认语法不再需要import future.keywords反而and/not/or变成了需要显式导入的未来关键字。这正是文档中OPA 1.0 后检查隐式 future keyword 导入没有意义一说的底层原因。配置版本时应注意version值必须与 capabilities 目录中实际存在的版本文件对应否则 Regal 无法定位能力文件。如果你使用的 OPA 版本恰好是某个发布候选版或补丁版请核对仓库 capabilities 目录中的实际文件名。从文件导入 Capabilities除了直接指定引擎版本你也可以把能力清单放到一个 JSON 文件里然后让 Regal 从文件导入。典型场景是团队使用自定义构建的 OPA包含额外内置函数或需要统一管理能力清单capabilities: from: file: build/capabilities.json这里的file路径是相对于你运行regal lint的工作目录解析的。文件内容即为 OPA 风格的 capabilities JSON结构同上一节的builtins/future_keywords/wasm_abi_versions/features等字段。这种方式与engineversion方式二选一即可两种配置互斥。用 plus / minus 增删内置函数你还可以在某个能力集合之上做增量修改minus用于排除让依赖这些内置函数的规则被跳过plus用于新增让 Regal 认识你的自定义内置函数。注意plus/minus操作的是内置函数集合而不是任意特性。capabilities: from: engine: opa version: v0.58.0 minus: builtins: # 排除依赖 http.send 内置函数的规则 - name: http.send plus: builtins: # 让 Regal 认识自定义的 ldap.query 函数 - name: ldap.query type: function decl: args: - type: string result: type: object参数说明minus.builtins一个内置函数名列表只需name字段。例如你的策略被禁止使用网络访问就可以用上面的写法把http.send从能力集合中移除从而跳过依赖它的规则。从 capabilities/v0.58.0.json 中可以确认http.send确实存在于该版本的内置函数列表中因此这种排除是有实际意义的。plus.builtins每个新增函数需要提供完整的type、decl.args、decl.result声明。上面示例声明了一个接收string参数、返回object的自定义函数ldap.query。这样 Regal 就能识别出策略中对ldap.query(...)的调用并据此参与类型与依赖分析而不会被当成未知函数。补充说明自定义内置函数是 OPA 部署层面的能力。在 OPA 的 capabilities 机制中除了内置函数还可以声明网络白名单如允许访问的主机、禁用future关键字等。Regal 的plus/minus当前聚焦在内置函数的增删上如果你需要更完整的自定义能力管理可参考 forbidden-function-call 规则文档 中对 OPA capabilities 机制的介绍——该规则本身是禁用某些函数的另一种更轻量的实现方式文档建议如果已在用 capabilities 机制管理函数白名单就无需再启用此规则。从 URL 加载 Capabilities自 Regal v0.26.0 起Regal 支持通过capabilities.from.url配置键从http或httpsURL 加载能力清单。例如从https://example.org/capabilities.json加载capabilities: from: url: https://example.org/capabilities.json这为集中分发能力清单提供了便利团队可以把统一的能力文件托管在内部服务器或对象存储上所有成员的 Regal 从同一 URL 拉取确保 lint 行为一致。使用 URL 方式时无需也不应同时指定engine/version。支持的引擎Regal 目前为以下引擎提供 capabilities 支持Engine说明opaOpen Policy Agent官方策略引擎也是默认与最常用的目标eopaEOPA——Open Policy Agent 的另一个实现rqRego Queryrq——面向 Rego 的查询工具配置示例以rq为目标capabilities: from: engine: rq version: rq 版本rq支持说明为了让rq脚本与 Regal 兼容rq脚本中必须包含package语句。如果你的项目使用rq请确保每个被检查的 Rego 脚本都声明了package否则 Regal 可能无法正确处理。版本信息提示文档中明确currently onlyopasupported的描述针对的是早期文档版本当前文档的Supported Engines一节已列出opa、eopa、rq三种引擎本文以仓库内文档现状为准。在完整配置中的位置capabilities只是 Regal 配置文件.regal/config.yaml或.regal.yaml中的一个顶层段。一个完整的配置可能同时包含规则级别、项目根目录、忽略文件等设置配置总览文档 给出了整合示例rules: style: todo-comment: level: ignore line-length: max-line-length: 100 level: warning capabilities: from: # 可选让 Regal 针对特定 OPA 版本生效 # 会禁用依赖该版本不支持的内置函数/特性的规则 # # 若不提供Regal 使用发布时已知的最新版 OPA 的能力 engine: opa version: v0.58.0 ignore: files: - file1.rego - *_tmp.rego project: roots: - main几点使用提示配置文件放在.regal/config.yaml或.regal.yamlRegal 会从当前目录向上逐级查找也可以用regal lint --config-file path短选项-c显式指定。若既不配置 capabilities也未在~/.config/regal/config.yaml找到用户级配置Regal 使用内置默认配置即最新版 OPA 能力。建议将配置文件提交到仓库保证团队成员与 CI 环境 lint 行为一致。结合规则文档理解跳过的行为理解 capabilities 如何影响规则最好的方式是看规则文档中的Capabilities小节。两个典型例子use-rego-v1该规则要求使用import rego.v1。当 capabilities 指向 OPA v0.55.0rego.v1尚不存在时规则被自动跳过并输出use-rego-v1: Missing capability for import rego.v1的提示同时该规则在 OPA 1.0 之后默认被禁用除非显式配置目标为更早版本——这两点都与 capabilities 的语义完全吻合。use-strings-count该规则推荐用strings.count替代count(indexof_n(...))。strings.count在 OPA v0.67.0 引入若目标版本更早配置 capabilities 后规则会被跳过。我们可以在仓库的 capabilities 文件中验证strings.count在 capabilities/v0.58.0.json 与 capabilities/v0.55.0.json 中都不存在说明这两个版本确实不支持该函数。use-array-flatten该规则推荐用array.flatten替代嵌套的array.concat而array.flatten在 OPA v1.13.0 才引入其文档Exceptions一节明确指出若目标版本早于 v1.13.0就必须通过 capabilities 告诉 Regal 你的 OPA 版本让不适用的规则被自动排除。这些规则文档共同印证了 capabilities 的核心价值与其手动逐个ignore规则不如一次性声明目标能力集合让依赖缺失特性的规则自动、安静地被跳过同时保留报告中的提示以便追踪。小结与最佳实践场景推荐配置项目固定运行在某 OPA 版本capabilities.from.engine: opafrom.version: vX.Y.Z使用自定义构建的 OPA含自定义内置函数capabilities.from.file: build/capabilities.json必要时配合plus团队集中管理能力清单capabilities.from.url: https://...Regal v0.26.0需要禁用个别内置函数在from基础上加minus.builtins需要注册自定义内置函数在from基础上加plus.builtins实践要点不要过度配置如果项目始终跟随最新 OPA可以不配置 capabilities让 Regal 使用默认最新能力。版本号务必精确version需要与 capabilities 目录中的实际版本文件对应并带上v前缀。升级 OPA 后记得更新配置当你把目标 OPA 升级到新版本时同步更新capabilities.from.version这样之前被跳过的规则如use-strings-count会自动重新启用。跳过不等于失败因缺少 capability 而跳过的规则只会出现在报告的提示中不会让regal lint以非零码退出可以放心在 CI 中使用。通过 capabilitiesRegal 能够在推荐新特性与尊重目标环境之间取得平衡让 lint 结果既贴近最佳实践又不会给出无法落地的建议。【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址: https://gitcode.com/gh_mirrors/op/opa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Regal Capabilities 配置指南：让 Regal 按目标 OPA 版本精准生效
Regal Capabilities 配置指南让 Regal 按目标 OPA 版本精准生效【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址: https://gitcode.com/gh_mirrors/op/opa导读Regal 是 Open Policy Agent 生态中的 Rego 代码检查Lint工具。默认情况下Regal 会基于发布时已知的最新版 OPA 的 capabilities能力清单来检查你的策略代码但这并不总是符合你的实际场景当你的项目仍运行在旧版 OPA 上时Regal 可能会推荐旧版本尚未引入的内置函数而当你的项目已经升级到 OPA 1.0 之后一些面向旧版的检查规则又变得毫无意义。本指南以 Regal 官方 Capabilities 文档 为主体系统讲解如何通过配置capabilities让 Regal 精确感知目标 OPA 引擎与版本、从文件或 URL 导入能力清单、以及用plus/minus增删内置函数从而让每条 lint 规则都只在你适用的版本范围内生效。读完本文你将掌握Regal capabilities 的完整配置语法engine/version/file/url四种来源、plus与minus的增删语义、三种受支持引擎opa/eopa/rq的适用场景以及如何通过跳过规则 报告提示的工作机制避免误报并了解该机制在仓库源码与相关规则文档中的印证。为什么需要配置 CapabilitiesRegal 的默认行为是使用发布 Regal 时已知的最新版 OPA的 capabilities 来执行检查。这意味着超前推荐如果某个内置函数是较新版本才引入的而你的项目因环境约束仍运行在旧版 OPA 上Regal 默认会推荐你使用它导致代码在目标环境不可用。文档给出的典型例子是 strings.count该函数在 OPA v0.67.0 才引入如果项目目标是更早版本推荐使用它就没有意义。滞后误报反方向同样存在。例如 OPA 1.0 之后future.keywords系列导入已不再需要此时仍让 Regal 检查 implicit-future-keywords 相关规则检查import future.keywords.if等隐式关键字导入就与实际情况不符——因为这些关键字在 OPA 1.0 中已成为默认语法的一部分。配置 capabilities 后Regal 会据此决定哪些规则参与检查凡是依赖了当前 capabilities 中不存在或不再适用特性的规则都会被自动跳过而不是产生误报或噪音。这一机制在 use-rego-v1 规则文档 中有直观的印证——当你用 capabilities 指向 OPA v0.55.0尚无rego.v1导入时Regal 的 lint 输出会是这样$ regal lint bundle 131 files linted. No violations found. 1 rule skipped: - use-rego-v1: Missing capability for import rego.v1注意被跳过的规则不会导致命令失败Regal 只是在报告中给出提示提醒你它因缺少相应 capability 而临时禁用。指定目标引擎与版本如果你明确知道项目要运行在某个具体的 OPA 版本上可以在配置文件中加入capabilities段通过from.enginefrom.version指定.regal/config.yaml或.regal.yamlcapabilities: from: engine: opa version: v0.58.0engine目标引擎标识目前官方支持opa此外还支持eopa与rq详见下文支持的引擎一节。version目标版本号需要带上v前缀如v0.58.0必须对应 capabilities 目录 中存在的版本文件。从仓库中可以确认OPA 为几乎每一个历史版本都维护了对应的 capabilities JSON 文件例如 capabilities/v0.58.0.json、capabilities/v0.59.0.json、capabilities/v0.55.0.json 等这些文件被编译期嵌入到二进制中见 capabilities/capabilities.go 中//go:embed *.json的FS变量Regal 正是基于这样的能力文件来判断哪些特性可用。capabilities JSON 里到底有什么以 capabilities/v0.58.0.json 为例一个典型的能力文件包含以下顶层字段字段含义v0.58.0 示例值builtins该版本可用的全部内置函数声明含参数与返回类型195 个内置函数future_keywords需要import future.keywords.*才能使用的关键字[contains, every, if, in]wasm_abi_versions该版本支持的 WASM ABI 版本版本列表features该版本引入的特性标记例如rule_head_ref_string_prefixes特性名数组而仓库根目录的 capabilities.json 则代表了当前最新OPA 的能力集合其中包含 206 个内置函数future_keywords为[and, not, or]features为[keywords_in_refs, rego_v1, template_strings]——对比可见在 OPA 1.0 中if/contains/every/in等关键字已经成为默认语法不再需要import future.keywords反而and/not/or变成了需要显式导入的未来关键字。这正是文档中OPA 1.0 后检查隐式 future keyword 导入没有意义一说的底层原因。配置版本时应注意version值必须与 capabilities 目录中实际存在的版本文件对应否则 Regal 无法定位能力文件。如果你使用的 OPA 版本恰好是某个发布候选版或补丁版请核对仓库 capabilities 目录中的实际文件名。从文件导入 Capabilities除了直接指定引擎版本你也可以把能力清单放到一个 JSON 文件里然后让 Regal 从文件导入。典型场景是团队使用自定义构建的 OPA包含额外内置函数或需要统一管理能力清单capabilities: from: file: build/capabilities.json这里的file路径是相对于你运行regal lint的工作目录解析的。文件内容即为 OPA 风格的 capabilities JSON结构同上一节的builtins/future_keywords/wasm_abi_versions/features等字段。这种方式与engineversion方式二选一即可两种配置互斥。用 plus / minus 增删内置函数你还可以在某个能力集合之上做增量修改minus用于排除让依赖这些内置函数的规则被跳过plus用于新增让 Regal 认识你的自定义内置函数。注意plus/minus操作的是内置函数集合而不是任意特性。capabilities: from: engine: opa version: v0.58.0 minus: builtins: # 排除依赖 http.send 内置函数的规则 - name: http.send plus: builtins: # 让 Regal 认识自定义的 ldap.query 函数 - name: ldap.query type: function decl: args: - type: string result: type: object参数说明minus.builtins一个内置函数名列表只需name字段。例如你的策略被禁止使用网络访问就可以用上面的写法把http.send从能力集合中移除从而跳过依赖它的规则。从 capabilities/v0.58.0.json 中可以确认http.send确实存在于该版本的内置函数列表中因此这种排除是有实际意义的。plus.builtins每个新增函数需要提供完整的type、decl.args、decl.result声明。上面示例声明了一个接收string参数、返回object的自定义函数ldap.query。这样 Regal 就能识别出策略中对ldap.query(...)的调用并据此参与类型与依赖分析而不会被当成未知函数。补充说明自定义内置函数是 OPA 部署层面的能力。在 OPA 的 capabilities 机制中除了内置函数还可以声明网络白名单如允许访问的主机、禁用future关键字等。Regal 的plus/minus当前聚焦在内置函数的增删上如果你需要更完整的自定义能力管理可参考 forbidden-function-call 规则文档 中对 OPA capabilities 机制的介绍——该规则本身是禁用某些函数的另一种更轻量的实现方式文档建议如果已在用 capabilities 机制管理函数白名单就无需再启用此规则。从 URL 加载 Capabilities自 Regal v0.26.0 起Regal 支持通过capabilities.from.url配置键从http或httpsURL 加载能力清单。例如从https://example.org/capabilities.json加载capabilities: from: url: https://example.org/capabilities.json这为集中分发能力清单提供了便利团队可以把统一的能力文件托管在内部服务器或对象存储上所有成员的 Regal 从同一 URL 拉取确保 lint 行为一致。使用 URL 方式时无需也不应同时指定engine/version。支持的引擎Regal 目前为以下引擎提供 capabilities 支持Engine说明opaOpen Policy Agent官方策略引擎也是默认与最常用的目标eopaEOPA——Open Policy Agent 的另一个实现rqRego Queryrq——面向 Rego 的查询工具配置示例以rq为目标capabilities: from: engine: rq version: rq 版本rq支持说明为了让rq脚本与 Regal 兼容rq脚本中必须包含package语句。如果你的项目使用rq请确保每个被检查的 Rego 脚本都声明了package否则 Regal 可能无法正确处理。版本信息提示文档中明确currently onlyopasupported的描述针对的是早期文档版本当前文档的Supported Engines一节已列出opa、eopa、rq三种引擎本文以仓库内文档现状为准。在完整配置中的位置capabilities只是 Regal 配置文件.regal/config.yaml或.regal.yaml中的一个顶层段。一个完整的配置可能同时包含规则级别、项目根目录、忽略文件等设置配置总览文档 给出了整合示例rules: style: todo-comment: level: ignore line-length: max-line-length: 100 level: warning capabilities: from: # 可选让 Regal 针对特定 OPA 版本生效 # 会禁用依赖该版本不支持的内置函数/特性的规则 # # 若不提供Regal 使用发布时已知的最新版 OPA 的能力 engine: opa version: v0.58.0 ignore: files: - file1.rego - *_tmp.rego project: roots: - main几点使用提示配置文件放在.regal/config.yaml或.regal.yamlRegal 会从当前目录向上逐级查找也可以用regal lint --config-file path短选项-c显式指定。若既不配置 capabilities也未在~/.config/regal/config.yaml找到用户级配置Regal 使用内置默认配置即最新版 OPA 能力。建议将配置文件提交到仓库保证团队成员与 CI 环境 lint 行为一致。结合规则文档理解跳过的行为理解 capabilities 如何影响规则最好的方式是看规则文档中的Capabilities小节。两个典型例子use-rego-v1该规则要求使用import rego.v1。当 capabilities 指向 OPA v0.55.0rego.v1尚不存在时规则被自动跳过并输出use-rego-v1: Missing capability for import rego.v1的提示同时该规则在 OPA 1.0 之后默认被禁用除非显式配置目标为更早版本——这两点都与 capabilities 的语义完全吻合。use-strings-count该规则推荐用strings.count替代count(indexof_n(...))。strings.count在 OPA v0.67.0 引入若目标版本更早配置 capabilities 后规则会被跳过。我们可以在仓库的 capabilities 文件中验证strings.count在 capabilities/v0.58.0.json 与 capabilities/v0.55.0.json 中都不存在说明这两个版本确实不支持该函数。use-array-flatten该规则推荐用array.flatten替代嵌套的array.concat而array.flatten在 OPA v1.13.0 才引入其文档Exceptions一节明确指出若目标版本早于 v1.13.0就必须通过 capabilities 告诉 Regal 你的 OPA 版本让不适用的规则被自动排除。这些规则文档共同印证了 capabilities 的核心价值与其手动逐个ignore规则不如一次性声明目标能力集合让依赖缺失特性的规则自动、安静地被跳过同时保留报告中的提示以便追踪。小结与最佳实践场景推荐配置项目固定运行在某 OPA 版本capabilities.from.engine: opafrom.version: vX.Y.Z使用自定义构建的 OPA含自定义内置函数capabilities.from.file: build/capabilities.json必要时配合plus团队集中管理能力清单capabilities.from.url: https://...Regal v0.26.0需要禁用个别内置函数在from基础上加minus.builtins需要注册自定义内置函数在from基础上加plus.builtins实践要点不要过度配置如果项目始终跟随最新 OPA可以不配置 capabilities让 Regal 使用默认最新能力。版本号务必精确version需要与 capabilities 目录中的实际版本文件对应并带上v前缀。升级 OPA 后记得更新配置当你把目标 OPA 升级到新版本时同步更新capabilities.from.version这样之前被跳过的规则如use-strings-count会自动重新启用。跳过不等于失败因缺少 capability 而跳过的规则只会出现在报告的提示中不会让regal lint以非零码退出可以放心在 CI 中使用。通过 capabilitiesRegal 能够在推荐新特性与尊重目标环境之间取得平衡让 lint 结果既贴近最佳实践又不会给出无法落地的建议。【免费下载链接】opaOpen Policy Agent (OPA) is an open source, general-purpose policy engine.项目地址: https://gitcode.com/gh_mirrors/op/opa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考