13个版本

新版本 0.2.3	2024年8月16日
0.2.2	2024年7月28日
0.2.1	2024年6月19日
0.1.2	2024年3月22日

#253 在编码分类中

9,737 每月下载量
在 3 个crates中使用（通过 zino-core）

自定义许可证

1MB
15K SLoC

Regorus

Regorus 是

Rego-Rus(t) - 使用Rust编写的快速、轻量级的Rego 解释器。
严格 - 严格遵循明确定义的Rego语义。

Regorus还

跨平台 - 使用平台无关的Rust编写。
与no_std兼容 - Regorus也可以在no_std环境中使用。大部分内置函数都受支持。
最新版 - 我们努力使Regorus与最新的OPA版本保持同步。Regorus支持import rego.v1。
符合 - Regorus与最新的OPA版本v0.67.0基本兼容。有关详细信息，请参阅OPA兼容性。请注意，虽然我们的行为结果相同，但我们尚未支持所有内置函数。
可扩展 - 通过在Rust中实现自定义状态化内置函数来扩展Rego语言。请参阅添加扩展。预计很快将支持使用其他语言进行扩展。
多语言 - 除了Rust之外，Regorus还可以从C、C++、C#、Golang、Java、Javascript、Python和Ruby中使用。这是通过Rust生态系统中的优秀FFI工具实现的。有关如何从不同语言使用Regorus的信息，请参阅绑定。

要尝试从您的浏览器中运行Regorus的编译版（JavaScript(WASM)），请访问Regorus沙盒。

Regorus可作为库提供，可轻松集成到您的Rust项目中。以下是一个评估简单Rego策略的示例

fn main() -> anyhow::Result<()> {
    // Create an engine for evaluating Rego policies.
    let mut engine = regorus::Engine::new();

    let policy = String::from(
        r#"
       package example
       import rego.v1

       allow if {
          ## All actions are allowed for admins.
          input.principal == "admin"
       } else if {
          ## Check if action is allowed for given user.
          input.action in data.allowed_actions[input.principal]
       }
	"#,
    );

    // Add policy to the engine.
    engine.add_policy(String::from("policy.rego"), policy)?;

    // Add data to engine.
    engine.add_data(regorus::Value::from_json_str(
        r#"{
     "allowed_actions": {
        "user1" : ["read", "write"],
        "user2" : ["read"]
     }}"#,
    )?)?;

    // Set input and evaluate whether user1 can write.
    engine.set_input(regorus::Value::from_json_str(
        r#"{
      "principal": "user1",
      "action": "write"
    }"#,
    )?);

    let r = engine.eval_rule(String::from("data.example.allow"))?;
    assert_eq!(r, regorus::Value::from(true));

    // Set input and evaluate whether user2 can write.
    engine.set_input(regorus::Value::from_json_str(
        r#"{
      "principal": "user2",
      "action": "write"
    }"#,
    )?);

    let r = engine.eval_rule(String::from("data.example.allow"))?;
    assert_eq!(r, regorus::Value::Undefined);

    Ok(())
}

Regorus的设计考虑了机密计算。在机密计算环境中，能够精确控制正在运行的内容非常重要。Regorus允许通过Cargo功能启用和禁用各种组件。默认情况下，所有功能均已启用。

regorus示例程序的默认构建版本大小为6.3M。

$ cargo build -r --example regorus; strip target/release/examples/regorus; ls -lh target/release/examples/regorus
-rwxr-xr-x  1 anand  staff   6.3M May 11 22:03 target/release/examples/regorus*

当禁用所有默认功能时，二进制文件大小降至1.9M。

$ cargo build -r --example regorus --no-default-features; strip target/release/examples/regorus; ls -lh target/release/examples/regorus
-rwxr-xr-x  1 anand  staff   1.9M May 11 22:04 target/release/examples/regorus*

Regorus通过了OPA v0.67.0测试套件，但有几个内置函数除外。请参阅下面的OPA兼容性。

绑定

Regorus可以用多种语言使用。

C：使用cbindgen生成C绑定。corrosion-rs可用于在基于CMake的项目中无缝使用Regorus。请参阅bindings/c。
C独立：bindings/c_no_std展示了如何在没有libc的情况下从C环境中使用Regorus。
C++：使用cbindgen生成C++绑定。corrosion-rs可用于在基于CMake的项目中无缝使用Regorus。请参阅bindings/cpp。
C#：使用csbindgen生成C#绑定。请参阅bindings/csharp，了解如何在C#项目中构建和使用Regorus的示例。
Golang：通过CGo将C绑定暴露给Golang。请参阅bindings/go，了解如何在Go项目中构建和使用Regorus的示例。
Python：使用pyo3生成Python绑定。使用maturin创建wheel。请参阅bindings/python。
Java：使用jni-rs开发Java绑定。请参阅bindings/java。
JavaScript：Regorus使用wasmpack编译为WASM。请参阅bindings/wasm，了解从nodejs中使用Regorus的示例。要尝试从您的浏览器中编译JavaScript(WASM)版本的Regorus，请访问Regorus Playground。
Ruby：使用magnus开发Ruby绑定。请参阅bindings/ruby。

为了减少操作开销，我们目前不将这些绑定发布到各个仓库。自己构建这些绑定非常简单。

入门

examples/regorus是一个示例程序，展示了如何将Regorus集成到项目中并评估Rego策略。

要构建和安装它，请执行以下操作：

$ cargo install --example regorus --path .

