My deploy hook command is rejected with "Command blocked at runtime: contains dangerous shell metacharacters" — what's allowed?

[fabriziosalmi]

I tried to save a deploy hook like nginx -s reload && systemctl reload haproxy (or anything with &&, ;, a pipe, or a sub-shell) and CertMate refuses to save it with contains dangerous shell metacharacters. The hook field used to accept this in older versions. What is the rule now and how do I run a multi-step command?

[fabriziosalmi]

Deploy hooks run on the CertMate host with the privileges of the CertMate process. A naïve shell=True would mean that anyone who can write to the settings (any admin / valid bearer token) can run arbitrary code on the host. v2.4.0 tightened the validator after a security review; v2.4.1 relaxed one specific allowance ($CERTMATE_* env var substitution). The current rules live in modules/core/deployer.py and apply at save time and at runtime.

Blocked patterns (rejected with contains dangerous shell metacharacters). The regex blocks:

Pattern	Why
` ` (backticks)	Sub-shell
$(…)	Sub-shell
${…}	Parameter expansion (except $CERTMATE_*, see below)
&&, ||	Logical chaining
;	Statement separator
\r, \n	Treated as ; by sh -c
> /…	Redirect to absolute path
<<	Here-doc
eval, source, . /…	Interpreter built-ins

Blocked references (rejected with references sensitive CertMate files). Even without shell metacharacters, the command cannot mention settings.json, api_bearer_token, client_secret, vault_token, or .env (case-insensitive).

Allowed.

• A single absolute-path executable plus arguments: /usr/sbin/nginx -s reload
• The whitelisted environment variables $CERTMATE_* and ${CERTMATE_*}. The hook runner injects these for you: $CERTMATE_CERT_PATH, $CERTMATE_KEY_PATH, $CERTMATE_DOMAIN, etc. These are substituted before the dangerous-pattern check, so referencing them is fine.
• Up to 1024 characters per command.

Running multi-step commands. Two clean options:

1. Write a shell script on the host, point the hook at it.

   # /etc/certmate/reload-edge.sh on the host
   #!/usr/bin/env bash
   set -euo pipefail
   nginx -s reload
   systemctl reload haproxy

   chmod 0750 /etc/certmate/reload-edge.sh

   Hook command: /etc/certmate/reload-edge.sh. The validator does not care what is inside the script; it only cares about the command string CertMate runs.

2. Use the multi-hook feature. Configure two separate deploy hooks on the same certificate, each with one command. CertMate runs them sequentially in the order saved. Each individual command must pass the validator on its own.

Migration note. If you upgraded from v2.3.x to v2.4.0+ and an existing hook stopped working at runtime even though it saved fine on the older version, the runtime validator now catches it. Switch to the script approach above.