Review Hooks

Cascade offers two review hook points in its signing pipeline for automated zone validation by user provided review scripts. These review hooks can be used to perform any validation the user requires to ensure their zone is correct at all stages, using any (third-party) tools desired.

A review script in Cascade is a custom program created by the user and configured in the zone’s policy, as shown below in Review with Script. It performs the desired validation and signals approval or rejection to Cascade via the program’s exit code. An exit code of 0 means the zone is approved, and any other exit code means the zone is rejected.

The first review hook is available after a zone is loaded by Cascade before it is signed. The second review hook is available after the zone is signed and not yet published. The review script can approve or reject a zone at either of these stages.

If a review script approves the zone, then that version of the zone will continue through the pipeline as usual. If a review script rejects the zone instead, then there are two things that can happen, depending on the configuration. Either the new version will be discarded and Cascade will simply wait for a new version of the zone, or Cascade will halt and stop doing new operations to the zone until an operator resolves the issue.

A review script receives relevant information about the zone in environment variables listed in the policy file manual. The review script then needs to use the address provided in the environment variables to fetch the zone via AXFR zone transfer and perform the required checks.

Note

When Cascade is run as a daemon with the provided systemd service unit, its file system access is limited. It only has write access to the /var/lib/cascade directory and a private /tmp directory. If a review script needs to write some state to a file, for example to store zonefiles of previously reviewed zones, it should do so in /var/lib/cascade.

If you need to write to other locations, they can be allowed with the ReadWritePaths option in the unit file. See the systemd.exec manpage for more information.

Review with Script

To configure a script as review hook, you set the review mode = "script" policy option, and specify the review script using the hook option in the [loader.review] and/or [signer.review] policy file sections.

Review scripts (or programs) are called using sh -c, so you can provide arguments to your review script, e.g.: hook = "script.sh --stage unsigned".

Here is an example configuration for automatic review:

[loader.review]
mode = "script"
hook = "review_loaded.sh"

[signer.review]
mode = "script"
hook = "review_signed.sh"

Manual Review

You can also enable manual review by setting the review mode = "manual" option under [loader.review] or [signer.review].

If no hook command is provided, but review is required, manual approval or rejection has to be performed using the CLI commands cascade zone approve or cascade zone reject.

Here is an example configuration for manual review:

[loader.review]
mode = "manual"

[signer.review]
mode = "manual"

Decide What Happens on Rejection

Cascade can do two things when a zone instance is rejected: halt or discard. This is configured through the on-reject field under [loader.review] or [signer.review].

If it is configured to "discard", it will simply go back to the idle state as if the loading or signing operation didn’t happen. This is the most fault-tolerant option.

If it is instead set to "halt" then Cascade will stop doing any operations to the zone. This allows the operator to investigate the issue before Cascade continues. If the zone should be accepted anyway, the cascade zone override command can be used to override the previous rejection. If the rejection was correct, the cascade zone reset command can be used to discard the loaded instance.

[loader.review]
mode = "script"
hook = "review_loaded.sh"
on-reject = "halt"

Example

In this example we will use validns to validate the unsigned zone, and dnssec-verify to validate the signed zone.

To do this, we need to write a shell script that fetches the zone using AXFR and performs the relevant checks. Let’s save the following review script[1] as /usr/local/bin/cascade-review.sh:

#!/usr/bin/env sh

set -e

logger -p daemon.notice -t cascade "Validating ${CASCADE_ZONE} of serial ${CASCADE_SERIAL} from ${CASCADE_SERVER}"

# Using `validns` to check the unsigned zone
# and `dnssec-verify` to check the signed zone
# Unfortunately, dig logs some errors on standard output... Nothing to do there
dig @${CASCADE_SERVER_IP} -p ${CASCADE_SERVER_PORT} "${CASCADE_ZONE}" AXFR | \
    if [ "$1" = "unsigned" ]; then
        # validns does not handle Ed25519
        validns -z "${CASCADE_ZONE}" -p all -
    else
        dnssec-verify -q -o "${CASCADE_ZONE}" /dev/stdin
    fi

Added in version 0.1.0-alpha2: Environment variables CASCADE_SERVER_IP and CASCADE_SERVER_PORT.

Next, we update the zone’s policy to use the review script for both stages:

# Keep the other settings in the policy as is ...

[loader.review]
mode = "script"
hook = "/usr/local/bin/cascade-review.sh unsigned"

[signer.review]
mode = "script"
hook = "/usr/local/bin/cascade-review.sh"

Finally, we need to reload the policy with cascade policy reload to apply the policy changes.