Testing Custom Rules with Fregot¶
What is Fregot?¶
Fregot is an open-source set of tools designed to enhance the Rego development experience, with or without Fugue. It allows you to evaluate any .rego
file, just like the OPA agent. However, Fregot is more lightweight and focuses on just the language implementation, rather than all the other things OPA does, such as running as a server and enforcing admission control policies in Kubernetes. Fregot also features debugging tools and enhanced error messages.
As a result, Fregot is especially handy for working with Fugue custom rules.
Fregot’s most important feature is the REPL (read-eval-print loop), which is an interactive programming environment. Inside the REPL, you can:
Test custom rules using different input documents
Jump inside a function and follow it step by step
Evaluate queries in context
Check a value’s type
For more information, see Using fregot repl to Debug Custom Rules.
Fregot also offers an eval
command to quickly test a single expression. For more information, see Using fregot eval to Test Custom Rules.
Installing Fregot and the fugue.rego library¶
To get started with Fregot, there are a couple one-time steps you need to take:
Install Fregot
Download the fugue.rego library
In Fugue, custom rules are evaluated using a library called fugue.rego
. When working with rules locally, you’ll need to download the library and save it to the directory where you keep your custom rules so you can import it into your Rego files.
Steps for creating a new rule to evaluate with Fregot¶
Any time you create a new rule that you want to evaluate with Fregot, you’ll need to follow these steps:
Create a
.rego
fileAdd a
package
declarationImport the
fugue.rego
library
Create a .rego file: Open up your favorite text editor and create a new text file with a .rego
extension in the same directory where you saved fugue.rego
.
Package declaration: This part is handled for you behind the scenes in Fugue. But when working with Rego locally, every .rego
file must have a package declaration. You can call it anything, but it’s most useful to give it a descriptive name, such as the filename without the extension:
package vm_size
Import line: This instructs Fregot to import the fugue.rego library, which allows you to use Fugue-specific functions such as fugue.allow_resource(resource)
, fugue.resources(resource_type)
, and so on. Like the package declaration, it’s also a requirement for local development.
import data.fugue
So at the very beginning of any Fugue custom rule file, add a package declaration and import the fugue.rego
library, as shown below:
package <insert your own package name here>
import data.fugue
You can write your rule underneath those lines. See Writing Rules for information on writing rules.
Test a custom rule with Fregot¶
Once you’ve written a rule, Fregot offers two ways to evaluate it:
fregot eval: Useful for quickly evaluating a single expression, such as
policy
fregot repl: Useful for debugging a rule and evaluating queries inside a rule
Both methods require a .rego
rule to test and a .json
input document to test it against.
Get the test input document¶
To test a rule in Fregot, you need to retrieve the input document from the CLI or API. The input document represents all of the resources in an environment at the time of the specified scan.
See the documentation for the CLI or API to retrieve the input and save the entire response as a .json
file, such as input.json
or similar.
Once you have the test input, you can test your custom rules with fregot eval or fregot repl.