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 available as a library that can be easily integrated into your Rust projects.
Here is an example of evaluating a simple Rego policy:
use anyhow::Result;
use regorus::*;
use serde_json;
fn main() -> Result<()> {
// Create an engine for evaluating Rego policies.
let mut engine = Engine::new();
// Add policy to the engine.
engine.add_policy(
// Filename to be associated with the policy.
"hello.rego".to_string(),
// Rego policy that just sets a message.
r#"
package test
message = "Hello, World!"
"#.to_string()
)?;
// Evaluate the policy, fetch the message and print it.
let results = engine.eval_query("data.test.message".to_string(), false)?;
println!("{}", serde_json::to_string_pretty(&results)?);
Ok(())
}
Regorus passes the OPA v0.60.0 test-suite barring a few builtins. See OPA Conformance below.
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
$ cargo install --example regorus --path .
Check that the regorus example program is working
$ 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
First, let's evaluate a simple Rego expression 1*2+3
$ regorus eval "1*2+3"
This produces the following output
{
"result": [
{
"expressions": [
{
"value": 5,
"text": "1*2+3",
"location": {
"row": 1,
"col": 1
}
}
]
}
]
}
Next, evaluate a sample policy and input (borrowed from Rego tutorial):
$ regorus eval -d examples/example.rego -i examples/input.json data.example
Finally, evaluate real-world policies used in Azure Container Instances (ACI)
$ regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.policy.mount_overlay=x
ACI Policies
Regorus successfully passes the ACI policy test-suite. It is fast and can run each of the tests in a few milliseconds.
$ 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
Run the ACI policies in the tests/aci directory, using data tests/aci/data.json and input tests/aci/input.json:
$ regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.policy.mount_overlay=x
Verify that OPA produces the same output
$ 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)
Performance
To check how fast Regorus runs on your system, first install a tool like hyperfine.
$ cargo install hyperfine
Then benchmark evaluation of the ACI policies,
$ 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
Compare it with 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 Conformance
Regorus has been verified to be compliant with OPA v0.60.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:
$ cargo test -r --test opa
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:
cryptoparsersaprivatekeyscryptox509parseandverifycertificatescryptox509parsecertificaterequestcryptox509parsecertificatescryptox509parsekeypaircryptox509parsersaprivatekeyglobsmatchgraphqlinvalidkeyerrorjsonpatchjwtbuiltinsjwtdecodeverifyjwtencodesignjwtencodesignrawjwtverifyhs256jwtverifyhs384jwtverifyhs512jwtverifyrsanetcidrcontainsnetcidrcontainsmatchesnetcidrexpandnetcidrintersectsnetcidrisvalidnetcidrmergenetcidroverlapnetlookupipaddrproviders-awsregometadatachainregometadataruleregoparsemodulerendertemplatetime
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.