mirror of
https://github.com/microsoft/regorus.git
synced 2026-08-05 02:16:11 +00:00
Updated readme. Added bundle support. (#61)
Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>
This commit is contained in:
Anand Krishnamoorthi
committed by
GitHub
GitHub
parent
70bf371ebf
commit
8a73b4bef9
128
README.md
128
README.md
@@ -1,9 +1,129 @@
|
||||
# regorus
|
||||
# Regorus
|
||||
|
||||
THIS REPOSITORY IS IN ACTIVE DEVELOPMENT AND NOT INTENDED FOR PRODUCTION USE.
|
||||
**Regorus** is
|
||||
|
||||
- *Rego*-*Rus(t)* - A fast, light-weight [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) 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.
|
||||
|
||||
|
||||
> **Warning**
|
||||
> While Regorus is highly performant and can interpret complex Rego policies, it does not yet pass the full [OPA test-suite](https://www.openpolicyagent.org/docs/latest/ir/#test-suite).
|
||||
> We are actively working to achieve full OPA compliance. Meanwhile, Regorus should be considered
|
||||
> **experimental and used with discretion**.
|
||||
|
||||
## Getting Started
|
||||
|
||||
[regorus](examples/regorus.rs) is an example program that shows how to integrate Regorus into your project and evaluate Rego policies.
|
||||
|
||||
To build it, do
|
||||
|
||||
cargo build -r --example regorus
|
||||
|
||||
|
||||
Check that the regorus example program is working
|
||||
|
||||
$ target/release/examples/regorus
|
||||
Usage: regorus <COMMAND>
|
||||
|
||||
Commands:
|
||||
eval Evaluate a Rego Query
|
||||
lex Tokenize a Rego policy
|
||||
parse Parse q 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`
|
||||
|
||||
target/release/examples/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](examples/example.rego) and [input](examples/input.json) (borrowed from [Rego tutorial](https://www.openpolicyagent.org/docs/latest/#2-try-opa-eval)):
|
||||
|
||||
target/release/examples/regorus eval -d examples/example.rego -i examples/input.json data.example
|
||||
|
||||
Finally, evaluate real-world [policies](tests/aci/) used in Azure Container Instances (ACI)
|
||||
|
||||
target/release/examples/regorus eval -d tests/aci/framework.rego \
|
||||
-d tests/aci/policy.rego \
|
||||
-d tests/aci/api.rego \
|
||||
-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`:
|
||||
|
||||
target/release/examples/regorus eval \
|
||||
-b tests/aci \
|
||||
-d tests/aci/data.json \
|
||||
-i tests/aci/input.json \
|
||||
data.framework.mount_overlay=x
|
||||
|
||||
Verify that [OPA](https://github.com/open-policy-agent/opa/releases) produces the same output
|
||||
|
||||
diff <(target/release/examples/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](https://github.com/sharkdp/hyperfine).
|
||||
|
||||
cargo install hyperfine
|
||||
|
||||
Then benchmark evaluation of the ACI policies,
|
||||
|
||||
$ hyperfine "target/release/examples/regorus eval -b tests/aci -d tests/aci/data.json -i tests/aci/input.json data.framework.mount_overlay=x"
|
||||
Benchmark 1: target/release/examples/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
|
||||
|
||||
**Regorus** is a Rego interpreter, analyzer and checker written in Rust.
|
||||
**Regorus** also aims to be a rigorous enforcer of formally defined Rego semantics.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
||||
Reference in New Issue
Block a user