cerbosctl Command

The cerbosctl command is the entrypoint for Cerbos administration utilities. It 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 environment
variables or command-line arguments.

Environment variables

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

Alternatively, command-line flags can be used to provide the server address and credentials.
When both environment variables and command-line flags are provided, the flags take precedence.

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
  decisions   Explore Cerbos engine decision logs
  list        List active policies
  version     Display client and server versions

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

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

list

This command lists the policies available in the configured policy repository. The list can be filtered by specifying one or more pairs of field selectors and match values as command line arguments. Field selectors are expected to be valid JSONPath expressions describing policy fields. See specification for more information about JSONPath. The output is sorted by name by default.

Use --field-eq to perform an exact match and --field-match to perform a regular expression match.

List resource policies where the version field is exactly 20210210
cerbosctl list --field-eq='$.resourcePolicy.version=20210210'
List any policy where version is exactly 20210210
cerbosctl list --field-eq='$.*.version=20210210'
List resource policies where the resource field contains leave
cerbosctl list --field-match='$.resourcePolicy.resource=leave'
List resource policies with a numeric version
cerbosctl list --field-match='$.resourcePolicy.version=\d+'
List policies sorted by version
cerbosctl list --sort version
List policies sorted by version in descending order
cerbosctl list --sort version --sort-desc