75. pepsi-whitelist¶
Manage the sender whitelist by hand.
75.1. Role¶
pepsi-whitelist manages the pepsi.whitelist table — the named sets of
sender patterns that mark a message as trusted (non-spam). It connects through the
shared [pepsi-postgres] section and reads the optional [pepsi-whitelist]
section. The same table is read by pepsi-stage-check-whitelist and populated
automatically by pepsi-stage-auto-whitelist; this tool lets an administrator
add, list and remove entries directly, and lets each user seed a whitelist of
their own from the mail they have already sent. It is not a stage.
Reference: pepsi-whitelist(1).
Unlike the other operator tools, which simply become the pepsi service
account when started as root, this one keeps the invoking identity and
switches only its effective ids around each database call: import --user
and --all-users need root in order to scan another user’s mailbox under
that user’s credentials.
75.2. Features¶
Patterns checked before they are stored:
add,add-listandimportask PostgreSQL to compile every pattern first and refuse one that does not (animportthen writes nothing).add — insert an entry: a
whitelist_namegroup and awhitelist_regex(a POSIX extended regular expression, stored verbatim — matched case-insensitively by the check stage against the addr-spec parsed out of theFrom:header, never against the raw header text).--no-dkim-requiredclears the per-rowdkim_requiredflag (set by default);--dmarc-requiredsetsdmarc_required(clear by default: the match then needs an aligned DMARC pass, aligned SPF included — the level for a correspondent whose domain does not sign);--signature-requiredsetssignature_required(clear by default);--sealer DOMAINadditionally requires that the message’s validated ARC chain was sealed by that domain. Idempotent: re-adding an existing(name, match field, regex)entry is a no-op and leaves its flags unchanged.add-list / remove-list — the same, for a mailing list identified by the
List-Idthat its postings carry, rather than by aFrom:pattern; theList-Idmatches every posting, whoever wrote it.--patterntreats the argument as a POSIX ERE instead of one exact identifier. AList-Idis a header anybody can copy, so pair it with--sealer.list — list entries ordered by name, match field and regex, optionally restricted to a single
whitelist_name, as a table or--json.remove — delete the entry identified by its exact
whitelist_nameandwhitelist_regex.import — seed a whitelist from a mailbox: every message whose
From:/Sender:is at a local domain and whose header block carries no delivery-trace field (Received:,Return-Path:,Delivered-To:,X-Original-To:) is one that the user sent, so itsTo:/Cc:/Bcc:addresses are people they correspond with and are added as entries. Received mail is ignored (whitelisting whoever wrote to you would defeat the purpose), as are recipients at a local domain. Reads mbox, Maildir (including its sub-folders), IMAP (--imap, with--imap-user/--imap-password-file) and Dovecot’s own formats (--doveadm,--doveadm-path); only header blocks are read, never bodies.--dry-runreports what would be added and changes nothing;--own-addressnarrows what counts as mail you sent;--max-entries/--max-messagesbound the run; and--user/--all-userslet root seed other accounts, each into its own namespace, unless--nameis also given; then the correspondents of every scanned account go into that one list.--include-deliveredalso reads received mail and is marked unsafe for the obvious reason: a forgedFrom:would then seed the whitelist.import, mailing lists — also propose every list whose postings the user has answered, as one exact
list-idrow each. A list qualifies when a message that the user sent answers (In-Reply-To:) one of its postings in the scanned mailbox. Like wildcards, each list is confirmed on its own on a terminal, all are accepted with--yesand all declined without a terminal. Receiving list mail alone proposes nothing.import –auto-wildcard — offer to replace the individual addresses at a domain with one
*@domainentry once at leastWILDCARD_THRESHOLD(10, overridable per run with--threshold) distinct addresses were seen there. Proposals are confirmed one at a time on a terminal, all accepted with--yes, and all declined when there is no terminal — an unattended run never widens a whitelist to a whole domain by itself. Public e-mail hosters (HOSTERS_FILE,/usr/share/pepsi/hosters.txt, overridable with--hostersand defeatable with--no-hosters) are never proposed, however many correspondents a user has there: “everyone atgmail.com” is not a set of people the user knows, and it would let every spammer with a free account bypass the payment gate. Their addresses are still imported individually.
75.3. Whitelist namespaces¶
A whitelist_name is either global (one segment, e.g. correspondents —
the operator’s) or owned by a user: <login>/<segment>, e.g.
alice/correspondents. Segments are letters, digits, _, . and -
(a dot because alice.smith is an ordinary login); the separator is /
because no POSIX-ish system allows it in a login name, whereas -, _,
. and a trailing $ all are. A segment made of nothing but dots is
refused, so .. — and therefore any relative path — is unrepresentable.
Ordinary users may read and write only their own namespace, keyed on the real
uid’s passwd login (never $USER or an argument). That includes list: the
shared whitelist records who the organisation corresponds with, and a program that every
user may run must not print it. root and the pepsi/pepsi-owner/
pepsi-whitelist accounts may manage everything.
For a per-user whitelist to matter, a check stage must consult it — see the
{localpart} / {login} placeholders in
pepsi-stage-check-whitelist’s WHITELIST_NAME.
75.4. Privilege model¶
Reaching the shared table needs a database identity that ordinary users lack;
reading a mailbox needs theirs. So pepsi-whitelist is installed setuid
pepsi-whitelist (mode 4755) and immediately lowers its effective ids to the
invoking user, raising them again only for the few milliseconds in which it
talks to PostgreSQL (peer authentication keys off the effective uid).
That account is deliberately not the pepsi service account: pepsi-setup
grants its role SELECT/INSERT/DELETE on pepsi.whitelist only, so
compromising a binary that every local user can execute reaches neither the message queue
nor the signing keys.
The mailbox parsing — megabytes of attacker-controlled RFC 5322 — happens in
pepsi-helper-mailbox-scan(1), spawned with setresuid setting the
real, effective and saved ids to the target user. That process has no privileged
id left in its credentials, so it cannot become pepsi-whitelist even in
principle; it is the only standalone pepsi-helper-* program with no setuid
bit at all.
Finally, -c/--config is refused for unprivileged callers; the
environment variables that steer configuration discovery (HOME,
XDG_CONFIG_HOME), libpq (PG*) and ${NAME} expansion (TALER_*,
PEPSI_*) are removed before the configuration is read; and PATH, from
which ${DATADIR} is derived and the scan helper found, is replaced by a fixed
system path. SCAN_HELPER is one of the options the database configuration
overlay may never set.
Unlike pepsi-stage-auto-whitelist (which escapes an address into an
anchored pattern), add stores the whitelist_regex exactly as given, so the
operator controls the matching directly.
75.5. Configuration¶
[pepsi-whitelist] (all optional): HOSTERS_FILE (default
${DATADIR}/hosters.txt), WILDCARD_THRESHOLD (default 10), MAX_ENTRIES
(the cap on rows one import may add, default 5000), SCAN_HELPER (default
pepsi-helper-mailbox-scan) and MAILBOX (the default mailbox to import
from), plus the shared locality options (LOCAL_DOMAINS, TARGETS,
RECIPIENT_DELIMITER) that decide which addresses count as ours. The database
connection comes from [pepsi-postgres]. See pepsi-whitelist(1).
75.6. See also¶
pepsi-stage-check-whitelist, pepsi-stage-auto-whitelist, pepsi-queue, Architecture, pepsi-whitelist(1), pepsi-helper-mailbox-scan(1), pepsi.conf(5). Security: the program’s grant and mode in the privilege split (The privilege split), and why it is the one privileged program an ordinary account may run (A local shell user).