Validating and testing policies
Validating policies
You can use the Cerbos compiler to make sure that your policies are valid before pushing them to a production Cerbos instance. We recommend setting up a git hook or a CI step to run the Cerbos compiler before you push any policy changes to production.
docker run -i -t -v /path/to/policy/dir:/policies ghcr.io/cerbos/cerbos:0.7.0 compile /policies
Example: GitHub Actions workflow
-
Create a directory named
.github/actions/cerbos
at the root of your repository -
Create a file named
.github/actions/cerbos/actions.yaml
containing the following:--- name: 'cerbos' description: 'Cerbos compile' inputs: policyDir: description: 'Policy directory' required: true runs: using: 'docker' image: 'docker://ghcr.io/cerbos/cerbos:0.7.0' args: - 'compile' - ${{ inputs.policyDir }}
-
Now you can add a job to your workflow definition that references the action created above. For example, the following workflow runs the Cerbos compile step on every pull request:
--- name: PR Check on: pull_request: branches: - main jobs: cerbosCheck: name: Check Cerbos policies runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v2 - name: Run Cerbos compile uses: ./.github/actions/cerbos id: cerbos with: policyDir: cerbos/policies
See the Cerbos REST demo respoisitory for an example of a similar GitHub Action being used to check the policies on each pull request. |
Testing policies
You can write optional tests for policies and run them as part of the compilation stage to make sure that the policies do exactly what you expect.
Tests are defined using the familiar YAML format as well. Make sure that your tests are in a separate directory from the policies to avoid confusion. We recommend storing them in a top-level directory named tests
. A test file must have _test
suffix in the name and one of the following file extensions: 'yaml', 'yml', or 'json'. For example, album_test.yml
, album_test.yaml
or album_test.json
.
---
name: AlbumObjectTestSuite (1)
description: Tests for verifying the album:object resource policy (2)
resources: (3)
alicia_album:
kind: "album:object",
attr:
owner: aliciaID,
id: XX125,
public: false,
flagged: false
principals: (4)
bradley:
id: bradleyID
roles:
- user
alicia:
id: aliciaID
roles:
- user
tests: (5)
- name: Alicia tries to view her own private album (6)
input: (7)
requestId: "test"
actions: ["view", "delete"]
resource: "alicia_album"
expected: (8)
- principal: alicia
actions:
view: EFFECT_ALLOW
delete: EFFECT_ALLOW
- principal: bradley
actions:
view: EFFECT_DENY
delete: EFFECT_DENY
1 | Name of the test suite |
2 | Description of the test suite |
3 | Map of resources. A key is a string that can be used to refer to the associated resource |
4 | Map of principals. A key is a string that can be used to refer to the associated principal |
5 | List of tests in this suite |
6 | Name of the test |
7 | Input to the policy engine |
8 | List of outcomes expected for a specified principal and a given action. |
Sharing test fixtures
It is possible to share principals and resources between test suites stored in the same directory. Create a testdata
directory in the directory containing your test suite files, then define shared resources and principals in testdata\resources.yml
and testdata\principals.yml
respectively (yaml
and json
extensions are also supported).
tests ├── album_object_test.yaml ├── gallery_object_test.yaml ├── slideshow_object_test.yaml └── testdata ├── principals.yaml └── resources.yaml
testdata\principals.yml
---
principals:
john:
id: johnID
roles:
- user
- moderator
testdata\resources.yml
---
resources:
alicia_album:
kind: "album:object",
attr:
owner: aliciaID,
id: XX125,
public: false,
flagged: false
YAML anchors and overrides are a great way to reduce repetition and reuse definitions in test cases. For example, the following definitions are equivalent:
|
Running tests
To run the tests, provide the path to the tests directory using the --tests
flag.
docker run -i -t \
-v /path/to/policy/dir:/policies \
-v /path/to/test/dir:/tests \
ghcr.io/cerbos/cerbos:0.7.0 compile --tests=/tests /policies
Machine readable output can be produced by passing --format=json
flag to the command.
By default, all discovered tests are run. To run just some of the tests, provide a regular expression that matches the test using the --run
flag.
docker run -i -t \
-v /path/to/policy/dir:/policies \
-v /path/to/test/dir:/tests \
ghcr.io/cerbos/cerbos:0.7.0 compile --tests=/tests --run=Delete /policies
You can also skip entire suites or individual tests in a suite by adding skip: true
to the test definition.
---
name: AlbumObjectTestSuite
description: Tests for verifying the album:object resource policy
tests:
- name: View private album
skip: true
skipReason: "Policy under review"
input:
requestId: "test01"
actions: ["view"]
resource: alicia_private_album
expected:
- principal: alicia
actions:
view: EFFECT_ALLOW