How to use Cerbos effectively

OK, that's editing sorted out. How do you run Cerbos? There are many options to choose from, including Homebrew bottles, DEB or RPM packages, tarballs, Docker containers, Helm charts and even a GitHub Action. The Docker container is the easiest way to get started because it's just a single command:

docker run --rm --name cerbos -p 3592:3592 -v $(pwd):/policies ghcr.io/cerbos/cerbos:latest

If you had any policy files in the current working directory, Cerbos would have loaded them already and they're ready for use right away. You can drop any new files in or edit existing ones in the current directory and Cerbos will automatically update itself. Remember what we said earlier about Cerbos being painless?

Although the Cerbos container is all you need to get everything done, it's handy to have the cerbos and cerbosctl binaries installed on your developer machines. Use brew, apt, dnf or simply extract the tarballs to your $PATH to install them.

Import existing policies from the Playground

If you have been tinkering with some policies on the Cerbos Playground and want to use them as the base for developing more policies on your own machine, you can simply hit the Export button to download a zip archive containing them.

If you're using the disk storage driver with Cerbos, simply extract the files to the configured policy directory. With the Cerbos container, it's only a matter of mounting the directory under /policies inside the container (-v /path/to/extracted/policies:/policies). With the other Cerbos installation methods, you either need to edit the configuration file or add --set=storage.disk.directory=/path/to/extracted/policies to the set of command line arguments passed to Cerbos.

If you're using one of the mutable storage drivers such as mysql, postgres, sqlite3 or sqlserver and have the Admin API enabled, you don't even have to extract the zip file. The `cerbosctl put` utility is capable of loading policies and schemas into Cerbos directly from a zip archive.

Manage Cerbos with cerbosctl

The cerbosctl utility ships with several handy utilities for interacting with Cerbos instances that have the Admin API enabled. You can view the policies and schemas available in the store, add or update policies and schemas (if the store is mutable), and reload the store.

If you have enabled local audit logs on the Cerbos instance, cerbosctl audit lets you filter and view the audit log entries on your terminal. The output can be exported as JSON for further processing with other analytics tools of your choice. There’s even a text user interface (TUI) for browsing the audit entries using the keyboard.

Write code to interact with Cerbos

Things are going well so far. You've written some simple policies, and you’ve written some integration code using one of the many SDKs to call the Cerbos API to make authorization decisions. Now you want to share that code with your colleagues for experimentation or try to get your CI system to test it. You want to make it easy but it's way too early to bust out the heavyweights like Docker Compose or Podman. Then, how do you get the Cerbos "sidecar" process to run alongside your app? We have got you covered there too with `cerbos run`. To illustrate, let's say you have been writing a Python script named awesome_cerbos_poc.py to try out Cerbos. You have your Cerbos policies stored in a subdirectory named policies alongside your script. Now all you need to do is to run the following command:

cerbos run -- python awesome_cerbos_poc.py

The above command will start a Cerbos instance and then launch a Python interpreter to run the awesome_cerbos_poc.py script. The script can access Cerbos using the values of CERBOS_HTTP or CERBOS_GRPC variables that are automatically injected into the process environment. When the script exits, the Cerbos instance shuts down as well. Easy!

Writing advanced policy expressions

You can use the Common Expression Language (CEL) to write conditional rules in Cerbos policies. This is one of the most powerful features of Cerbos because it allows the business logic associated with authorization to be externalized from your application code. When business requirements inevitably change, in most cases you can get away with just modifying the Cerbos policy instead of changing and deploying your application. In a monolithic application, this might not be too difficult (although, you still have to develop, test and rollout to production -- which can be quite intensive depending on the nature of the system). However, if you have multiple services or systems (usually developed in different languages or by different teams) that need to follow these business logic changes, then the benefit of Cerbos is quite obvious. With a single, non-intrusive Cerbos policy rollout (essentially a Git push), all of those systems will be automatically in compliance without any manual intervention.

CEL is a very simple language and its syntax would be familiar to anyone who has worked with C-family languages such as Java, Javascript, Go, Rust and so on. Cerbos supports all the built-in CEL functions with some extra functions built by us to support common authorization use cases. Even though most of these functions are easy to understand and use by just reading the documentation, sometimes the best way to figure out how something works is to just try it out. This is even more important when developing a pipeline of function calls that feed their results to other functions. You can do that with the Cerbos REPL. You can start it by running the cerbos repl command (or, docker run -it ghcr.io/cerbos/cerbos:latest repl).

You can evaluate CEL expressions on the REPL. For example, if you type in 1 + 1, it will output 2. The result of the last successfully evaluated expression is stored in the special _ variable. So, if you type in _ + 2 now, the result would be 4. You can even define your own variables and assign values to them to be used later.