Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Regorus
Regorus is
- Rego-Rus(t) - A fast, light-weight Rego interpreter written in Rust.
- Rigorous - A rigorous enforcer of well-defined Rego semantics.
Regorus is also
-
cross-platform - Written in platform-agnostic Rust.
-
no_std compatible - Regorus can be used in
no_std
environments too. Most of the builtins are supported. -
current - We strive to keep Regorus up to date with latest OPA release. Regorus supports
import rego.v1
. -
compliant - Regorus is mostly compliant with the latest OPA release v0.64.0. See OPA Conformance for details. Note that while we behaviorally produce the same results, we don't yet support all the builtins.
-
extensible - Extend the Rego language by implementing custom stateful builtins in Rust. See add_extension. Support for extensibility using other languages coming soon.
-
polyglot - In addition to Rust, Regorus can be used from C, C++, C#, Golang, Java, Javascript, Python, and Ruby. This is made possible by the excellent FFI tools available in the Rust ecosystem. See bindings for information on how to use Regorus from different languages.
To try out a Javascript(WASM) compiled version of Regorus from your browser, visit Regorus Playground.
Regorus is available as a library that can be easily integrated into your Rust projects. Here is an example of evaluating a simple Rego policy:
Regorus is designed with Confidential Computing in mind. In Confidential Computing environments, it is important to be able to control exactly what is being run. Regorus allows enabling and disabling various components using cargo features. By default all features are enabled.
The default build of regorus example program is 6.3M:
; ;
When all default features are disabled, the binary size drops down to 1.9M.
; ;
Regorus passes the OPA v0.64.0 test-suite barring a few builtins. See OPA Conformance below.
Bindings
Regorus can be used from a variety of languages:
- C: C binding is generated using cbindgen. corrosion-rs can be used to seamlessly use Regorous in your CMake based projects. See bindings/c.
- C freestanding: bindings/c_no_std shows how to use Regorus from C environments without a libc.
- C++: C++ binding is generated using cbindgen. corrosion-rs can be used to seamlessly use Regorous in your CMake based projects. See bindings/cpp.
- C#: C# binding is generated using csbindgen. See bindings/csharp for an example of how to build and use Regorus in your C# projects.
- Golang: The C bindings are exposed to Golang via CGo. See bindings/go for an example of how to build and use Regorus in your Go projects.
- Python: Python bindings are generated using pyo3. Wheels are created using maturin. See bindings/python.
- Java: Java bindings are developed using jni-rs. See bindings/java.
- Javascript: Regorus is compiled to WASM using wasmpack. See bindings/wasm for an example of using Regorus from nodejs. To try out a Javascript(WASM) compiled version of Regorus from your browser, visit Regorus Playground.
- Ruby: Ruby bindings are developed using magnus. See bindings/ruby.
To avoid operational overhead, we currently don't publish these bindings to various repositories. It is straight-forward to build these bindings yourself.
Getting Started
examples/regorus is an example program that shows how to integrate Regorus into your project and evaluate Rego policies.
To build and install it, do
Check that the regorus example program is working
)
First, let's evaluate a simple Rego expression 1*2+3
This produces the following output
Next, evaluate a sample policy and input (borrowed from Rego tutorial):
Finally, evaluate real-world policies used in Azure Container Instances (ACI)
Policy coverage
Regorus allows determining which lines of a policy have been executed using the coverage
feature (enabled by default).
We can try it out using the regorus
example program by passing in the --coverage
flag.
$ regorus eval -d examples/example.rego -i examples/input.json data.example --coverage
It produces the following coverage report which shows that all lines are executed except the line that sets allow
to true.
See Engine::get_coverage_report for details. Policy coverage information is useful for debugging your policy as well as to write tests for your policy so that all lines of the policy are exercised by the tests.
ACI Policies
Regorus successfully passes the ACI policy test-suite. It is fast and can run each of the tests in a few milliseconds.
)
)
Run the ACI policies in the tests/aci
directory, using data tests/aci/data.json
and input tests/aci/input.json
:
Verify that OPA produces the same output
Performance
To check how fast Regorus runs on your system, first install a tool like hyperfine.
Then benchmark evaluation of the ACI policies,
)
)
Compare it with OPA
)
)
OPA Conformance
Regorus has been verified to be compliant with OPA v0.64.0 using a test driver that loads and runs the OPA testsuite using Regorus, and verifies that expected outputs are produced.
The test driver can be invoked by running:
Currently, Regorus passes all the non-builtin specific tests. See passing tests suites.
The following test suites don't pass fully due to mising builtins:
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
They are captured in the following github issues.
Grammar
The grammar used by Regorus to parse Rego policies is described in grammar.md in both W3C EBNF and RailRoad Diagram formats.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Trademarks
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.