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:
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 file: Open up your favorite text editor and create a new text file with a
.rego extension in the same directory where you saved
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:
Import line: This instructs Fregot to import the fugue.rego library, which allows you to use Fugue-specific functions such as
fugue.resources(resource_type), and so on. Like the package declaration, it’s also a requirement for local development.
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
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.