Skip to content

Agent Zero AI framework

Fix IMAP sender whitelist bypass with strict mailbox parsing

Alessandroc565f7284587
diff --git a/plugins/_email_integration/AGENTS.md b/plugins/_email_integration/AGENTS.md
index 8d3d09c7e..42c905244 100644
--- a/plugins/_email_integration/AGENTS.md
+++ b/plugins/_email_integration/AGENTS.md
@@ -14,6 +14,7 @@
## Local Contracts
- Treat mailbox credentials and downloaded attachments as sensitive.
+- IMAP accepts exactly one valid From mailbox, rejecting duplicate fields, groups, and parser defects before body processing. Match the whitelist and address replies using that mailbox's normalized address; From filtering does not authenticate sender identity.
- Preserve UID/state tracking so restarts do not duplicate old mail.
- Keep SMTP replies threaded and safe around user-visible errors.
@@ -24,6 +25,7 @@
## Verification
- Smoke-test connection checks, polling, attachment handling, dispatch routing, and SMTP replies when practical.
+- Run `PYTHONPATH=. pytest -q tests/test_email_integration_sender.py` for inbound sender validation and SMTP recipient regression coverage.
## Child DOX Index
diff --git a/plugins/_email_integration/README.md b/plugins/_email_integration/README.md
index ad85fd1c6..49c8c820f 100644
--- a/plugins/_email_integration/README.md
+++ b/plugins/_email_integration/README.md
@@ -19,6 +19,10 @@ It supports both:
- Uses UID tracking for IMAP accounts so only new mail is processed after initialization.
- **Attachment handling**
- Downloads attachments into `usr/email/attachments`.
+- **Sender filtering**
+ - IMAP requires exactly one valid From mailbox, even when the sender whitelist is empty.
+ - Whitelist patterns match the mailbox address, excluding display names; replies use that same address.
+ - This filters the claimed From address, not authenticated identity. Sender authenticity requires checks enforced by your mail provider.
- **Dispatcher workflow**
- Reuses or creates a background `Email Dispatcher` context.
- Uses model prompts to decide whether an email belongs to an existing chat or should open a new one.
diff --git a/plugins/_email_integration/helpers/imap_client.py b/plugins/_email_integration/helpers/imap_client.py
index f88456d7a..a3f82e551 100644
--- a/plugins/_email_integration/helpers/imap_client.py
+++ b/plugins/_email_integration/helpers/imap_client.py
@@ -11,6 +11,7 @@ import re
import uuid
from dataclasses import dataclass, field
from datetime import datetime, timedelta
+from email import policy
from email.header import decode_header
from email.message import Message as EmailMessage
from fnmatch import fnmatch
@@ -209,8 +210,8 @@ async def _fetch_single(
email_msg = email.message_from_bytes(email_data) # type: ignore[arg-type]
- sender = _decode_header(email_msg.get("From", ""))
- if _is_noreply(sender):
+ sender = _extract_single_sender(email_msg)
+ if not sender or _is_noreply(sender):
return None
if sender_whitelist and not _matches_whitelist(sender, sender_whitelist):
return None
@@ -465,38 +466,26 @@ def _is_noreply(sender: str) -> bool:
def _matches_whitelist(sender: str, whitelist: list[str]) -> bool:
- sender_email = _extract_email_from_sender(sender.lower())
+ sender_email = sender.lower()
for pattern in whitelist:
if fnmatch(sender_email, pattern.lower()):
return True
return False
-def _extract_email_from_sender(sender: str) -> str:
- """Extract email address from sender string.
-
- Handles formats like:
- - "Name <[email protected]>"
- - "\"Display Name\" <[email protected]>"
-
- Uses content inside angle brackets as authoritative to prevent spoofing
- by fake emails in the display name (e.g., "John [email protected] <[email protected]>").
- """
- import re
- # Look for email inside angle brackets - this is the authoritative source
- match = re.search(r"<([^>]+)>", sender)
- if match:
- email = match.group(1).strip()
- # Validate it looks like an email
- if re.match(r"^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$", email):
- return email
-
- # No angle brackets - extract email from the whole string
- # This handles plain "[email protected]" or malformed input
- email_match = re.search(r"[^\s<>]+@[^\s<>]+\.[^\s<>]+", sender)
- if email_match:
- return email_match.group(0)
-
- # Fallback: return the whole string (will likely fail pattern match)
- return sender
+def _extract_single_sender(email_msg: EmailMessage) -> str | None:
+ """Validate one From mailbox before authorization, dispatch, or replies."""
+ headers = email_msg.get_all("From", [])
+ if len(headers) != 1:
+ return None
+ header = policy.default.header_fetch_parse("From", headers[0])
+ if (
+ header.defects
+ or len(header.addresses) != 1
+ or any(group.display_name is not None for group in header.groups)
+ ):
+ return None
+ address = header.addresses[0]
+ if not address.username or not address.domain:
+ return None
+ return address.addr_spec
diff --git a/tests/test_email_integration_sender.py b/tests/test_email_integration_sender.py
new file mode 100644
index 000000000..6562fe58b
--- /dev/null
+++ b/tests/test_email_integration_sender.py
@@ -0,0 +1,63 @@
+import asyncio
+import smtplib
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from plugins._email_integration.helpers import imap_client, smtp_client
+
+
+def test_imap_sender_validation_and_reply_recipient():
+ send_message = smtplib.SMTP.send_message
+ cases = [
+ ([], None),
+ ([""], None),
+ (["not an address"], None),
+ (["Boss <[email protected]>, [email protected]"], None),
+ (["Staff: [email protected];"], None),
+ (["Boss <[email protected]"], None),
+ (["=?utf-8?q?B=C3=B6ss?= <[email protected]>"], "[email protected]"),
+ (["Boss\r\n <[email protected]>"], "[email protected]"),
+ (["[email protected]"], None),
+ ]
+ for from_headers, address in cases:
+ raw = (
+ "".join(f"From: {value}\r\n" for value in from_headers)
+ + "Subject: sender test\r\n\r\nHarmless test body."
+ ).encode()
+ for whitelist in (None, ["*@company.com"], ["[email protected]"]):
+ accepted = address is not None and (
+ whitelist is None or address.lower() == "[email protected]"
+ )
+ for fetch in (imap_client.fetch_new, imap_client.fetch_unread_since):
+ client = MagicMock()
+ client.gmail_search.return_value = [42]
+ client.fetch.return_value = {42: {b"RFC822": raw}}
+ with patch.object(imap_client, "_parse_body", new_callable=AsyncMock) as body:
+ body.return_value = ("Harmless test body.", [])
+ messages, uid = asyncio.run(fetch(client, "unused", 1, whitelist))
+ assert uid == 42
+ assert bool(messages) == accepted, (from_headers, whitelist, fetch.__name__)
+ assert body.await_count == int(accepted)
+ client.add_flags.assert_called_once_with([42], [b"\\Seen"])
+ if accepted:
+ assert messages[0].sender == address
+
+ # Keep real SMTP recipient derivation; intercept transport only.
+ with patch.object(smtp_client.smtplib, "SMTP") as smtp:
+ server = smtp.return_value.__enter__.return_value
+ server.send_message.side_effect = lambda msg: send_message(server, msg)
+ server.ehlo_or_helo_if_needed.return_value = None
+ error = asyncio.run(smtp_client.send_reply(
+ smtp_client.SmtpConfig("unused", username="[email protected]"),
+ to=messages[0].sender,
+ subject="Re: sender test",
+ body="Harmless reply.",
+ ))
+ assert error is None
+ assert server.sendmail.call_args.args[1] == [address]