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:

  1. Install Fregot

  2. 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:

  1. Create a .rego file

  2. Add a package declaration

  3. Import 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.