cerbos

This documentation is for a previous version of Cerbos. Choose 0.39.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

See Install from binary or Run from container for instructions on how to install the cerbos binary.

This binary provides the following sub commands:

compile

Validate, compile and run tests on a policy repo

healthcheck

Perform a healthcheck on a Cerbos PDP

repl

An interactive REPL (read-evaluate-print-loop) for CEL conditions

run

Start a PDP and run a command within its context

server

Start the PDP server

Example: Running compile using the binary
./cerbos compile --help
Example: Running compile using the container
docker run -i -t ghcr.io/cerbos/cerbos:0.37.0 compile --help

compile Command

Runs the Cerbos compiler to validate policy definitions and run any test suites. See Policy compilation for more information.

This command exits with different exit codes depending on the kind of failure.

0

No compile or test failures

1

Unknown failure

2

Invalid arguments to command

3

Compilation failed

4

Tests failed

 
Usage: cerbos compile <dir>

Compile and test policies

Examples:

# Compile and run tests found in /path/to/policy/repo

cerbos compile /path/to/policy/repo

# Compile and run tests that contain "Delete" in their name

cerbos compile --run=Delete /path/to/policy/repo

# Compile but skip tests

cerbos compile --skip-tests /path/to/policy/repo

Arguments:
  <dir>    Policy directory

Flags:
  -h, --help                       Show context-sensitive help.
      --version                    Show cerbos version

      --ignore-schemas             Ignore schemas during compilation
      --tests=STRING               Path to the directory containing tests. Defaults to policy directory.
      --run=STRING                 Run only tests that match this regex
      --skip-tests                 Skip tests
  -o, --output="tree"              Output format (tree,list,json)
      --test-output=TEST-OUTPUT    Test output format. If unspecified matches the value of the output flag. (tree,list,json,junit)
      --color=COLOR                Output color level (auto,never,always,256,16m). Defaults to auto.
      --no-color                   Disable colored output
      --verbose                    Verbose output on test failure

healthcheck Command

Utility to perform healthchecks on a Cerbos PDP. Can be used as a Docker HEALTHCHECK command.

You can share the configuration between Cerbos PDP and the healthcheck by using the CERBOS_CONFIG environment variable to define the path to the config file.

Example: Docker healthcheck based on mounted config file
docker run -i -t -p 3592:3592 -p 3593:3593 \
    -v /path/to/conf/dir:/config \
    -e CERBOS_CONFIG=/config/.cerbos.yaml \
    ghcr.io/cerbos/cerbos:0.37.0
Usage: cerbos healthcheck (hc)

Healthcheck utility

Performs a healthcheck on a Cerbos PDP. This can be used as a Docker HEALTHCHECK command. When the path to the Cerbos config file is provided via the '--config' flag or the CERBOS_CONFIG environment variable, the
healthcheck will be automatically configured based on the settings from the file. By default, the gRPC endpoint will be checked using the gRPC healthcheck protocol. This is usually sufficient for most cases as the Cerbos
REST API is built on top of the gRPC API as well.

Examples:

# Check gRPC endpoint

cerbos healthcheck --config=/path/to/.cerbos.yaml

# Check HTTP endpoint and ignore server certificate verification

cerbos healthcheck --config=/path/to/.cerbos.yaml --kind=http --insecure

# Check the HTTP endpoint of a specific host with no TLS.

cerbos healthcheck --kind=http --host-port=10.0.1.5:3592 --no-tls

Flags:
  -h, --help           Show context-sensitive help.
      --version        Show cerbos version

      --kind="grpc"    Healthcheck kind (grpc,http) ($CERBOS_HC_KIND)
      --insecure       Do not verify server certificate ($CERBOS_HC_INSECURE)
      --timeout=10s    Healthcheck timeout ($CERBOS_HC_TIMEOUT)

config
  --config=STRING    Cerbos config file ($CERBOS_CONFIG)

manual
  --host-port=STRING    Host and port to connect to ($CERBOS_HC_HOSTPORT)
  --ca-cert=STRING      Path to CA cert for validating server cert ($CERBOS_HC_CACERT)
  --no-tls              Don't use TLS ($CERBOS_HC_NOTLS)

repl Command

The REPL is an interactive utility to experiment with CEL conditions used in Cerbos policy rules. All Cerbos library functions and special variables (request, R, P and so on) are available in this environment.

Example: Running the REPL using the binary
./cerbos repl
Example: Running the REPL using the container
docker run -i -t ghcr.io/cerbos/cerbos:0.37.0 repl

You can type in valid CEL expressions at the prompt to instantly evaluate them.

-> 5 + 1
_ = 6

-> "test".charAt(1)
_ = "e"

The special variable _ holds the result of the last expression evaluated.

-> 5 + 5
_ = 10

-> _ * 10
_ = 100

You can define variables using the :let directive.

