`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