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 Configuration. 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 that version of the zone will be halted and not proceed further. However, a subsequently loaded version of the zone will be processed and traverse the pipeline as usual, unless it too is rejected by a review script.

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.

Configuration

To configure a review hook, you set the review required = true policy option, and specify the review script using the cmd-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.: cmd-hook = "script.sh --stage unsigned".

Manual Review

You can also enable manual review by setting the review required = true option under [loader.review] or [signer.review] without providing a cmd-hook command.

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.

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]
required = true
cmd-hook = "/usr/local/bin/cascade-review.sh unsigned"

[signer.review]
required = true
cmd-hook = "/usr/local/bin/cascade-review.sh"

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