cerbos

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

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.14.0 compile --help

compile Command

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

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

  -f, --format="pretty"    Output format (pretty,plain,json)
      --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
      --ignore-schemas     Ignore schemas during compilation
      --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/conf.yaml \
    ghcr.io/cerbos/cerbos:0.14.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/config.yaml

# Check HTTP endpoint and ignore server certificate verification

cerbos healthcheck --config=/path/to/config.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

      --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)

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

      --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=./config.yaml

Start Cerbos server (PDP)

Examples:

# Start the server

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

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

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

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

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