-> :let x = hierarchy("a.b.c")
x = [
  "a",
  "b",
  "c"
]

-> :let y = hierarchy("a.b")
y = [
  "a",
  "b"
]

-> x.immediateChildOf(y)
_ = true

You can also set special variables used in Cerbos policies (request, variables, R, P, V) and try out CEL expressions using them.

-> :let request = {
>   "principal":{"id":"john","roles":["employee"],"attr":{"scope":"foo.bar.baz.qux"}},
>   "resource":{"id":"x1","kind":"leave_request","attr":{"scope":"foo.bar"}}
> }

-> hierarchy(R.attr.scope).ancestorOf(hierarchy(P.attr.scope))
_ = true

Type :vars to display the values of all the variables currently defined in the environment.

You can load a Cerbos policy into the REPL by typing :load path/to/policy_file.yaml. This will read the policy and load any rules that have conditions attached. These can be viewed by typing :rules. Execute any rule by providing its number to the :exec directive (for example, :exec #2). Rules are executed using the variables defined in the current REPL session. You can set or update them using the :let directive and re-execute the rules to see the effects.

-> :load store/leave_request.yaml
Loaded resource.leave_request.v20210210

Policy variables:
{
  "pending_approval": "(\"PENDING_APPROVAL\")",
  "principal_location": "(P.attr.ip_address.inIPAddrRange(\"10.20.0.0/16\") ? \"GB\" : \"\")"
}

Conditional rules in 'resource.leave_request.v20210210'

[#0]
    actions:
    - approve
    condition:
      match:
        expr: request.resource.attr.status == V.pending_approval
    derivedRoles:
    - direct_manager
    effect: EFFECT_ALLOW


-> :exec #0
└──request.resource.attr.status == V.pending_approval [false]

Type :help or :h to display help. Type :quit, :q or :exit to exit the REPL.

Use the up/down arrow keys (or Ctrl+P/Ctrl+N) to navigate command history. Most of the standard line-editing commands such as Ctrl+a, Ctrl+h, Ctrl+r are supported as well.

run Command

This provides a quick way to try out Cerbos. It launches a Cerbos PDP instance and then invokes a command of your choice that can then use the PDP to make access decisions. A good use case for this command is as an integration test runner. If you have written some tests that make use of Cerbos, you can run them within the context of an actual PDP instance as follows:

cerbos run -- python -m unittest

By default, the policies are loaded from the policies directory in the current working directory and HTTP and gRPC endpoints will be exposed on 127.0.0.1:3592 and 127.0.0.1:3593 respectively. Your application can obtain the actual endpoint addresses by inspecting the CERBOS_HTTP or CERBOS_GRPC environment variables.

If a file named .cerbos.yaml exists in the current working directory, that file will be used as the Cerbos configuration file. You can use a different config file or override specific config values using the same flags as the server command above.

Usage: cerbos run <command> ...

Run a command in the context of a Cerbos PDP

Launches a command within the context of a Cerbos PDP. The policies are loaded by default from a directory named "policies" in the current working directory. The launched application can access Cerbos endpoints using the
values from CERBOS_HTTP or CERBOS_GRPC environment variables.

If a file named ".cerbos.yaml" exists in the current working directory, it will be used as the configuration file for the PDP. You can override the config file and/or other configuration options using the flags described
below.

Examples:

# Launch Go tests within a Cerbos context

cerbos run -- go test ./...

# Start Cerbos with a custom configuration file and run Python tests within the context

cerbos run --config=myconf.yaml -- python -m unittest

# Silence Cerbos log output

cerbos run --log-level=error -- curl -I http://127.0.0.1:3592/_cerbos/health

Arguments:
  <command> ...    Command to run

Flags:
  -h, --help                                    Show context-sensitive help.
      --version                                 Show cerbos version

      --log-level="info"                        Log level (debug,info,warn,error)
      --config=.cerbos.yaml                     Path to config file
      --set=server.adminAPI.enabled=true,...    Config overrides
      --timeout=30s                             Cerbos startup timeout

server Command

Starts the Cerbos PDP.

Usage: cerbos server --config=.cerbos.yaml

Start Cerbos server (PDP)

Examples:

# Start the server

cerbos server --config=/path/to/.cerbos.yaml

# Start the server with the Admin API enabled and the 'sqlite' storage driver

cerbos server --config=/path/to/.cerbos.yaml --set=server.adminAPI.enabled=true --set=storage.driver=sqlite3 --set=storage.sqlite3.dsn=':memory:'

Flags:
  -h, --help                                    Show context-sensitive help.
      --version                                 Show cerbos version

      --debug-listen-addr=:6666                 Address to start the gops listener
      --log-level="info"                        Log level (debug,info,warn,error)
      --config=.cerbos.yaml                     Path to config file
      --set=server.adminAPI.enabled=true,...    Config overrides