cerbosctl

This utility is included in the tar archives, Linux packages and the Homebrew tap. See Install from binary for instructions on how to install this binary from one of those sources.

This utility requires the Admin API to be enabled on the Cerbos server.

The server address to connect to and the credentials to authenticate can be provided through environment variables or as arguments to the command.

Cerbos instance administration commands
The Cerbos Admin API must be enabled in order for these commands to work.
The Admin API requires credentials. They can be provided using a netrc file,
environment variables or command-line arguments.

Environment variables

CERBOS_SERVER: gRPC address of the Cerbos server
CERBOS_USERNAME: Admin username
CERBOS_PASSWORD: Admin password

When more than one method is used to provide credentials, the precedence from lowest to
highest is: netrc < environment < command line.

Usage:
  cerbosctl [command]

Examples:

# Connect to a TLS enabled server while skipping certificate verification and launch the decisions viewer
cerbosctl --server=localhost:3593 --username=user --password=password --insecure decisions

# Connect to a non-TLS server and launch the decisions viewer
cerbosctl --server=localhost:3593 --username=user --password=password --plaintext decisions

Available Commands:
  audit       View audit logs
  completion  Generate the autocompletion script for the specified shell
  decisions   Interactive decision log viewer
  get         List or view policies and schemas
  help        Help about any command
  put         Put policies or schemas
  version     Show cerbosctl and PDP version

Flags:
      --ca-cert string       Path to the CA certificate for verifying server identity
      --client-cert string   Path to the TLS client certificate
      --client-key string    Path to the TLS client key
  -h, --help                 help for cerbosctl
      --insecure             Skip validating server certificate
      --password string      Admin password
      --plaintext            Use plaintext protocol without TLS
      --server string        Address of the Cerbos server
      --username string      Admin username
  -v, --version              version for cerbosctl

Use "cerbosctl [command] --help" for more information about a command.

audit

This command allows you to view the audit logs captured by the Cerbos server. Audit logging must be enabled on the server to obtain the data through this command.

Filters
tail

Get the last N records (e.g. --tail=10)

between

Get records between two ISO-8601 timestamps. If the last timestamp is left out, get records from the first timestamp up to now.

  • --between=2021-07-01T00:00:00Z,2021-07-02T00:00:00Z: From midnight of 2021-07-01 to midnight of 2021-07-02.

  • --between=2021-07-01T00:00:00Z: From midnight of 2021-07-01 to now.

since

Get records from N hours/minutes/second ago to now. (e.g. --since=3h)

lookup

Get a specific record by ID. (e.g. --lookup=01F9Y5MFYTX7Y87A30CTJ2FB0S)

View the last 10 access logs
cerbosctl audit --kind=access --tail=10
View the decision logs from midnight 2021-07-01 to midnight 2021-07-02
cerbosctl audit --kind=decision --between=2021-07-01T00:00:00Z,2021-07-02T00:00:00Z
View the decision logs from midnight 2021-07-01 to now
cerbosctl audit --kind=decision --between=2021-07-01T00:00:00Z
View the access logs from 3 hours ago to now as newline-delimited JSON
cerbosctl audit --kind=access --since=3h --raw
View a specific access log entry by call ID
cerbosctl audit --kind=access --lookup=01F9Y5MFYTX7Y87A30CTJ2FB0S

decisions

This command starts an interactive text user interface to view and analyze the decision records captured by the Cerbos server. It accepts the same filter flags as the audit command.

Decisions

  • tab Switch focus to different panes in the UI

  • esc Close window (or exit if you are in the main screen)

  • q Exit

Use the arrow keys (or Vim keys h, j, k, l) to scroll horizontally or vertically. Press enter to select/open an item.

Start analyzing the last 20 decision records
cerbosctl decisions --tail=20

get

This command lists the policies available in the configured policy repository. You can also retrieve individual policies or schemas by their identifiers and view their definitions as YAML or JSON.

You can filter the output using the name and version flags. Each flag accepts multiple comma-separated values which are OR’ed together. For example, --name=a.yaml,b.yaml matches policies that are either named a.yaml or b.yaml.

List derived roles
cerbosctl get derived_roles
cerbosctl get derived_role
cerbosctl get dr
List principal policies
cerbosctl get principal_policies
cerbosctl get principal_policy
cerbosctl get pp
List resource policies
cerbosctl get resource_policies
cerbosctl get resource_policy
cerbosctl get rp
List derived_roles where name is my_policy or a_policy
cerbosctl get derived_roles --name my_policy,a_policy
cerbosctl get dr --name my_policy,a_policy
List principal_policies where version is default or v1
cerbosctl get principal_policies --version default,v1
cerbosctl get pp --version default,v1
List derived_roles and sort by column policyId or name
cerbosctl get derived_roles --sort-by policyId
cerbosctl get dr --sort-by policyId

cerbosctl get derived_roles --sort-by name
cerbosctl get dr --sort-by name
List principal_policies and sort by column policyId, name or version
cerbosctl get principal_policies --sort-by policyId
cerbosctl get pp --sort-by policyId

cerbosctl get principal_policies --sort-by name
cerbosctl get pp --sort-by name

cerbosctl get principal_policies --sort-by version
cerbosctl get pp --sort-by version
List resource_policies and sort by column policyId, name or version
cerbosctl get resource_policies --sort-by policyId
cerbosctl get rp --sort-by policyId

cerbosctl get resource_policies --sort-by name
cerbosctl get rp --sort-by name

cerbosctl get resource_policies --sort-by version
cerbosctl get rp --sort-by version
Get JSON
cerbosctl get derived_roles my_derived_roles --format=json
Get YAML
cerbosctl get derived_roles my_derived_roles --format=yaml

put

This command puts the given policies or schemas to the configured policy repository.

Put policies
cerbosctl put policies ./path/to/policy.yaml
cerbosctl put policy ./path/to/policy.yaml
cerbosctl put p ./path/to/policy.yaml
Put multiple policies
cerbosctl put policy ./path/to/policy.yaml ./path/to/other/policy.yaml
Put policies under a directory
cerbosctl put policy ./dir/to/policies ./other/dir/to/policies
Put policies under a directory recursively
cerbosctl put policy --recursive ./dir/to/policies
cerbosctl put policy -R ./dir/to/policies
Put schemas
cerbosctl put schemas ./path/to/schema.json
cerbosctl put schema ./path/to/schema.json
cerbosctl put s ./path/to/schema.json
Put multiple schemas
cerbosctl put schema ./path/to/schema.json ./path/to/other/schema.json
Put schemas under a directory
cerbosctl put schema ./dir/to/schemas ./other/dir/to/schemas
Put schemas under a directory recursively
cerbosctl put schema --recursive ./dir/to/schemas
cerbosctl put schema -R ./dir/to/schemas