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.
cerbosctl audit --kind=access --tail=10
cerbosctl audit --kind=decision --between=2021-07-01T00:00:00Z,2021-07-02T00:00:00Z
cerbosctl audit --kind=decision --between=2021-07-01T00:00:00Z
cerbosctl audit --kind=access --since=3h --raw
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.
-
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.
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.
version
field is exactly 20210210
cerbosctl list --field-eq='$.resourcePolicy.version=20210210'
version
is exactly 20210210
cerbosctl list --field-eq='$.*.version=20210210'
resource
field contains leave
cerbosctl list --field-match='$.resourcePolicy.resource=leave'
cerbosctl list --field-match='$.resourcePolicy.version=\d+'
cerbosctl list --sort version
cerbosctl list --sort version --sort-desc