cerbosctl
This documentation is for a previous version of Cerbos. Choose 0.39.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.
docker run -it ghcr.io/cerbos/cerbosctl:0.36.0 \
--server=192.168.1.10:3593 \
--username=user \
--password=password \
get rp
OS | Arch | Bundle |
---|---|---|
Linux |
x86-64 |
|
Linux |
arm64 |
|
MacOS |
universal |
|
MacOS |
x86-64 |
|
MacOS |
arm64 |
|
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.
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
delete
This command deletes the schemas with the specified ids.
cerbosctl delete schemas principal.json cerbosctl delete schema principal.json cerbosctl delete s principal.json
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.
cerbosctl disable policies derived_roles.my_derived_roles cerbosctl disable policy derived_roles.my_derived_roles cerbosctl disable p derived_roles.my_derived_roles
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.
cerbosctl enable policies derived_roles.my_derived_roles cerbosctl enable policy derived_roles.my_derived_roles cerbosctl enable p derived_roles.my_derived_roles
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.
cerbosctl get derived_roles cerbosctl get derived_role cerbosctl get dr
cerbosctl get principal_policies cerbosctl get principal_policy cerbosctl get pp
cerbosctl get resource_policies cerbosctl get resource_policy cerbosctl get rp
name
is my_policy
or a_policy
cerbosctl get derived_roles --name my_policy,a_policy cerbosctl get dr --name my_policy,a_policy
name
is my_policy
or a_policy
, using regular expressioncerbosctl get derived_roles --name-regexp "^(my|a)_policy\$" cerbosctl get dr --name-regexp "^(my|a)_policy\$"
version
is default
or v1
cerbosctl get principal_policies --version default,v1 cerbosctl get pp --version default,v1
version
is default
or v1
, using regular expressioncerbosctl get principal_policies --version-regexp "(default|v1)" cerbosctl get pp --version-regexp "(default|v1)"
scope
includes the substring foo
, using regular expressioncerbosctl get resource_policies --scope-regexp foo cerbosctl get rp --scope-regexp foo
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
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
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
cerbosctl get derived_roles my_derived_roles --output=json
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.
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.
cerbosctl inspect policies
put
This command puts the given policies or schemas to the configured policy repository.
cerbosctl put policies ./path/to/policy.yaml cerbosctl put policy ./path/to/policy.yaml cerbosctl put p ./path/to/policy.yaml
cerbosctl put policy ./path/to/policy.yaml ./path/to/other/policy.yaml
cerbosctl put policy ./dir/to/policies ./other/dir/to/policies
cerbosctl put policy --recursive ./dir/to/policies cerbosctl put policy -R ./dir/to/policies
cerbosctl put policy ./dir/to/policies.zip
cerbosctl put schemas ./path/to/schema.json cerbosctl put schema ./path/to/schema.json cerbosctl put s ./path/to/schema.json
cerbosctl put schema ./path/to/schema.json ./path/to/other/schema.json
cerbosctl put schema ./dir/to/schemas ./other/dir/to/schemas
cerbosctl put schema --recursive ./dir/to/schemas cerbosctl put schema -R ./dir/to/schemas
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.
cerbosctl store export path/to/dir
cerbosctl store export path/to/archive.zip
cerbosctl store export path/to/archive.gzip cerbosctl store export path/to/archive.tar.gz