From 510715cef0d70ba81069e3032f03809f6ec99502 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20Cort=C3=A9s=20Cano?= <38475681+TrapoSAMA@users.noreply.github.com> Date: Sun, 19 Jul 2026 04:52:50 -0400 Subject: [PATCH] Harden optional mailbox hook scripts (#1080) - backport only the generic hardening of the existing optional Maildir and Dovecot hook examples - validate the documented hook argument contracts before constructing filesystem paths - quote filesystem operations, replace legacy shell constructs and propagate command failures - make domain and mailbox deletion safely retryable when their target is already absent - update the Dovecot password example for Dovecot 2.3.19 or newer, with a Dovecot 2.4 setting note The hooks remain optional and disabled by default. Administrators must review `basedir`, `trashbase` and the service account used by sudo. The mail-crypt password example now requires Dovecot 2.3.19 or newer. --- ADDITIONS/README.md | 23 ++- ADDITIONS/postfixadmin-domain-postdeletion.sh | 107 +++++++------ .../postfixadmin-mailbox-postcreation.sh | 112 +++++++------- .../postfixadmin-mailbox-postdeletion.sh | 142 ++++++++++-------- .../postfixadmin-mailbox-postpassword.sh | 51 +++++-- 5 files changed, 256 insertions(+), 179 deletions(-) diff --git a/ADDITIONS/README.md b/ADDITIONS/README.md index 6e0238ab..d23043b0 100644 --- a/ADDITIONS/README.md +++ b/ADDITIONS/README.md @@ -48,22 +48,33 @@ See also : https://github.com/postfixadmin/postfixadmin/tree/master/ADDITIONS/s by George Vieira Deletes all unused mailboxes -## Example mailbox / domain scripts for Postfixadmin +## Example mailbox / domain scripts for PostfixAdmin - postfixadmin-mailbox-postcreation.sh - postfixadmin-mailbox-postdeletion.sh - postfixadmin-domain-postdeletion.sh + by Troels Arvin -Examples of scripts relevant to the optional +Examples relevant to the optional `mailbox_postcreation_script`, +`mailbox_postdeletion_script` and `domain_postdeletion_script` configuration +options. +Review and adjust `basedir` and `trashbase` before installing the scripts. Run +them as the account that owns the Maildirs, not as root. If sudo is required, +grant the web server permission to run only the exact script as that account; +never grant access to a generic `mv` command. Install privileged hooks in a +root-owned directory that is not writable by the web server or mail users. -$CONF['mailbox_postcreation_script'], -$CONF['mailbox_postdeletion_script'] and -$CONF['domain_postdeletion_script'] configuration options. +The scripts validate the argument contracts documented in `config.inc.php`. +Deletion is idempotent: an already absent Maildir is reported as a successful +no-op so an interrupted hook can be retried safely. + +`postfixadmin-mailbox-postpassword.sh` is an example for Dovecot mail-crypt. It +requires Dovecot 2.3.19 or newer. Its default private-password setting name is +for Dovecot 2.3; follow the comment in the script when using Dovecot 2.4. ## Cyrus Quota Usage See https://github.com/o-m-d/cyrus-quotausage-to-pfa - diff --git a/ADDITIONS/postfixadmin-domain-postdeletion.sh b/ADDITIONS/postfixadmin-domain-postdeletion.sh index a7a94b19..0497d593 100644 --- a/ADDITIONS/postfixadmin-domain-postdeletion.sh +++ b/ADDITIONS/postfixadmin-domain-postdeletion.sh @@ -1,62 +1,75 @@ #!/bin/sh -# Example script for removing a Maildir domain top-level folder -# from a Courier-IMAP virtual mail hierarchy. +# Example script for moving a deleted Maildir domain to a recovery directory. +# PostfixAdmin passes the domain as argument 1. -# The script only looks at argument 1, assuming that it -# indicates the relative name of a domain, such as -# "somedomain.com". If $basedir/somedomain.com exists, it will -# be removed. +# Run this script as the user that owns the Maildirs. If the web server needs +# sudo, restrict the sudoers rule to that user and this exact script. Do not +# grant a generic mv command. -# The script will not actually delete the directory. It moves it -# to a special directory which may once in a while be cleaned up -# by the system administrator. - -# This script should be run as the user which owns the maildirs. If -# the script is actually run by the apache user (e.g. through PHP), -# then you could use "sudo" to grant apache the rights to run -# this script as the relevant user. -# Assume this script has been saved as -# /usr/local/bin/postfixadmin-domain-postdeletion.sh and has been -# made executable. Now, an example /etc/sudoers line: -# apache ALL=(courier) NOPASSWD: /usr/local/bin/postfixadmin-domain-postdeletion.sh -# The line states that the apache user may run the script as the -# user "courier" without providing a password. - - -# Change this to where you keep your virtual mail users' maildirs. +# Change these paths to match the virtual mail layout. basedir=/var/spool/maildirs - -# Change this to where you would like deleted maildirs to reside. trashbase=/var/spool/deleted-maildirs -if [ `echo $1 | fgrep '..'` ]; then - echo "First argument contained a double-dot sequence; bailing out." +fail() +{ + printf '%s\n' "$0: $*" >&2 exit 1 -fi +} -if [ ! -e "$trashbase" ]; then - echo "trashbase '$trashbase' does not exist; bailing out." - exit 1 -fi +valid_domain() +{ + candidate=$1 -trashdir="${trashbase}/`date +%F_%T`_$1" -domaindir="${basedir}/$1" + [ -n "$candidate" ] && [ "${#candidate}" -le 253 ] || return 1 + case "$candidate" in + -*|.*|*.|*..*|*/*|*\\*|*[!A-Za-z0-9.-]*) return 1 ;; + esac + + remainder=$candidate + while :; do + case "$remainder" in + *.*) + label=${remainder%%.*} + remainder=${remainder#*.} + ;; + *) + label=$remainder + remainder= + ;; + esac + + [ -n "$label" ] && [ "${#label}" -le 63 ] || return 1 + case "$label" in + -*|*-) return 1 ;; + esac + [ -n "$remainder" ] || break + done +} + +[ "$#" -eq 1 ] || fail "expected exactly one domain argument" +domain=$1 +valid_domain "$domain" || fail "invalid domain '$domain'" + +[ -d "$basedir" ] || fail "basedir '$basedir' is not a directory" +[ -d "$trashbase" ] || fail "trashbase '$trashbase' is not a directory" + +domaindir="${basedir%/}/$domain" +[ "$domaindir" != "${trashbase%/}" ] || fail "refusing to move trashbase itself" if [ ! -e "$domaindir" ]; then - echo "Directory '$domaindir' does not exits; nothing to do." - exit 0; + printf '%s\n' "$0: directory '$domaindir' does not exist; nothing to do." + exit 0 fi -if [ ! -d "$domaindir" ]; then - echo "'$domaindir' is not a directory; bailing out." - exit 1 -fi -if [ -e "$trashdir" ]; then - echo "Directory '$trashdir' already exits; bailing out." - exit 1; +[ -d "$domaindir" ] || fail "'$domaindir' is not a directory" + +timestamp=$(date '+%Y%m%dT%H%M%S') || fail "could not generate a timestamp" +trashdir="${trashbase%/}/${timestamp}_$$_${domain}" +[ ! -e "$trashdir" ] || fail "trash destination '$trashdir' already exists" + +if ! mv "$domaindir" "$trashdir"; then + fail "could not move '$domaindir' to '$trashdir'" fi -mv $domaindir $trashdir - -exit $? - +printf '%s\n' "$0: moved '$domaindir' to '$trashdir'." +exit 0 diff --git a/ADDITIONS/postfixadmin-mailbox-postcreation.sh b/ADDITIONS/postfixadmin-mailbox-postcreation.sh index 472606aa..2ec1797a 100644 --- a/ADDITIONS/postfixadmin-mailbox-postcreation.sh +++ b/ADDITIONS/postfixadmin-mailbox-postcreation.sh @@ -1,71 +1,79 @@ #!/bin/sh # Example script for adding a Maildir to a Courier-IMAP virtual mail -# hierarchy. +# hierarchy. PostfixAdmin passes username, domain, Maildir and quota as +# arguments 1 through 4. This example uses only the relative Maildir path. -# The script only looks at argument 3, assuming that it -# indicates the relative name of a maildir, such as -# "somedomain.com/peter/". +# Run this script as the user that owns the Maildirs. If the web server needs +# sudo, restrict the sudoers rule to that user and this exact script. -# This script should be run as the user which owns the maildirs. If -# the script is actually run by the apache user (e.g. through PHP), -# then you could use "sudo" to grant apache the rights to run -# this script as the relevant user. -# Assume this script has been saved as -# /usr/local/bin/postfixadmin-mailbox-postcreation.sh and has been -# made executable. Now, an example /etc/sudoers line: -# apache ALL=(courier) NOPASSWD: /usr/local/bin/postfixadmin-mailbox-postcreation.sh -# The line states that the apache user may run the script as the -# user "courier" without providing a password. - - -# Change this to where you keep your virtual mail users' maildirs. +# Change this to where you keep your virtual mail users' Maildirs. basedir=/var/spool/maildirs -if [ ! -e "$basedir" ]; then - echo "$0: basedir '$basedir' does not exist; bailing out." +fail() +{ + printf '%s\n' "$0: $*" >&2 exit 1 -fi +} -if [ `echo $3 | fgrep '..'` ]; then - echo "$0: An argument contained a double-dot sequence; bailing out." - exit 1 -fi +valid_relative_maildir() +{ + candidate=${1%/} + + [ -n "$candidate" ] || return 1 + case "$candidate" in + /*|*\\*|*//*|*[![:print:]]*) return 1 ;; + esac + + remainder=$candidate + while :; do + case "$remainder" in + */*) + component=${remainder%%/*} + remainder=${remainder#*/} + ;; + *) + component=$remainder + remainder= + ;; + esac + + case "$component" in + ''|.|..) return 1 ;; + esac + [ -n "$remainder" ] || break + done +} + +[ "$#" -eq 4 ] || fail "expected username, domain, Maildir and quota arguments" +relative_maildir=${3%/} +valid_relative_maildir "$relative_maildir" || fail "invalid relative Maildir '$3'" + +[ -d "$basedir" ] || fail "basedir '$basedir' is not a directory" + +maildir="${basedir%/}/$relative_maildir" +parent=$(dirname "$maildir") || fail "could not determine the parent directory" -maildir="${basedir}/$3" -parent=`dirname "$maildir"` if [ ! -d "$parent" ]; then - if [ -e "$parent" ]; then - echo "$0: strange - directory '$parent' exists, but is not a directory; bailing out." - exit 1 - else - mkdir -p "${parent}" - if [ $? -ne 0 ]; then - echo "$0: mkdir -p '$parent' returned non-zero; bailing out." - exit 1 - fi + [ ! -e "$parent" ] || fail "'$parent' exists but is not a directory" + if ! mkdir -p "$parent"; then + fail "could not create parent directory '$parent'" fi fi -if [ -e "$maildir" ]; then - echo "$0: Directory '$maildir' already exists! bailing out" - exit 1 +[ ! -e "$maildir" ] || fail "Maildir '$maildir' already exists" + +if maildirmake_path=$(command -v maildirmake 2>/dev/null); then + : +elif maildirmake_path=$(command -v courier-maildirmake 2>/dev/null); then + : +else + fail "could not find maildirmake or courier-maildirmake in PATH" fi - -# try looking for maildirmake ... -MDM=`which maildirmake || which courier-maildirmake` - -if [ "x${MDM}" = "x" ]; then - echo "Couldn't find maildirmake or courier-maildirmake in your PATH etc (via which)" >/dev/stderr - exit 1 -fi - -"${MDM}" "${maildir}" - -if [ ! -d "$maildir" ]; then - echo "$0: maildirmake didn't produce a directory; bailing out." - exit 1 +if ! "$maildirmake_path" "$maildir"; then + fail "maildirmake failed for '$maildir'" fi +[ -d "$maildir" ] || fail "maildirmake did not create '$maildir'" exit 0 diff --git a/ADDITIONS/postfixadmin-mailbox-postdeletion.sh b/ADDITIONS/postfixadmin-mailbox-postdeletion.sh index 7c903e70..8f52da64 100644 --- a/ADDITIONS/postfixadmin-mailbox-postdeletion.sh +++ b/ADDITIONS/postfixadmin-mailbox-postdeletion.sh @@ -1,77 +1,95 @@ #!/bin/sh -# Example script for removing a Maildir from a Courier-IMAP virtual mail -# hierarchy. +# Example script for moving a deleted Maildir to a recovery directory. +# PostfixAdmin passes username and domain as arguments 1 and 2. -# The script looks at arguments 1 and 2, assuming that they -# indicate username and domain, respectively. +# Run this script as the user that owns the Maildirs. If the web server needs +# sudo, restrict the sudoers rule to that user and this exact script. Do not +# grant a generic mv command. -# The script will not actually delete the maildir. It moves it -# to a special directory which may once in a while be cleaned up -# by the system administrator. - -# This script should be run as the user which owns the maildirs. If -# the script is actually run by the apache user (e.g. through PHP), -# then you could use "sudo" to grant apache the rights to run -# this script as the relevant user. -# Assume this script has been saved as -# /usr/local/bin/postfixadmin-mailbox-postdeletion.sh and has been -# made executable. Now, an example /etc/sudoers line: -# apache ALL=(courier) NOPASSWD: /usr/local/bin/postfixadmin-mailbox-postdeletion.sh -# The line states that the apache user may run the script as the -# user "courier" without providing a password. - - -# Change this to where you keep your virtual mail users' maildirs. +# Change these paths to match the virtual mail layout. basedir=/var/spool/maildirs - -# Change this to where you would like deleted maildirs to reside. trashbase=/var/spool/deleted-maildirs - -if [ ! -e "$trashbase" ]; then - echo "trashbase '$trashbase' does not exist; bailing out." +fail() +{ + printf '%s\n' "$0: $*" >&2 exit 1 +} + +valid_domain() +{ + candidate=$1 + + [ -n "$candidate" ] && [ "${#candidate}" -le 253 ] || return 1 + case "$candidate" in + -*|.*|*.|*..*|*/*|*\\*|*[!A-Za-z0-9.-]*) return 1 ;; + esac + + remainder=$candidate + while :; do + case "$remainder" in + *.*) + label=${remainder%%.*} + remainder=${remainder#*.} + ;; + *) + label=$remainder + remainder= + ;; + esac + + [ -n "$label" ] && [ "${#label}" -le 63 ] || return 1 + case "$label" in + -*|*-) return 1 ;; + esac + [ -n "$remainder" ] || break + done +} + +valid_mailbox_component() +{ + case "$1" in + ''|.|..|*/*|*\\*|*[![:print:]]*) return 1 ;; + esac +} + +[ "$#" -eq 2 ] || fail "expected username and domain arguments" +username=$1 +domain=$2 +valid_domain "$domain" || fail "invalid domain '$domain'" + +case "$username" in + *@"$domain") subdir=${username%"@$domain"} ;; + *) fail "username '$username' does not belong to domain '$domain'" ;; +esac +valid_mailbox_component "$subdir" || fail "unsafe mailbox directory component" + +[ -d "$basedir" ] || fail "basedir '$basedir' is not a directory" +[ -d "$trashbase" ] || fail "trashbase '$trashbase' is not a directory" + +maildir="${basedir%/}/$domain/$subdir" +if [ ! -e "$maildir" ]; then + printf '%s\n' "$0: Maildir '$maildir' does not exist; nothing to do." + exit 0 fi +[ -d "$maildir" ] || fail "'$maildir' is not a directory" -if [ `echo $1 | fgrep '..'` ]; then - echo "First argument contained a double-dot sequence; bailing out." - exit 1 -fi -if [ `echo $2 | fgrep '..'` ]; then - echo "First argument contained a double-dot sequence; bailing out." - exit 1 -fi - -subdir=`echo "$1" | sed 's/@.*//'` - -maildir="${basedir}/$2/${subdir}" -trashdir="${trashbase}/$2/`date +%F_%T`_${subdir}" - -parent=`dirname "$trashdir"` -if [ ! -d "$parent" ]; then - if [ -e "$parent" ]; then - echo "Strainge - directory '$parent' exists, but is not a directory." - echo "Bailing out." - exit 1 - else - mkdir -p "$parent" - if [ $? -ne 0 ]; then - echo "mkdir -p '$parent' returned non-zero; bailing out." - exit 1 - fi +trashparent="${trashbase%/}/$domain" +if [ ! -d "$trashparent" ]; then + [ ! -e "$trashparent" ] || fail "'$trashparent' exists but is not a directory" + if ! mkdir -p "$trashparent"; then + fail "could not create trash directory '$trashparent'" fi fi -if [ ! -e "$maildir" ]; then - echo "maildir '$maildir' does not exist; nothing to do." - exit 1 -fi -if [ -e "$trashdir" ]; then - echo "trashdir '$trashdir' already exists; bailing out." - exit 1 +timestamp=$(date '+%Y%m%dT%H%M%S') || fail "could not generate a timestamp" +trashdir="${trashparent}/${timestamp}_$$_${subdir}" +[ ! -e "$trashdir" ] || fail "trash destination '$trashdir' already exists" + +if ! mv "$maildir" "$trashdir"; then + fail "could not move '$maildir' to '$trashdir'" fi -mv $maildir $trashdir - -exit $? +printf '%s\n' "$0: moved '$maildir' to '$trashdir'." +exit 0 diff --git a/ADDITIONS/postfixadmin-mailbox-postpassword.sh b/ADDITIONS/postfixadmin-mailbox-postpassword.sh index b6c6e77d..f1d29c3f 100644 --- a/ADDITIONS/postfixadmin-mailbox-postpassword.sh +++ b/ADDITIONS/postfixadmin-mailbox-postpassword.sh @@ -1,19 +1,46 @@ #!/bin/bash -# Example script for dovecot mail-crypt-plugin -# https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/ +# Example script for Dovecot's mail-crypt plugin. +# Requires Dovecot 2.3.19 or newer for the -O/-N prompt behaviour. +# https://doc.dovecot.org/2.3/configuration_manual/mail_crypt_plugin/ -IFS= read -r -d $'\0' OLD_PASSWORD -IFS= read -r -d $'\0' NEW_PASSWORD +# Dovecot 2.3 setting name. For Dovecot 2.4, use: +# private_password_setting=crypt_user_key_password +private_password_setting=plugin/mail_crypt_private_password -# New user -if [ -z "$OLD_PASSWORD" ]; then - OLD_PASSWORD="$(openssl rand -hex 16)" - doveadm -o plugin/mail_crypt_private_password="$OLD_PASSWORD" mailbox cryptokey generate -u "$1" -U +fail() +{ + printf '%s\n' "$0: $*" >&2 + exit 1 +} + +[[ $# -eq 2 ]] || fail "expected username and domain arguments" +username=$1 +domain=$2 +[[ -n $username && -n $domain && $username == *@"$domain" ]] || fail "invalid username or domain" + +IFS= read -r -d '' old_password || fail "could not read the NUL-terminated old password" +IFS= read -r -d '' new_password || fail "could not read the NUL-terminated new password" +[[ -n $new_password ]] || fail "new password must not be empty" + +openssl_path=$(command -v openssl 2>/dev/null) || fail "could not find openssl in PATH" +doveadm_path=$(command -v doveadm 2>/dev/null) || fail "could not find doveadm in PATH" + +if [[ -z $old_password ]]; then + old_password=$("$openssl_path" rand -hex 16) || fail "could not generate a temporary password" + [[ -n $old_password ]] || fail "openssl returned an empty temporary password" + + if ! "$doveadm_path" -o "$private_password_setting=$old_password" \ + mailbox cryptokey generate -u "$username" -U; then + fail "could not generate the mailbox cryptokey" + fi fi -# If you're using dovecot >= 2.3.19, try this instead (See: https://github.com/postfixadmin/postfixadmin/issues/646) -# printf "%s\n%s\n" "$OLD_PASSWORD" "$NEW_PASSWORD" "$NEW_PASSWORD" | doveadm mailbox cryptokey password -u "$1" -N -O +# Since Dovecot 2.3.19, -O asks for the old password and -N asks for the new +# password twice. Keep passwords on stdin instead of command-line arguments. +if ! printf '%s\n%s\n%s\n' "$old_password" "$new_password" "$new_password" | \ + "$doveadm_path" mailbox cryptokey password -u "$username" -O -N; then + fail "could not update the mailbox cryptokey password" +fi -# Password change -printf "%s\n%s\n" "$OLD_PASSWORD" "$NEW_PASSWORD" | doveadm mailbox cryptokey password -u "$1" -N -O "" +exit 0