/exceptions

name: "Checkpoint Avanan Exceptions"
description: >
  The Checkpoint Harmony Email (Avanan) whitelist and blacklist surface: the
  match fields and matching modes an exception accepts, the defaults that
  widen an entry beyond what was typed, the id mismatch between listing and
  editing, and the standing security consequence of a detection bypass.
when_to_use: >-
  When reading, adding, editing or removing sender exceptions in Checkpoint
  Harmony Email, or auditing accumulated ones. Use when: checkpoint whitelist,
  avanan whitelist, checkpoint blacklist, allow list, block list, sender
  exception, hec_list_exceptions, hec_add_exception, exempt sender, block
  domain, or exception hygiene review.

Checkpoint Harmony Email 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 c