检查regorus示例程序是否正常工作

$ regorus
Usage: regorus <COMMAND>

Commands:
  eval   Evaluate a Rego Query
  lex    Tokenize a Rego policy
  parse  Parse a Rego policy
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

首先，让我们评估一个简单的Rego表达式 1*2+3

$ regorus eval "1*2+3"

这将产生以下输出

{
  "result": [
    {
      "expressions": [
        {
           "value": 5,
           "text": "1*2+3",
           "location": {
              "row": 1,
              "col": 1
            }
        }
      ]
    }
  ]
}

接下来，评估一个示例策略policy和input（从Rego教程借用）

$ regorus eval -d examples/example.rego -i examples/input.json data.example

最后，评估在Azure容器实例（ACI）中使用的真实世界策略policies

$ regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.policy.mount_overlay=x

政策覆盖

Regorus 允许通过使用 coverage 功能（默认启用）来确定政策中的哪些行已被执行。

我们可以通过传递 --coverage 标志来使用 regorus 示例程序进行尝试。

$ regorus eval -d examples/example.rego -i examples/input.json data.example --coverage

它生成以下覆盖报告，显示除了将 allow 设置为 true 的那行之外，所有行都已执行。

有关详细信息，请参阅 Engine::get_coverage_report。政策覆盖信息对于调试您的策略以及编写测试以使策略的所有行都由测试执行非常有用。

ACI 策略

Regorus 成功通过了 ACI 策略测试套件。它运行速度快，每个测试可以在几毫秒内运行。

$ cargo test -r --test aci
    Finished release [optimized + debuginfo] target(s) in 0.05s
    Running tests/aci/main.rs (target/release/deps/aci-2cd8d21a893a2450)
aci/mount_device                                  passed    3.863292ms
aci/mount_overlay                                 passed    3.6905ms
aci/scratch_mount                                 passed    3.643041ms
aci/create_container                              passed    5.046333ms
aci/shutdown_container                            passed    3.632ms
aci/scratch_unmount                               passed    3.631333ms
aci/unmount_overlay                               passed    3.609916ms
aci/unmount_device                                passed    3.626875ms
aci/load_fragment                                 passed    4.045167ms

在 tests/aci 目录中运行 ACI 策略，使用数据 tests/aci/data.json 和输入 tests/aci/input.json

$ regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.policy.mount_overlay=x

验证 OPA 产生相同的输出

$ diff <(regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x) \
       <(opa eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x)

性能

要检查 Regorus 在您系统上的运行速度，首先安装一个像 hyperfine 这样的工具。

$ cargo install hyperfine

然后基准测试 ACI 策略的评估

$ hyperfine "regorus eval -b tests/aci -d tests/aci/data.json -i   tests/aci/input.json data.framework.mount_overlay=x"
Benchmark 1: regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x
  Time (mean ± σ):       4.6 ms ±   0.2 ms    [User: 4.1 ms, System: 0.4 ms]
  Range (min … max):     4.4 ms …   6.0 ms    422 runs

与 OPA 进行比较

$ hyperfine "opa eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x"
Benchmark 1: opa eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x
  Time (mean ± σ):      45.2 ms ±   0.6 ms    [User: 68.8 ms, System: 5.1 ms]
  Range (min … max):    43.8 ms …  46.7 ms    62 runs

OPA 兼容性

Regorus 已经过验证符合 OPA v0.67.0，使用一个测试驱动程序，该驱动程序使用 Regorus 加载和运行 OPA 测试套件，并验证是否生成了预期输出。

可以通过运行以下命令来调用测试驱动程序

$ cargo test -r --test opa --features opa-testutil,serde_json/arbitrary_precision

目前，Regorus 通过了所有非内建特定测试。请参阅 passing tests suites。

以下测试套件由于缺少内置函数而没有完全通过

cryptoparsersaprivatekeys
cryptox509parseandverifycertificates
cryptox509parsecertificaterequest
cryptox509parsecertificates
cryptox509parsekeypair
cryptox509parsersaprivatekey
globsmatch
graphql
invalidkeyerror
jsonpatch
jwtdecodeverify
jwtencodesign
jwtencodesignraw
jwtverifyhs256
jwtverifyhs384
jwtverifyhs512
jwtverifyrsa
netcidrcontains
netcidrcontainsmatches
netcidrexpand
netcidrintersects
netcidrisvalid
netcidrmerge
netcidroverlap
netlookupipaddr
providers-aws
regometadatachain
regometadatarule
regoparsemodule
rendertemplate

它们记录在以下 github issues 中。

语法

Regorus 用于解析 Rego 策略的语法在 grammar.md 中描述，包括 W3C EBNF 和 RailRoad Diagram 格式。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一个贡献者许可协议（CLA），声明您有权，并且实际上确实授予我们使用您的贡献的权利。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人将自动确定您是否需要提供 CLA，并适当地装饰 PR（例如，状态检查，注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的 CLA 的存储库中做一次。

本项目采用了微软开源行为准则。如需更多信息，请查看行为准则常见问题解答或通过opencode@microsoft.com联系，有任何疑问或评论。

商标

本项目可能包含项目、产品或服务的商标或标志。微软商标或标志的授权使用必须遵循微软商标与品牌指南。在使用本项目修改版本的微软商标或标志时，不得引起混淆或暗示微软赞助。任何第三方商标或标志的使用均需遵守第三方政策。

依赖项

~1–13MB
~164K SLoC