Checkpoint Avanan Exceptions

Overview

Exceptions are Harmony Email's two standing lists. A whitelist entry exempts matching mail from the detection engines; a blacklist entry condemns it. They are the only configuration surface this plugin can write, and each entry persists tenant-wide until someone removes it. MSP work here is adding narrow, justified entries and auditing the ones that accumulated.

Anti-triggers

• Policy configuration — enabling, disabling, tuning or scoping a security policy, adjusting engine sensitivity, editing DLP rules or impersonation-protection rosters. No tool in this plugin reaches any of it, and no sibling skill covers it; that work is console-only. Exceptions are not policies.
• Delivering one held message — a release is a message action, not a list entry. Use avanan-quarantine.
• Which policy or engine fired — use avanan-threats.
• Microsoft 365 tenant policy — conditional access, transport rules and security baselines are not Harmony Email exceptions. Use cipp-standards or cipp-mailboxes.
• Another vendor's lists — SpamTitan is spamtitan-lists. The mimecast plugin has no managed-sender skill; it covers message tracking, delivery queues and threat intelligence only.

The four tools

Every call requires excType, valued whitelist or blacklist — including hec_list_exceptions, which lists one list at a time. Auditing both means two calls.

Tool	Requires	Notes
hec_list_exceptions	excType	Returns the whole list; no paging
hec_add_exception	excType + ≥1 match field
hec_update_exception	excType, excId	Full replace of supplied fields
hec_delete_exception	excType, excId	Irreversible

The id argument is not the id field you were given. hec_list_exceptions returns each entry's identifier as entityId, but hec_update_exception and hec_delete_exception take it as excId. Passing it under the name it arrived with fails schema validation.

excId is also unrelated to the entityId of a mail entity, despite the shared field name — an exception id is not a message id.

Match fields

An add needs at least one of these; a bare excType is rejected.

Field	Matches
senderEmail	Sender address
senderDomain	Sender domain
senderName	Sender display name
recipient	Recipient address
subject	Subject line
attachmentMd5	Attachment MD5 hash
comment	Free text — not a match field, but the audit trail

Supplying several narrows the entry: they combine, so senderEmail plus subject matches only mail meeting both.

Matching modes and their defaults

Each mode governs how loosely its field matches, and the defaults are wider than most people intend:

Mode	Values	Default
senderEmailMatching	matching, contains	matching
senderDomainMatching	contains, endswith	endswith
subjectMatching	matching, contains	contains

senderDomain defaults to endswith, so example.com also exempts notexample.com and evil-example.com. Set senderDomainMatching to contains only deliberately — it is wider still, not narrower. There is no exact-match mode for a domain; a truly exact exemption has to be written as a senderEmail entry, or as one senderDomain entry per address you accept.

subject defaults to contains, which makes a short subject exception alarmingly broad.

Fields the schema does not advertise

The handler also forwards linkDomains, linkDomainMatching, senderNameMatching, recipientMatching, ignoringSpfCheck, senderClientIp, senderIp and actionNeeded when supplied, but the published input schema does not declare them. A strict MCP client will strip them before the call. Treat them as unsupported unless you have confirmed they survived — check the returned entry rather than assuming.

ignoringSpfCheck in particular turns a whitelist entry into a bypass of sender authentication as well as content inspection.

Security semantics

A whitelist entry is a standing detection bypass, not a note. It exempts matching mail from the engines that would otherwise catch it, permanently and tenant-wide, and it is the first thing an attacker wants. Mail spoofing the exempted sender inherits the exemption — which is why a domain-level entry with the default endswith mode is a materially different object from the single-sender exemption someone thought they were creating.

Adding one changes no mail flow at the moment it runs, which is exactly why it reads as harmless. A pattern of agent-created whitelist entries is a signal to review, not a productivity win.

Deleting an exception is equally consequential in reverse: it re-admits detection for a sender somebody deliberately exempted. That may be the right fix, or it may break a customer's mail flow tomorrow. The delete is a POST to a /delete/ path and is annotated irreversible — there is no undo and no soft-delete.

Auditing accumulated exceptions

hec_list_exceptions returns entityId, the match fields, comment, addedBy and updateTime — enough for a hygiene pass without any other call.

1. List both whitelist and blacklist.
2. Flag entries with an empty comment — no recorded justification.
3. Flag senderDomain entries where a senderEmail would have sufficed, and any entry relying on the endswith or contains defaults.
4. Sort by updateTime and flag anything unreviewed beyond the customer's agreed interval.
5. Cross-check addedBy against current staff — entries from departed technicians rarely have a live owner.
6. Produce a review list. Do not delete unilaterally: removal needs the technician or customer who can say whether the mail flow still matters.

Narrowing an over-broad entry is hec_update_exception, not delete-and-add — it preserves the id and the addedBy history.

Gotchas

• No paging, no filtering. hec_list_exceptions returns the entire list for one type. On a large tenant that is a large response; there is no server-side search.
• No expiry. Nothing in the surface sets a review or sunset date. A "temporary" exception is permanent unless a human returns to it, so the comment field is the only place a sunset date can live.
• Updates replace what they touch. hec_update_exception applies the fields you send; re-send the fields you intend to keep rather than assuming a partial merge preserves them.
• attachmentMd5 is MD5, not SHA-256. Hashes carried from an EDR or threat feed usually need converting or re-sourcing.

Related Skills

• Checkpoint Quarantine — acting on one message
• Checkpoint Threats — what the engines caught
• Checkpoint API Patterns — ids, auth, regions