`cerbosctl`

This documentation is for a previous version of Cerbos. Choose 0.40.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

This utility can be downloaded as a separate container, tar archive, or npm package. It is automatically installed when installing Cerbos through Linux packages or the Homebrew tap.

Run from the container

docker run -it ghcr.io/cerbos/cerbosctl:0.36.0 \
    --server=192.168.1.10:3593 \
    --username=user \
    --password=password \
    get rp

Download and run the appropriate binary from https://github.com/cerbos/cerbos/releases/tag/v0.36.0
OS	Arch	Bundle
Linux	x86-64	`cerbosctl_0.36.0_Linux_x86_64.tar.gz`
Linux	arm64	`cerbosctl_0.36.0_Linux_arm64.tar.gz`
MacOS	universal	`cerbosctl_0.36.0_Darwin_all.tar.gz`
MacOS	x86-64	`cerbosctl_0.36.0_Darwin_x86_64.tar.gz`
MacOS	arm64	`cerbosctl_0.36.0_Darwin_arm64.tar.gz`

Cerbosctl 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.

Usage: cerbosctl <command>

A CLI for managing Cerbos

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.

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

Flags:
  -h, --help                       Show context-sensitive help.
      --server="localhost:3593"    Address of the Cerbos server ($CERBOS_SERVER)
      --username=STRING            Admin username ($CERBOS_USERNAME)
      --password=STRING            Admin password ($CERBOS_PASSWORD)
      --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
      --insecure                   Skip validating server certificate
      --plaintext                  Use plaintext protocol without TLS

Commands:
  get derived_roles (derived_role,dr) [<id> ...]

  get export_variables (ev) [<id> ...]

  get principal_policies (principal_policy,pp) [<id> ...]

  get resource_policies (resource_policy,rp) [<id> ...]

  get schemas (schema,s) [<id> ...]

  store export (e) <path>

  store reload (r)

  delete schema (schemas,s) <id> ...

  disable policy (policies,p) <id> ...

  enable policy (policies,p) <id> ...

  put policy (policies,p) <paths> ...

  put schema (schemas,s) <paths> ...

  decisions
    Interactive decision log viewer

  audit
    View audit logs

  version
    Show cerbosctl and PDP version

Run "cerbosctl <command> --help" for more information on 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

`delete`

This command deletes the schemas with the specified ids.

Delete schemas

cerbosctl delete schemas principal.json
cerbosctl delete schema principal.json
cerbosctl delete s principal.json

Delete multiple schemas

cerbosctl delete schemas principal.json leave_request.json
cerbosctl delete schema principal.json leave_request.json
cerbosctl delete s principal.json leave_request.json

`disable`

This command disables the policies with the specified ids.

Disable policies

cerbosctl disable policies derived_roles.my_derived_roles
cerbosctl disable policy derived_roles.my_derived_roles
cerbosctl disable p derived_roles.my_derived_roles

Disable multiple policies

cerbosctl disable policies derived_roles.my_derived_roles resource.leave_request.default
cerbosctl disable policy derived_roles.my_derived_roles resource.leave_request.default
cerbosctl disable p derived_roles.my_derived_roles resource.leave_request.default

Scoped policies must have unbroken scope chains. If you’re disabling a scoped policy, make sure that its descendant policies are disabled as well.

`enable`

This command enables the policies with the specified ids.

Enable policies

cerbosctl enable policies derived_roles.my_derived_roles
cerbosctl enable policy derived_roles.my_derived_roles
cerbosctl enable p derived_roles.my_derived_roles

Enable multiple policies

cerbosctl enable policies derived_roles.my_derived_roles resource.leave_request.default
cerbosctl enable policy derived_roles.my_derived_roles resource.leave_request.default
cerbosctl enable p derived_roles.my_derived_roles resource.leave_request.default

`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.

Separately, you can filter the output using the name-regexp, version-regexp and scope-regexp flags. Each flag accepts a regular expression string. These are separate from the name and version flags above, and cannot be used with their respective counterparts.

You can include disabled policies in the results by adding --include-disabled flag.

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 derived_roles where name is my_policy or a_policy, using regular expression

cerbosctl get derived_roles --name-regexp "^(my|a)_policy\$"
cerbosctl get dr --name-regexp "^(my|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 principal_policies where version is default or v1, using regular expression

cerbosctl get principal_policies --version-regexp "(default|v1)"
cerbosctl get pp --version-regexp "(default|v1)"

List resource_policies where scope includes the substring foo, using regular expression

cerbosctl get resource_policies --scope-regexp foo
cerbosctl get rp --scope-regexp foo

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 --output=json

Get YAML

cerbosctl get derived_roles my_derived_roles --output=yaml

`hub`

Operations related to Cerbos Hub.

`epdp`

Operations related to embedded PDPs.

`list-candidates`

This command lists policies that are candidates for inclusion in the ePDP bundle. A policy is marked for inclusion if it is annotated with hub.cerbos.cloud/embedded-pdp: "true" in the metadata.annotations section of the policy. If a policy has the correct annotation, that policy and its ancestors (if it’s a scoped policy) are included the Cerbos Hub embedded PDP bundle. If none of the policies in the repo are annotated, they are all included in the bundle by default.

List candidates

cerbosctl hub epdp list-candidates ./path/to/repository

`inspect policies`

This command is to inspect policies in the store. Currently, it lists actions defined in the policies.

Inspect policies

cerbosctl inspect policies

`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 policies from a zip file

cerbosctl put policy ./dir/to/policies.zip

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

Put schemas from a zip file

cerbosctl put schema ./dir/to/schemas.zip

`store`

Trigger operations on the policy store of the PDP

`export`

Exports the policies and schemas from the store into a directory.

Export policies and schemas from the store into a directory

cerbosctl store export path/to/dir

Export policies and schemas from the store into a zip archive

cerbosctl store export path/to/archive.zip

Export policies and schemas from the store into a gzip archive

cerbosctl store export path/to/archive.gzip
cerbosctl store export path/to/archive.tar.gz

`reload`

Reloads the store.

Reload the store

cerbosctl store reload

Reload the store and wait until it finishes

cerbosctl store reload --wait`