From c7713c622823f844b5e0842cc91b53b48a65782a Mon Sep 17 00:00:00 2001 From: anti Date: Sat, 11 Apr 2026 03:12:32 -0400 Subject: [PATCH] feat(imap,pop3): full IMAP4rev1 + POP3 bait mailbox implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit IMAP: extended to full IMAP4rev1 — 10 bait emails (AWS keys, DB creds, tokens, VPN config, root pw etc.), LIST/LSUB/STATUS/FETCH/UID FETCH/ SEARCH/CLOSE/NOOP, proper SELECT untagged responses (EXISTS, UIDNEXT, FLAGS, PERMANENTFLAGS), CAPABILITY with IDLE/LITERAL+/AUTH=PLAIN. FETCH correctly handles sequence sets (1:*, 1:3, *), item dispatch (FLAGS, ENVELOPE, BODY[], RFC822, RFC822.SIZE), and places body literals last per RFC 3501. POP3: extended with same 10 bait emails, fixed banner env var key (POP3_BANNER not IMAP_BANNER), CAPA fully populated (TOP/UIDL/USER/ RESP-CODES/SASL), TOP (headers + N body lines), UIDL (msg-N format), DELE/RSET with _deleted set tracking, NOOP. _active_messages() helper excludes DELE'd messages from STAT/LIST/UIDL. Both: DEBT-026 stub added (_EMAIL_SEED_PATH env var, documented in DEBT.md for next-session JSON seed file wiring). Tests: test_imap.py expanded to 27 cases, test_pop3.py to 22 cases — 860 total tests passing. --- DEBT.md | 12 +- templates/imap/server.py | 560 +++++++++++++++++++++++++---- templates/pop3/server.py | 467 ++++++++++++++++++------ tests/service_testing/test_imap.py | 279 ++++++++++++-- tests/service_testing/test_pop3.py | 242 +++++++++++-- 5 files changed, 1326 insertions(+), 234 deletions(-) diff --git a/DEBT.md b/DEBT.md index a3da844..f8de25a 100644 --- a/DEBT.md +++ b/DEBT.md @@ -101,10 +101,14 @@ All route decorators now declare `responses={401: {"description": "Not authentic ~~**File:** `decnet/web/sqlite_repository.py` (~400 lines)~~ Fully refactored to `decnet/web/db/` modular layout: `models.py` (SQLModel schema), `repository.py` (abstract base), `sqlite/repository.py` (SQLite implementation), `sqlite/database.py` (engine/session factory). Commit `de84cc6`. -### DEBT-026 — IMAP/POP3 bait emails are hardcoded -**Files:** `templates/imap/server.py`, `templates/pop3/server.py` -Bait emails are hardcoded strings. A modular framework to dynamically inject personalized mailboxes, custom mails, and dynamic users should be implemented in the future for a more personalized feel. -**Status:** Deferred — out of current scope. +### DEBT-026 — IMAP/POP3 bait emails not configurable via service config +**Files:** `templates/imap/server.py`, `templates/pop3/server.py`, `decnet/services/imap.py`, `decnet/services/pop3.py` +Bait emails are hardcoded. A stub env var `IMAP_EMAIL_SEED` is read but currently ignored. Full implementation requires: +1. `IMAP_EMAIL_SEED` points to a JSON file with a list of `{from_, to, subject, date, body}` dicts. +2. `templates/imap/server.py` loads and merges/replaces `_BAIT_EMAILS` from that file at startup. +3. `decnet/services/imap.py` `compose_fragment()` reads `service_cfg["email_seed"]` and injects `IMAP_EMAIL_SEED` + a bind-mount for the seed file into the compose fragment. +4. Same pattern for POP3 (`POP3_EMAIL_SEED`). +**Status:** Stub in place — full wiring deferred to next session. --- diff --git a/templates/imap/server.py b/templates/imap/server.py index 8a38293..d558b8c 100644 --- a/templates/imap/server.py +++ b/templates/imap/server.py @@ -1,52 +1,356 @@ #!/usr/bin/env python3 """ -IMAP server (port 143/993). -Presents an IMAP4rev1 banner, captures LOGIN credentials. -Implements a basic IMAP state machine (NOT_AUTHENTICATED -> AUTHENTICATED -> SELECTED). -Provides hardcoded bait emails containing AWS API keys to attackers. -Logs commands as JSON. +IMAP server (port 143). +Full IMAP4rev1 state machine with bait mailbox. + +States: NOT_AUTHENTICATED → AUTHENTICATED → SELECTED + +Credentials via IMAP_USERS env var ("user:pass,user2:pass2"). +10 bait emails in INBOX containing AWS keys, DB passwords, tokens etc. +Banner advertises Dovecot so nmap fingerprints correctly. """ import asyncio import os -from decnet_logging import syslog_line, write_syslog_file, forward_syslog +from decnet_logging import SEVERITY_WARNING, syslog_line, write_syslog_file, forward_syslog -NODE_NAME = os.environ.get("NODE_NAME", "mailserver") -SERVICE_NAME = "imap" -LOG_TARGET = os.environ.get("LOG_TARGET", "") -IMAP_BANNER = os.environ.get("IMAP_BANNER", f"* OK [{NODE_NAME}] Dovecot ready.\r\n") +NODE_NAME = os.environ.get("NODE_NAME", "mailserver") +SERVICE_NAME = "imap" +LOG_TARGET = os.environ.get("LOG_TARGET", "") +IMAP_BANNER = os.environ.get("IMAP_BANNER", f"* OK Dovecot ready.\r\n") +_RAW_USERS = os.environ.get("IMAP_USERS", "admin:admin123,root:toor,mail:mail,user:user") -IMAP_USERS = os.environ.get("IMAP_USERS", "admin:admin123,root:toor") +VALID_USERS: dict[str, str] = { + u: p for part in _RAW_USERS.split(",") if ":" in part for u, p in [part.split(":", 1)] +} -_BAIT_EMAILS = [ - (1, "Date: Tue, 01 Nov 2023 10:00:00 +0000\r\nFrom: sysadmin@company.com\r\nSubject: AWS Credentials\r\n\r\nHere are the new AWS keys:\r\nAKIAIOSFODNN7EXAMPLE\r\nwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n"), - (2, "Date: Wed, 02 Nov 2023 11:30:00 +0000\r\nFrom: devops@company.com\r\nSubject: DB Password Reset\r\n\r\nThe production database password has been temporarily set to:\r\nProdDB_temp_2023!!\r\n"), +# DEBT-026: path to a JSON file with custom email definitions. +# When set, _BAIT_EMAILS should be replaced/extended from that file. +# Wiring (service_cfg["email_seed"] → compose_fragment → env var → here) is deferred. +_EMAIL_SEED_PATH = os.environ.get("IMAP_EMAIL_SEED", "") # stub — currently unused + +# ── Bait emails ─────────────────────────────────────────────────────────────── +# All 10 live in INBOX. UID == sequence number. + +_BAIT_EMAILS: list[dict] = [ + { + "uid": 1, "flags": [r"\Seen"], + "from_name": "DevOps Team", "from_addr": "devops@company.internal", + "to_addr": "admin@company.internal", + "subject": "AWS credentials rotation", + "date": "Mon, 06 Nov 2023 09:12:33 +0000", + "body": ( + "Date: Mon, 06 Nov 2023 09:12:33 +0000\r\n" + "From: DevOps Team \r\n" + "To: admin@company.internal\r\n" + "Subject: AWS credentials rotation\r\n" + "Message-ID: <1@company.internal>\r\n" + "\r\n" + "Team,\r\n\r\n" + "New AWS credentials have been issued. Old keys deactivated.\r\n\r\n" + "Access Key ID: AKIAIOSFODNN7EXAMPLE\r\n" + "Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n\r\n" + "Update ~/.aws/credentials immediately.\r\n\r\n-- DevOps\r\n" + ), + }, + { + "uid": 2, "flags": [r"\Seen"], + "from_name": "Monitoring", "from_addr": "monitoring@company.internal", + "to_addr": "admin@company.internal", + "subject": "DB password changed", + "date": "Tue, 07 Nov 2023 14:05:11 +0000", + "body": ( + "Date: Tue, 07 Nov 2023 14:05:11 +0000\r\n" + "From: Monitoring \r\n" + "To: admin@company.internal\r\n" + "Subject: DB password changed\r\n" + "Message-ID: <2@company.internal>\r\n" + "\r\n" + "Production database password was rotated.\r\n\r\n" + "Connection string: mysql://admin:Sup3rS3cr3t!@10.0.1.5:3306/production\r\n\r\n" + "Update all app configs.\r\n" + ), + }, + { + "uid": 3, "flags": [], + "from_name": "GitHub", "from_addr": "noreply@github.com", + "to_addr": "admin@company.internal", + "subject": "Your personal access token", + "date": "Wed, 08 Nov 2023 08:30:00 +0000", + "body": ( + "Date: Wed, 08 Nov 2023 08:30:00 +0000\r\n" + "From: GitHub \r\n" + "To: admin@company.internal\r\n" + "Subject: Your personal access token\r\n" + "Message-ID: <3@company.internal>\r\n" + "\r\n" + "Hi admin,\r\n\r\n" + "A new personal access token was created for your account.\r\n\r\n" + "Token: ghp_16C7e42F292c6912E7710c838347Ae178B4a\r\n\r\n" + "If this wasn't you, revoke it immediately at github.com/settings/tokens.\r\n" + ), + }, + { + "uid": 4, "flags": [r"\Seen"], + "from_name": "IT Admin", "from_addr": "admin@company.internal", + "to_addr": "team@company.internal", + "subject": "VPN config attached", + "date": "Thu, 09 Nov 2023 11:22:47 +0000", + "body": ( + "Date: Thu, 09 Nov 2023 11:22:47 +0000\r\n" + "From: IT Admin \r\n" + "To: team@company.internal\r\n" + "Subject: VPN config attached\r\n" + "Message-ID: <4@company.internal>\r\n" + "\r\n" + "VPN access details for new starters:\r\n\r\n" + " Host: vpn.company.internal:1194\r\n" + " Protocol: UDP\r\n" + " Username: vpnadmin\r\n" + " Password: VpnP@ss2024\r\n\r\n" + "Config file sent separately via secure channel.\r\n" + ), + }, + { + "uid": 5, "flags": [], + "from_name": "SysAdmin", "from_addr": "sysadmin@company.internal", + "to_addr": "admin@company.internal", + "subject": "Root password", + "date": "Fri, 10 Nov 2023 16:45:00 +0000", + "body": ( + "Date: Fri, 10 Nov 2023 16:45:00 +0000\r\n" + "From: SysAdmin \r\n" + "To: admin@company.internal\r\n" + "Subject: Root password\r\n" + "Message-ID: <5@company.internal>\r\n" + "\r\n" + "New root password for prod servers:\r\n\r\n" + " r00tM3T00!\r\n\r\n" + "Change after first login. Do NOT forward this email.\r\n" + ), + }, + { + "uid": 6, "flags": [r"\Seen"], + "from_name": "Backup System", "from_addr": "backup@company.internal", + "to_addr": "admin@company.internal", + "subject": "Backup job failed", + "date": "Sat, 11 Nov 2023 03:12:04 +0000", + "body": ( + "Date: Sat, 11 Nov 2023 03:12:04 +0000\r\n" + "From: Backup System \r\n" + "To: admin@company.internal\r\n" + "Subject: Backup job failed\r\n" + "Message-ID: <6@company.internal>\r\n" + "\r\n" + "Nightly backup to 192.168.1.50:/mnt/nas FAILED at 03:11 UTC.\r\n\r\n" + "Error: Authentication failed. Credentials in /etc/backup.conf may be stale.\r\n\r\n" + "Last successful backup: 2023-11-10 03:11 UTC\r\n" + ), + }, + { + "uid": 7, "flags": [r"\Seen"], + "from_name": "Security Alerts", "from_addr": "alerts@company.internal", + "to_addr": "admin@company.internal", + "subject": "SSH brute-force alert", + "date": "Sun, 12 Nov 2023 07:04:31 +0000", + "body": ( + "Date: Sun, 12 Nov 2023 07:04:31 +0000\r\n" + "From: Security Alerts \r\n" + "To: admin@company.internal\r\n" + "Subject: SSH brute-force alert\r\n" + "Message-ID: <7@company.internal>\r\n" + "\r\n" + "47 failed SSH login attempts detected against prod-web-01.\r\n\r\n" + "Source IPs: 185.220.101.34, 185.220.101.47, 185.220.101.52\r\n" + "Target user: root\r\n" + "Period: 2023-11-12 06:58 – 07:04 UTC\r\n\r\n" + "All attempts blocked by fail2ban. No successful logins.\r\n" + ), + }, + { + "uid": 8, "flags": [r"\Seen"], + "from_name": "External Vendor", "from_addr": "vendor@external.com", + "to_addr": "admin@company.internal", + "subject": "RE: API integration", + "date": "Mon, 13 Nov 2023 10:11:55 +0000", + "body": ( + "Date: Mon, 13 Nov 2023 10:11:55 +0000\r\n" + "From: External Vendor \r\n" + "To: admin@company.internal\r\n" + "Subject: RE: API integration\r\n" + "Message-ID: <8@company.internal>\r\n" + "\r\n" + "Hi,\r\n\r\n" + "Here is the live API key for the integration:\r\n\r\n" + " sk_live_9mK3xF2aP7qR1bN8cT4dW6vE0yU5hJ\r\n\r\n" + "Keep this confidential. Let me know if you need the webhook secret.\r\n\r\n" + "Best regards,\r\nVendor Support\r\n" + ), + }, + { + "uid": 9, "flags": [], + "from_name": "Help Desk", "from_addr": "helpdesk@company.internal", + "to_addr": "admin@company.internal", + "subject": "Password reset request", + "date": "Tue, 14 Nov 2023 13:48:22 +0000", + "body": ( + "Date: Tue, 14 Nov 2023 13:48:22 +0000\r\n" + "From: Help Desk \r\n" + "To: admin@company.internal\r\n" + "Subject: Password reset request\r\n" + "Message-ID: <9@company.internal>\r\n" + "\r\n" + "Hi,\r\n\r\n" + "Could you reset my MFA? Current password is Winter2024! so you can verify it's me.\r\n\r\n" + "Thanks\r\n" + ), + }, + { + "uid": 10, "flags": [r"\Seen"], + "from_name": "AWS Billing", "from_addr": "noreply@aws.amazon.com", + "to_addr": "admin@company.internal", + "subject": "Your AWS bill is ready", + "date": "Wed, 15 Nov 2023 00:01:00 +0000", + "body": ( + "Date: Wed, 15 Nov 2023 00:01:00 +0000\r\n" + "From: AWS Billing \r\n" + "To: admin@company.internal\r\n" + "Subject: Your AWS bill is ready\r\n" + "Message-ID: <10@company.internal>\r\n" + "\r\n" + "Your AWS bill for October 2023 is $847.23.\r\n\r\n" + "Top services:\r\n" + " EC2 (us-east-1): $412.10\r\n" + " RDS (us-east-1): $198.50\r\n" + " S3: $87.43\r\n" + " EC2 (eu-west-2): $149.20\r\n\r\n" + "Account ID: 123456789012\r\n" + ), + }, ] +_MAILBOXES = ["INBOX", "Sent", "Drafts", "Archive"] + +# ── Logging ─────────────────────────────────────────────────────────────────── + def _log(event_type: str, severity: int = 6, **kwargs) -> None: line = syslog_line(SERVICE_NAME, NODE_NAME, event_type, severity, **kwargs) print(line, flush=True) write_syslog_file(line) forward_syslog(line, LOG_TARGET) +# ── FETCH helpers ───────────────────────────────────────────────────────────── + +def _parse_seq_range(range_str: str, total: int) -> list[int]: + """Parse IMAP sequence set ('1', '1:3', '1:*', '*') → list of 1-based indices.""" + result = [] + for part in range_str.split(","): + part = part.strip() + if ":" in part: + lo_s, hi_s = part.split(":", 1) + lo = total if lo_s == "*" else int(lo_s) + hi = total if hi_s == "*" else int(hi_s) + result.extend(range(min(lo, hi), max(lo, hi) + 1)) + elif part == "*": + result.append(total) + else: + result.append(int(part)) + return [n for n in result if 1 <= n <= total] + + +def _parse_fetch_items(items_str: str) -> list[str]: + """Parse '(FLAGS ENVELOPE)' or 'BODY[]' → list of item name strings.""" + s = items_str.strip() + if s.startswith("(") and s.endswith(")"): + s = s[1:-1] + tokens, i = [], 0 + while i < len(s): + if s[i] == " ": + i += 1 + continue + j, depth = i, 0 + while j < len(s): + if s[j] == "[": + depth += 1 + elif s[j] == "]": + depth -= 1 + elif s[j] == " " and depth == 0: + break + j += 1 + tokens.append(s[i:j].upper()) + i = j + return tokens + + +def _envelope(msg: dict) -> str: + """Build minimal RFC 3501 ENVELOPE tuple string.""" + def addr(name: str, email: str) -> str: + parts = email.split("@", 1) + user = parts[0] + host = parts[1] if len(parts) > 1 else "" + safe_name = name.replace('"', '\\"') + return f'("{safe_name}" NIL "{user}" "{host}")' + + from_addr = addr(msg["from_name"], msg["from_addr"]) + to_addr = addr("", msg["to_addr"]) + subject = msg["subject"].replace('"', '\\"') + return ( + f'("{msg["date"]}" "{subject}" ' + f'({from_addr}) ({from_addr}) ({from_addr}) ' + f'({to_addr}) NIL NIL NIL "<{msg["uid"]}@{NODE_NAME}>")' + ) + + +def _build_fetch_response(seq: int, msg: dict, items: list[str]) -> bytes: + """Build the bytes for a single '* N FETCH (...)' response.""" + non_literal: list[str] = [] + literal_name: str | None = None + literal_raw: bytes | None = None + + for item in items: + norm = item.upper() + if norm == "FLAGS": + flags = " ".join(msg["flags"]) if msg["flags"] else "" + non_literal.append(f"FLAGS ({flags})") + elif norm == "ENVELOPE": + non_literal.append(f"ENVELOPE {_envelope(msg)}") + elif norm == "RFC822.SIZE": + non_literal.append(f"RFC822.SIZE {len(msg['body'].encode())}") + elif norm in ("UID",): + non_literal.append(f"UID {msg['uid']}") + elif norm in ("BODY[]", "RFC822", "BODY[TEXT]", "BODY.PEEK[]"): + literal_name = "BODY[]" + literal_raw = msg["body"].encode() + elif norm in ("BODY[HEADER]", "BODY.PEEK[HEADER]"): + header_part = msg["body"].split("\r\n\r\n", 1)[0] + "\r\n\r\n" + literal_name = "BODY[HEADER]" + literal_raw = header_part.encode() + # unknown items silently ignored + + if literal_raw is not None: + prefix_str = (" ".join(non_literal) + " ") if non_literal else "" + header = f"* {seq} FETCH ({prefix_str}{literal_name} {{{len(literal_raw)}}}\r\n".encode() + return header + literal_raw + b")\r\n" + else: + return f"* {seq} FETCH ({' '.join(non_literal)})\r\n".encode() + + +# ── Protocol ────────────────────────────────────────────────────────────────── + class IMAPProtocol(asyncio.Protocol): def __init__(self): - self._transport = None - self._peer = None - self._buf = b"" - self._state = "NOT_AUTHENTICATED" - self._valid_users = dict(u.split(":", 1) for u in IMAP_USERS.split(",") if ":" in u) + self._transport = None + self._peer = ("?", 0) + self._buf = b"" + self._state = "NOT_AUTHENTICATED" + self._selected = None # mailbox name currently selected def connection_made(self, transport): self._transport = transport self._peer = transport.get_extra_info("peername", ("?", 0)) _log("connect", src=self._peer[0], src_port=self._peer[1]) - if IMAP_BANNER: - if not IMAP_BANNER.endswith("\r\n"): - padded_banner = IMAP_BANNER + "\r\n" - else: - padded_banner = IMAP_BANNER - transport.write(padded_banner.encode()) + banner = IMAP_BANNER if IMAP_BANNER.endswith("\r\n") else IMAP_BANNER + "\r\n" + transport.write(banner.encode()) def data_received(self, data): self._buf += data @@ -54,7 +358,12 @@ class IMAPProtocol(asyncio.Protocol): line, self._buf = self._buf.split(b"\n", 1) self._handle_line(line.decode(errors="replace").strip()) - def _handle_line(self, line: str): + def connection_lost(self, exc): + _log("disconnect", src=self._peer[0] if self._peer else "?") + + # ── Command dispatch ────────────────────────────────────────────────────── + + def _handle_line(self, line: str) -> None: parts = line.split(None, 2) if not parts: return @@ -62,63 +371,162 @@ class IMAPProtocol(asyncio.Protocol): cmd = parts[1].upper() if len(parts) > 1 else "" args = parts[2] if len(parts) > 2 else "" - _log("command", src=self._peer[0], cmd=line[:128], state=self._state) + _log("command", src=self._peer[0], cmd=cmd, state=self._state) + # Commands valid in any state if cmd == "CAPABILITY": - self._transport.write(b"* CAPABILITY IMAP4rev1 AUTH=PLAIN AUTH=LOGIN\r\n") - self._transport.write(f"{tag} OK CAPABILITY completed\r\n".encode()) - - elif cmd == "LOGIN": - if self._state != "NOT_AUTHENTICATED": - self._transport.write(f"{tag} BAD Already authenticated\r\n".encode()) - return - creds = args.split(None, 1) - username = creds[0].strip('"') if creds else "" - password = creds[1].strip('"') if len(creds) > 1 else "" - - if username in self._valid_users and self._valid_users[username] == password: - self._state = "AUTHENTICATED" - _log("auth", src=self._peer[0], username=username, password=password, status="success") - self._transport.write(f"{tag} OK [CAPABILITY IMAP4rev1] Logged in\r\n".encode()) - else: - _log("auth", src=self._peer[0], username=username, password=password, status="failed") - self._transport.write(f"{tag} NO [AUTHENTICATIONFAILED] Authentication failed.\r\n".encode()) - - elif cmd == "SELECT" or cmd == "EXAMINE": - if self._state == "NOT_AUTHENTICATED": - self._transport.write(f"{tag} BAD Not authenticated\r\n".encode()) - return - - self._state = "SELECTED" - count = len(_BAIT_EMAILS) - self._transport.write(f"* {count} EXISTS\r\n* 0 RECENT\r\n* OK [UIDVALIDITY 1] UIDs valid\r\n".encode()) - self._transport.write(f"{tag} OK [READ-WRITE] Select completed.\r\n".encode()) + self._w(b"* CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS" + b" ID ENABLE IDLE AUTH=PLAIN AUTH=LOGIN\r\n") + self._w(f"{tag} OK CAPABILITY completed\r\n") - elif cmd == "FETCH": - if self._state != "SELECTED": - self._transport.write(f"{tag} BAD Not selected\r\n".encode()) - return - - # rudimentary fetch match simply returning all if any match - # an attacker usually sends "FETCH 1:* (BODY[])" or similar - if "RFC822" in args.upper() or "BODY" in args.upper(): - for uid, content in _BAIT_EMAILS: - content_encoded = content.encode() - self._transport.write(f"* {uid} FETCH (RFC822 {{{len(content_encoded)}}}\r\n".encode()) - self._transport.write(content_encoded) - self._transport.write(b")\r\n") - self._transport.write(f"{tag} OK Fetch completed.\r\n".encode()) + elif cmd == "NOOP": + self._w(f"{tag} OK\r\n") elif cmd == "LOGOUT": - self._transport.write(b"* BYE Logging out\r\n") - self._transport.write(f"{tag} OK Logout completed.\r\n".encode()) + self._w(b"* BYE Logging out\r\n") + self._w(f"{tag} OK LOGOUT completed\r\n") self._transport.close() - - else: - self._transport.write(f"{tag} BAD Command not recognized or unsupported\r\n".encode()) - def connection_lost(self, exc): - _log("disconnect", src=self._peer[0] if self._peer else "?") + # NOT_AUTHENTICATED only + elif cmd == "LOGIN": + self._cmd_login(tag, args) + + # AUTHENTICATED or SELECTED + elif cmd in ("LIST", "LSUB"): + self._cmd_list(tag, cmd) + elif cmd == "STATUS": + self._cmd_status(tag, args) + elif cmd in ("SELECT", "EXAMINE"): + self._cmd_select(tag, cmd, args) + + # SELECTED only + elif cmd == "FETCH": + self._cmd_fetch(tag, args, use_uid=False) + elif cmd == "SEARCH": + self._cmd_search(tag) + elif cmd == "CLOSE": + self._cmd_close(tag) + + # UID prefix — dispatch sub-command + elif cmd == "UID": + sub_parts = args.split(None, 1) + sub_cmd = sub_parts[0].upper() if sub_parts else "" + sub_args = sub_parts[1] if len(sub_parts) > 1 else "" + if sub_cmd == "FETCH": + self._cmd_fetch(tag, sub_args, use_uid=True) + elif sub_cmd == "SEARCH": + self._cmd_search(tag, uid_mode=True) + else: + self._w(f"{tag} BAD Unknown UID sub-command\r\n") + + else: + self._w(f"{tag} BAD Command not recognized or not supported\r\n") + + # ── Command implementations ─────────────────────────────────────────────── + + def _cmd_login(self, tag: str, args: str) -> None: + if self._state != "NOT_AUTHENTICATED": + self._w(f"{tag} BAD Already authenticated\r\n") + return + parts = args.split(None, 1) + username = parts[0].strip('"') if parts else "" + password = parts[1].strip('"') if len(parts) > 1 else "" + if VALID_USERS.get(username) == password: + self._state = "AUTHENTICATED" + _log("auth", src=self._peer[0], username=username, password=password, + status="success") + self._w(f"{tag} OK [CAPABILITY IMAP4rev1] Logged in\r\n") + else: + _log("auth", src=self._peer[0], username=username, password=password, + status="failed", severity=SEVERITY_WARNING) + self._w(f"{tag} NO [AUTHENTICATIONFAILED] Authentication failed.\r\n") + + def _cmd_list(self, tag: str, cmd: str) -> None: + if self._state == "NOT_AUTHENTICATED": + self._w(f"{tag} BAD Not authenticated\r\n") + return + for box in _MAILBOXES: + self._w(f'* {cmd} (\\HasNoChildren) "/" "{box}"\r\n') + self._w(f"{tag} OK {cmd} completed\r\n") + + def _cmd_status(self, tag: str, args: str) -> None: + if self._state == "NOT_AUTHENTICATED": + self._w(f"{tag} BAD Not authenticated\r\n") + return + parts = args.split(None, 1) + mailbox = parts[0].strip('"') if parts else "INBOX" + attr_str = parts[1].strip("()").upper() if len(parts) > 1 else "MESSAGES" + + counts = {"MESSAGES": 10, "RECENT": 0, "UNSEEN": 10} if mailbox == "INBOX" \ + else {"MESSAGES": 0, "RECENT": 0, "UNSEEN": 0} + + result_parts = [] + for attr in attr_str.split(): + if attr in counts: + result_parts.append(f"{attr} {counts[attr]}") + self._w(f"* STATUS {mailbox} ({' '.join(result_parts)})\r\n") + self._w(f"{tag} OK STATUS completed\r\n") + + def _cmd_select(self, tag: str, cmd: str, args: str) -> None: + if self._state == "NOT_AUTHENTICATED": + self._w(f"{tag} BAD Not authenticated\r\n") + return + mailbox = args.strip('"') + total = len(_BAIT_EMAILS) if mailbox == "INBOX" else 0 + self._selected = mailbox + self._state = "SELECTED" + self._w(f"* {total} EXISTS\r\n") + self._w(b"* 0 RECENT\r\n") + self._w(b"* OK [UNSEEN 1] Message 1 is first unseen\r\n") + self._w(b"* OK [UIDVALIDITY 1712345678] UIDs valid\r\n") + self._w(f"* OK [UIDNEXT {total + 1}] Predicted next UID\r\n") + self._w(b"* FLAGS (\\Answered \\Flagged \\Deleted \\Seen \\Draft)\r\n") + self._w(b"* OK [PERMANENTFLAGS (\\Deleted \\Seen \\*)] Limited\r\n") + mode = "READ-ONLY" if cmd == "EXAMINE" else "READ-WRITE" + self._w(f"{tag} OK [{mode}] {cmd} completed\r\n") + + def _cmd_fetch(self, tag: str, args: str, use_uid: bool) -> None: + if self._state != "SELECTED": + self._w(f"{tag} BAD Not in selected state\r\n") + return + parts = args.split(None, 1) + range_str = parts[0] if parts else "1:*" + items_str = parts[1] if len(parts) > 1 else "FLAGS" + + total = len(_BAIT_EMAILS) + indices = _parse_seq_range(range_str, total) + items = _parse_fetch_items(items_str) + # Ensure UID is included when using UID FETCH + if use_uid and "UID" not in items: + items = ["UID"] + items + + for seq in indices: + if 1 <= seq <= total: + self._transport.write(_build_fetch_response(seq, _BAIT_EMAILS[seq - 1], items)) + self._w(f"{tag} OK FETCH completed\r\n") + + def _cmd_search(self, tag: str, uid_mode: bool = False) -> None: + if self._state != "SELECTED": + self._w(f"{tag} BAD Not in selected state\r\n") + return + nums = " ".join(str(i) for i in range(1, len(_BAIT_EMAILS) + 1)) + self._w(f"* SEARCH {nums}\r\n") + self._w(f"{tag} OK SEARCH completed\r\n") + + def _cmd_close(self, tag: str) -> None: + if self._state != "SELECTED": + self._w(f"{tag} BAD Not in selected state\r\n") + return + self._state = "AUTHENTICATED" + self._selected = None + self._w(f"{tag} OK CLOSE completed\r\n") + + # ── Helpers ─────────────────────────────────────────────────────────────── + + def _w(self, data: str | bytes) -> None: + if isinstance(data, str): + data = data.encode() + self._transport.write(data) async def main(): diff --git a/templates/pop3/server.py b/templates/pop3/server.py index 17f0bdf..90b5176 100644 --- a/templates/pop3/server.py +++ b/templates/pop3/server.py @@ -1,55 +1,189 @@ #!/usr/bin/env python3 """ -POP3 server (port 110/995). -Presents a POP3 banner, captures USER and PASS credentials. -Implements a basic POP3 state machine (AUTHORIZATION -> TRANSACTION). -Provides hardcoded bait emails. -Logs commands as JSON. +POP3 server (port 110). +Full POP3 state machine with bait mailbox. + +States: AUTHORIZATION → TRANSACTION + +Credentials via IMAP_USERS env var (shared with IMAP service). +10 bait emails containing AWS keys, DB passwords, tokens etc. """ import asyncio import os -from decnet_logging import syslog_line, write_syslog_file, forward_syslog +from decnet_logging import SEVERITY_WARNING, syslog_line, write_syslog_file, forward_syslog -NODE_NAME = os.environ.get("NODE_NAME", "mailserver") -SERVICE_NAME = "pop3" -LOG_TARGET = os.environ.get("LOG_TARGET", "") -POP3_BANNER = os.environ.get("IMAP_BANNER", f"+OK [{NODE_NAME}] Dovecot ready.\r\n") +NODE_NAME = os.environ.get("NODE_NAME", "mailserver") +SERVICE_NAME = "pop3" +LOG_TARGET = os.environ.get("LOG_TARGET", "") +POP3_BANNER = os.environ.get("POP3_BANNER", f"+OK {NODE_NAME} Dovecot POP3 ready.") +_RAW_USERS = os.environ.get("IMAP_USERS", "admin:admin123,root:toor,mail:mail,user:user") -IMAP_USERS = os.environ.get("IMAP_USERS", "admin:admin123,root:toor") +VALID_USERS: dict[str, str] = { + u: p for part in _RAW_USERS.split(",") if ":" in part for u, p in [part.split(":", 1)] +} -_BAIT_EMAILS = [ - "Date: Tue, 01 Nov 2023 10:00:00 +0000\r\nFrom: sysadmin@company.com\r\nSubject: AWS Credentials\r\n\r\nHere are the new AWS keys:\r\nAKIAIOSFODNN7EXAMPLE\r\nwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n", - "Date: Wed, 02 Nov 2023 11:30:00 +0000\r\nFrom: devops@company.com\r\nSubject: DB Password Reset\r\n\r\nThe production database password has been temporarily set to:\r\nProdDB_temp_2023!!\r\n", +# DEBT-026: path to a JSON file with custom email definitions. +# Wiring (service_cfg["email_seed"] → compose_fragment → env var → here) is deferred. +_EMAIL_SEED_PATH = os.environ.get("POP3_EMAIL_SEED", "") # stub — currently unused + +# ── Bait emails ─────────────────────────────────────────────────────────────── + +_BAIT_EMAILS: list[str] = [ + ( + "Date: Mon, 06 Nov 2023 09:12:33 +0000\r\n" + "From: DevOps Team \r\n" + "To: admin@company.internal\r\n" + "Subject: AWS credentials rotation\r\n" + "Message-ID: <1@company.internal>\r\n" + "\r\n" + "Team,\r\n\r\n" + "New AWS credentials have been issued. Old keys deactivated.\r\n\r\n" + "Access Key ID: AKIAIOSFODNN7EXAMPLE\r\n" + "Secret Access Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\r\n\r\n" + "Update ~/.aws/credentials immediately.\r\n\r\n-- DevOps\r\n" + ), + ( + "Date: Tue, 07 Nov 2023 14:05:11 +0000\r\n" + "From: Monitoring \r\n" + "To: admin@company.internal\r\n" + "Subject: DB password changed\r\n" + "Message-ID: <2@company.internal>\r\n" + "\r\n" + "Production database password was rotated.\r\n\r\n" + "Connection string: mysql://admin:Sup3rS3cr3t!@10.0.1.5:3306/production\r\n\r\n" + "Update all app configs.\r\n" + ), + ( + "Date: Wed, 08 Nov 2023 08:30:00 +0000\r\n" + "From: GitHub \r\n" + "To: admin@company.internal\r\n" + "Subject: Your personal access token\r\n" + "Message-ID: <3@company.internal>\r\n" + "\r\n" + "Hi admin,\r\n\r\n" + "A new personal access token was created for your account.\r\n\r\n" + "Token: ghp_16C7e42F292c6912E7710c838347Ae178B4a\r\n\r\n" + "If this wasn't you, revoke it immediately at github.com/settings/tokens.\r\n" + ), + ( + "Date: Thu, 09 Nov 2023 11:22:47 +0000\r\n" + "From: IT Admin \r\n" + "To: team@company.internal\r\n" + "Subject: VPN config attached\r\n" + "Message-ID: <4@company.internal>\r\n" + "\r\n" + "VPN access details for new starters:\r\n\r\n" + " Host: vpn.company.internal:1194\r\n" + " Protocol: UDP\r\n" + " Username: vpnadmin\r\n" + " Password: VpnP@ss2024\r\n\r\n" + "Config file sent separately via secure channel.\r\n" + ), + ( + "Date: Fri, 10 Nov 2023 16:45:00 +0000\r\n" + "From: SysAdmin \r\n" + "To: admin@company.internal\r\n" + "Subject: Root password\r\n" + "Message-ID: <5@company.internal>\r\n" + "\r\n" + "New root password for prod servers:\r\n\r\n" + " r00tM3T00!\r\n\r\n" + "Change after first login. Do NOT forward this email.\r\n" + ), + ( + "Date: Sat, 11 Nov 2023 03:12:04 +0000\r\n" + "From: Backup System \r\n" + "To: admin@company.internal\r\n" + "Subject: Backup job failed\r\n" + "Message-ID: <6@company.internal>\r\n" + "\r\n" + "Nightly backup to 192.168.1.50:/mnt/nas FAILED at 03:11 UTC.\r\n\r\n" + "Error: Authentication failed. Credentials in /etc/backup.conf may be stale.\r\n\r\n" + "Last successful backup: 2023-11-10 03:11 UTC\r\n" + ), + ( + "Date: Sun, 12 Nov 2023 07:04:31 +0000\r\n" + "From: Security Alerts \r\n" + "To: admin@company.internal\r\n" + "Subject: SSH brute-force alert\r\n" + "Message-ID: <7@company.internal>\r\n" + "\r\n" + "47 failed SSH login attempts detected against prod-web-01.\r\n\r\n" + "Source IPs: 185.220.101.34, 185.220.101.47, 185.220.101.52\r\n" + "Target user: root\r\n" + "Period: 2023-11-12 06:58 - 07:04 UTC\r\n\r\n" + "All attempts blocked by fail2ban. No successful logins.\r\n" + ), + ( + "Date: Mon, 13 Nov 2023 10:11:55 +0000\r\n" + "From: External Vendor \r\n" + "To: admin@company.internal\r\n" + "Subject: RE: API integration\r\n" + "Message-ID: <8@company.internal>\r\n" + "\r\n" + "Hi,\r\n\r\n" + "Here is the live API key for the integration:\r\n\r\n" + " sk_live_9mK3xF2aP7qR1bN8cT4dW6vE0yU5hJ\r\n\r\n" + "Keep this confidential. Let me know if you need the webhook secret.\r\n\r\n" + "Best regards,\r\nVendor Support\r\n" + ), + ( + "Date: Tue, 14 Nov 2023 13:48:22 +0000\r\n" + "From: Help Desk \r\n" + "To: admin@company.internal\r\n" + "Subject: Password reset request\r\n" + "Message-ID: <9@company.internal>\r\n" + "\r\n" + "Hi,\r\n\r\n" + "Could you reset my MFA? Current password is Winter2024! so you can verify it's me.\r\n\r\n" + "Thanks\r\n" + ), + ( + "Date: Wed, 15 Nov 2023 00:01:00 +0000\r\n" + "From: AWS Billing \r\n" + "To: admin@company.internal\r\n" + "Subject: Your AWS bill is ready\r\n" + "Message-ID: <10@company.internal>\r\n" + "\r\n" + "Your AWS bill for October 2023 is $847.23.\r\n\r\n" + "Top services:\r\n" + " EC2 (us-east-1): $412.10\r\n" + " RDS (us-east-1): $198.50\r\n" + " S3: $87.43\r\n" + " EC2 (eu-west-2): $149.20\r\n\r\n" + "Account ID: 123456789012\r\n" + ), ] +# ── Logging ─────────────────────────────────────────────────────────────────── + def _log(event_type: str, severity: int = 6, **kwargs) -> None: line = syslog_line(SERVICE_NAME, NODE_NAME, event_type, severity, **kwargs) print(line, flush=True) write_syslog_file(line) forward_syslog(line, LOG_TARGET) + +# ── Protocol ────────────────────────────────────────────────────────────────── + class POP3Protocol(asyncio.Protocol): def __init__(self): - self._transport = None - self._peer = None - self._buf = b"" - self._state = "AUTHORIZATION" - self._valid_users = dict(u.split(":", 1) for u in IMAP_USERS.split(",") if ":" in u) - self._current_user = None + self._transport = None + self._peer = ("?", 0) + self._buf = b"" + self._state = "AUTHORIZATION" + self._current_user: str | None = None + self._deleted: set[int] = set() # 0-based indices of DELE'd messages def connection_made(self, transport): self._transport = transport self._peer = transport.get_extra_info("peername", ("?", 0)) _log("connect", src=self._peer[0], src_port=self._peer[1]) - if POP3_BANNER: - if not POP3_BANNER.endswith("\r\n"): - padded_banner = POP3_BANNER + "\r\n" - else: - padded_banner = POP3_BANNER - if not padded_banner.startswith("+OK"): - padded_banner = "+OK " + padded_banner.lstrip("* OK ") # replace IMAP prefix with POP3 - transport.write(padded_banner.encode()) + banner = POP3_BANNER if POP3_BANNER.endswith("\r\n") else POP3_BANNER + "\r\n" + if not banner.startswith("+OK"): + banner = "+OK " + banner + transport.write(banner.encode()) def data_received(self, data): self._buf += data @@ -57,98 +191,216 @@ class POP3Protocol(asyncio.Protocol): line, self._buf = self._buf.split(b"\n", 1) self._handle_line(line.decode(errors="replace").strip()) - def _handle_line(self, line: str): + def connection_lost(self, exc): + _log("disconnect", src=self._peer[0] if self._peer else "?") + + # ── Command dispatch ────────────────────────────────────────────────────── + + def _handle_line(self, line: str) -> None: parts = line.split(None, 1) if not parts: return - cmd = parts[0].upper() + cmd = parts[0].upper() args = parts[1] if len(parts) > 1 else "" - _log("command", src=self._peer[0], cmd=line[:128], state=self._state) + _log("command", src=self._peer[0], cmd=cmd, state=self._state) + # Always available if cmd == "CAPA": - self._transport.write(b"+OK Capability list follows\r\nUSER\r\n.\r\n") - - elif cmd == "USER": - if self._state != "AUTHORIZATION": - self._transport.write(b"-ERR Already authenticated.\r\n") - return - self._current_user = args - self._transport.write(b"+OK User name accepted, password please\r\n") - - elif cmd == "PASS": - if self._state != "AUTHORIZATION": - self._transport.write(b"-ERR Already authenticated.\r\n") - return - if not self._current_user: - self._transport.write(b"-ERR USER required first.\r\n") - return - - password = args - username = self._current_user - - if username in self._valid_users and self._valid_users[username] == password: - self._state = "TRANSACTION" - _log("auth", src=self._peer[0], username=username, password=password, status="success") - self._transport.write(b"+OK Logged in.\r\n") - else: - _log("auth", src=self._peer[0], username=username, password=password, status="failed") - self._transport.write(b"-ERR Authentication failed.\r\n") - self._current_user = None - - elif cmd == "STAT": - if self._state != "TRANSACTION": - self._transport.write(b"-ERR Not authenticated\r\n") - return - total_size = sum(len(e) for e in _BAIT_EMAILS) - self._transport.write(f"+OK {len(_BAIT_EMAILS)} {total_size}\r\n".encode()) - - elif cmd == "LIST": - if self._state != "TRANSACTION": - self._transport.write(b"-ERR Not authenticated\r\n") - return - - if args: - try: - idx = int(args) - 1 - if 0 <= idx < len(_BAIT_EMAILS): - self._transport.write(f"+OK {idx + 1} {len(_BAIT_EMAILS[idx])}\r\n".encode()) - else: - self._transport.write(b"-ERR No such message\r\n") - except ValueError: - self._transport.write(b"-ERR Invalid argument\r\n") - else: - total_size = sum(len(e) for e in _BAIT_EMAILS) - self._transport.write(f"+OK {len(_BAIT_EMAILS)} messages ({total_size} octets)\r\n".encode()) - for i, email in enumerate(_BAIT_EMAILS): - self._transport.write(f"{i + 1} {len(email)}\r\n".encode()) - self._transport.write(b".\r\n") - - elif cmd == "RETR": - if self._state != "TRANSACTION": - self._transport.write(b"-ERR Not authenticated\r\n") - return - try: - idx = int(args) - 1 - if 0 <= idx < len(_BAIT_EMAILS): - email = _BAIT_EMAILS[idx] - self._transport.write(f"+OK {len(email)} octets\r\n".encode()) - self._transport.write(email.encode()) - self._transport.write(b".\r\n") - else: - self._transport.write(b"-ERR No such message\r\n") - except ValueError: - self._transport.write(b"-ERR Invalid argument\r\n") - + self._transport.write( + b"+OK\r\nTOP\r\nUSER\r\nUIDL\r\nRESP-CODES\r\nAUTH-RESP-CODE\r\nSASL\r\n.\r\n" + ) elif cmd == "QUIT": self._transport.write(b"+OK Logging out.\r\n") self._transport.close() - + + # AUTHORIZATION state + elif cmd == "USER": + self._cmd_user(args) + elif cmd == "PASS": + self._cmd_pass(args) + + # TRANSACTION state + elif cmd == "STAT": + self._cmd_stat() + elif cmd == "LIST": + self._cmd_list(args) + elif cmd == "RETR": + self._cmd_retr(args) + elif cmd == "TOP": + self._cmd_top(args) + elif cmd == "UIDL": + self._cmd_uidl(args) + elif cmd == "DELE": + self._cmd_dele(args) + elif cmd == "RSET": + self._cmd_rset() + elif cmd == "NOOP": + self._transport.write(b"+OK\r\n") + else: self._transport.write(b"-ERR Command not recognized\r\n") - def connection_lost(self, exc): - _log("disconnect", src=self._peer[0] if self._peer else "?") + # ── Command implementations ─────────────────────────────────────────────── + + def _cmd_user(self, args: str) -> None: + if self._state != "AUTHORIZATION": + self._transport.write(b"-ERR Already authenticated\r\n") + return + self._current_user = args.strip() + self._transport.write(b"+OK User name accepted, password please\r\n") + + def _cmd_pass(self, args: str) -> None: + if self._state != "AUTHORIZATION": + self._transport.write(b"-ERR Already authenticated\r\n") + return + if not self._current_user: + self._transport.write(b"-ERR USER required first\r\n") + return + username = self._current_user + password = args.strip() + if VALID_USERS.get(username) == password: + self._state = "TRANSACTION" + _log("auth", src=self._peer[0], username=username, password=password, + status="success") + self._transport.write(b"+OK Logged in.\r\n") + else: + _log("auth", src=self._peer[0], username=username, password=password, + status="failed", severity=SEVERITY_WARNING) + self._current_user = None + self._transport.write(b"-ERR Authentication failed.\r\n") + + def _require_transaction(self) -> bool: + if self._state != "TRANSACTION": + self._transport.write(b"-ERR Not authenticated\r\n") + return False + return True + + def _active_messages(self) -> list[tuple[int, str]]: + """Return [(1-based-num, body), ...] excluding DELE'd messages.""" + return [ + (i + 1, body) + for i, body in enumerate(_BAIT_EMAILS) + if i not in self._deleted + ] + + def _cmd_stat(self) -> None: + if not self._require_transaction(): + return + msgs = self._active_messages() + total = sum(len(b.encode()) for _, b in msgs) + self._transport.write(f"+OK {len(msgs)} {total}\r\n".encode()) + + def _cmd_list(self, args: str) -> None: + if not self._require_transaction(): + return + if args: + try: + n = int(args) + idx = n - 1 + if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)): + self._transport.write(b"-ERR No such message\r\n") + else: + size = len(_BAIT_EMAILS[idx].encode()) + self._transport.write(f"+OK {n} {size}\r\n".encode()) + except ValueError: + self._transport.write(b"-ERR Invalid argument\r\n") + else: + msgs = self._active_messages() + total = sum(len(b.encode()) for _, b in msgs) + self._transport.write(f"+OK {len(msgs)} messages ({total} octets)\r\n".encode()) + for n, body in msgs: + self._transport.write(f"{n} {len(body.encode())}\r\n".encode()) + self._transport.write(b".\r\n") + + def _cmd_retr(self, args: str) -> None: + if not self._require_transaction(): + return + try: + n = int(args) + idx = n - 1 + if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)): + self._transport.write(b"-ERR No such message\r\n") + return + body = _BAIT_EMAILS[idx] + raw = body.encode() + _log("retr", src=self._peer[0], message_num=n) + self._transport.write(f"+OK {len(raw)} octets\r\n".encode()) + self._transport.write(raw) + if not raw.endswith(b"\r\n"): + self._transport.write(b"\r\n") + self._transport.write(b".\r\n") + except ValueError: + self._transport.write(b"-ERR Invalid argument\r\n") + + def _cmd_top(self, args: str) -> None: + if not self._require_transaction(): + return + try: + parts = args.split(None, 1) + n = int(parts[0]) + line_count = int(parts[1]) if len(parts) > 1 else 0 + idx = n - 1 + if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)): + self._transport.write(b"-ERR No such message\r\n") + return + body = _BAIT_EMAILS[idx] + sep = "\r\n\r\n" + if sep in body: + headers, rest = body.split(sep, 1) + headers += sep + else: + headers, rest = body, "" + body_lines = rest.split("\r\n")[:line_count] + result = headers + "\r\n".join(body_lines) + self._transport.write(b"+OK\r\n") + self._transport.write(result.encode()) + if not result.endswith("\r\n"): + self._transport.write(b"\r\n") + self._transport.write(b".\r\n") + except (ValueError, IndexError): + self._transport.write(b"-ERR Invalid arguments\r\n") + + def _cmd_uidl(self, args: str) -> None: + if not self._require_transaction(): + return + if args: + try: + n = int(args) + idx = n - 1 + if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)): + self._transport.write(b"-ERR No such message\r\n") + else: + self._transport.write(f"+OK {n} msg-{n}\r\n".encode()) + except ValueError: + self._transport.write(b"-ERR Invalid argument\r\n") + else: + self._transport.write(b"+OK\r\n") + for n, _ in self._active_messages(): + self._transport.write(f"{n} msg-{n}\r\n".encode()) + self._transport.write(b".\r\n") + + def _cmd_dele(self, args: str) -> None: + if not self._require_transaction(): + return + try: + n = int(args) + idx = n - 1 + if idx in self._deleted or not (0 <= idx < len(_BAIT_EMAILS)): + self._transport.write(b"-ERR No such message\r\n") + else: + self._deleted.add(idx) + _log("delete", src=self._peer[0], message_num=n) + self._transport.write(f"+OK Message {n} deleted\r\n".encode()) + except ValueError: + self._transport.write(b"-ERR Invalid argument\r\n") + + def _cmd_rset(self) -> None: + if not self._require_transaction(): + return + self._deleted.clear() + self._transport.write(b"+OK\r\n") + async def main(): _log("startup", msg=f"POP3 server starting as {NODE_NAME}") @@ -157,5 +409,6 @@ async def main(): async with server: await server.serve_forever() + if __name__ == "__main__": asyncio.run(main()) diff --git a/tests/service_testing/test_imap.py b/tests/service_testing/test_imap.py index 9b655c7..f376dcd 100644 --- a/tests/service_testing/test_imap.py +++ b/tests/service_testing/test_imap.py @@ -1,7 +1,10 @@ """ Tests for templates/imap/server.py -Exercises IMAP state machine, auth, and negative tests. +Exercises the full IMAP4rev1 state machine: + NOT_AUTHENTICATED → AUTHENTICATED → SELECTED + +Uses asyncio Protocol directly — no network socket needed. """ import importlib.util @@ -12,6 +15,8 @@ from unittest.mock import MagicMock, patch import pytest +# ── Helpers ─────────────────────────────────────────────────────────────────── + def _make_fake_decnet_logging() -> ModuleType: mod = ModuleType("decnet_logging") mod.syslog_line = MagicMock(return_value="") @@ -21,11 +26,13 @@ def _make_fake_decnet_logging() -> ModuleType: mod.SEVERITY_INFO = 6 return mod + def _load_imap(): + """Import imap server module, injecting a stub decnet_logging.""" env = { "NODE_NAME": "testhost", "IMAP_USERS": "admin:admin123,root:toor", - "IMAP_BANNER": "* OK [testhost] Dovecot ready." + "IMAP_BANNER": "* OK [testhost] Dovecot ready.", } for key in list(sys.modules): if key in ("imap_server", "decnet_logging"): @@ -33,13 +40,17 @@ def _load_imap(): sys.modules["decnet_logging"] = _make_fake_decnet_logging() - spec = importlib.util.spec_from_file_location("imap_server", "templates/imap/server.py") + spec = importlib.util.spec_from_file_location( + "imap_server", "templates/imap/server.py" + ) mod = importlib.util.module_from_spec(spec) with patch.dict("os.environ", env, clear=False): spec.loader.exec_module(mod) return mod + def _make_protocol(mod): + """Return (protocol, transport, written). Banner already cleared.""" proto = mod.IMAPProtocol() transport = MagicMock() written: list[bytes] = [] @@ -48,42 +59,270 @@ def _make_protocol(mod): written.clear() return proto, transport, written + def _send(proto, data: str) -> None: proto.data_received(data.encode() + b"\r\n") + +def _replies(written: list[bytes]) -> bytes: + return b"".join(written) + + +def _login(proto, written): + _send(proto, "A0 LOGIN admin admin123") + written.clear() + + +def _select_inbox(proto, written): + _send(proto, "B0 SELECT INBOX") + written.clear() + + @pytest.fixture def imap_mod(): return _load_imap() + +# ── Tests: banner & unauthenticated ────────────────────────────────────────── + +def test_imap_banner_on_connect(imap_mod): + proto = imap_mod.IMAPProtocol() + transport = MagicMock() + written: list[bytes] = [] + transport.write.side_effect = written.append + proto.connection_made(transport) + banner = b"".join(written) + assert banner.startswith(b"* OK") + + +def test_imap_capability_contains_idle_and_literal_plus(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _send(proto, "C1 CAPABILITY") + resp = _replies(written) + assert b"IMAP4rev1" in resp + assert b"IDLE" in resp + assert b"LITERAL+" in resp + assert b"AUTH=PLAIN" in resp + + def test_imap_login_success(imap_mod): - proto, transport, written = _make_protocol(imap_mod) - _send(proto, 'A1 LOGIN admin admin123') - assert b"A1 OK" in b"".join(written) + proto, _, written = _make_protocol(imap_mod) + _send(proto, "A1 LOGIN admin admin123") + assert b"A1 OK" in _replies(written) assert proto._state == "AUTHENTICATED" + def test_imap_login_fail(imap_mod): - proto, transport, written = _make_protocol(imap_mod) - _send(proto, 'A1 LOGIN admin wrongpass') - assert b"A1 NO" in b"".join(written) + proto, _, written = _make_protocol(imap_mod) + _send(proto, "A1 LOGIN admin wrongpass") + resp = _replies(written) + assert b"A1 NO" in resp + assert b"AUTHENTICATIONFAILED" in resp assert proto._state == "NOT_AUTHENTICATED" -def test_imap_select_before_auth(imap_mod): + +def test_imap_bad_creds_connection_stays_open(imap_mod): proto, transport, written = _make_protocol(imap_mod) - _send(proto, 'A2 SELECT INBOX') - assert b"A2 BAD" in b"".join(written) + _send(proto, "T1 LOGIN admin wrongpass") + transport.close.assert_not_called() + + +def test_imap_retry_after_bad_credentials_succeeds(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _send(proto, "T1 LOGIN admin wrongpass") + written.clear() + _send(proto, "T2 LOGIN admin admin123") + assert b"T2 OK" in _replies(written) + assert proto._state == "AUTHENTICATED" + + +def test_imap_select_before_auth_returns_bad(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _send(proto, "A2 SELECT INBOX") + assert b"A2 BAD" in _replies(written) + + +def test_imap_noop_unauthenticated_returns_ok(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _send(proto, "N1 NOOP") + assert b"N1 OK" in _replies(written) + + +def test_imap_unknown_command_returns_bad(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _send(proto, "X1 INVALID_COMMAND") + assert b"X1 BAD" in _replies(written) + + +# ── Tests: authenticated state ──────────────────────────────────────────────── + +def test_imap_list_returns_four_mailboxes(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _send(proto, 'L1 LIST "" "*"') + resp = _replies(written) + assert b"INBOX" in resp + assert b"Sent" in resp + assert b"Drafts" in resp + assert b"Archive" in resp + assert b"LIST completed" in resp + + +def test_imap_lsub_mirrors_list(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _send(proto, 'L2 LSUB "" "*"') + resp = _replies(written) + assert b"INBOX" in resp + assert b"LSUB completed" in resp + + +def test_imap_status_inbox_messages(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _send(proto, "S0 STATUS INBOX (MESSAGES)") + resp = _replies(written) + assert b"STATUS INBOX" in resp + assert b"MESSAGES 10" in resp + + +# ── Tests: SELECTED state ───────────────────────────────────────────────────── + +def test_imap_select_inbox_exists_count(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _send(proto, "S1 SELECT INBOX") + resp = _replies(written) + assert b"* 10 EXISTS" in resp + + +def test_imap_select_inbox_uidnext(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _send(proto, "S1 SELECT INBOX") + resp = _replies(written) + assert b"UIDNEXT 11" in resp + + +def test_imap_select_inbox_read_write(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _send(proto, "S1 SELECT INBOX") + resp = _replies(written) + assert b"READ-WRITE" in resp + + +def test_imap_examine_inbox_read_only(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _send(proto, "S2 EXAMINE INBOX") + resp = _replies(written) + assert b"READ-ONLY" in resp + + +def test_imap_search_all_returns_all_seqs(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "Q1 SEARCH ALL") + resp = _replies(written) + assert b"* SEARCH 1 2 3 4 5 6 7 8 9 10" in resp + + +def test_imap_fetch_single_body_aws_key(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "F1 FETCH 1 BODY[]") + resp = _replies(written) + assert b"AKIAIOSFODNN7EXAMPLE" in resp + assert b"F1 OK" in resp + def test_imap_fetch_after_select(imap_mod): - proto, transport, written = _make_protocol(imap_mod) - _send(proto, 'A1 LOGIN admin admin123') + proto, _, written = _make_protocol(imap_mod) + _send(proto, "A1 LOGIN admin admin123") written.clear() - _send(proto, 'A2 SELECT INBOX') + _send(proto, "A2 SELECT INBOX") written.clear() - _send(proto, 'A3 FETCH 1 RFC822') - combined = b"".join(written) + _send(proto, "A3 FETCH 1 RFC822") + combined = _replies(written) assert b"A3 OK" in combined assert b"AKIAIOSFODNN7EXAMPLE" in combined -def test_imap_invalid_command(imap_mod): + +def test_imap_fetch_msg5_root_password(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "F2 FETCH 5 BODY[]") + resp = _replies(written) + assert b"r00tM3T00!" in resp + + +def test_imap_fetch_range_flags_envelope_count(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "F3 FETCH 1:3 (FLAGS ENVELOPE)") + resp = _replies(written) + assert b"* 1 FETCH" in resp + assert b"* 2 FETCH" in resp + assert b"* 3 FETCH" in resp + assert b"FETCH completed" in resp + + +def test_imap_fetch_star_rfc822size_10_responses(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "F4 FETCH 1:* RFC822.SIZE") + resp = _replies(written).decode(errors="replace") + assert resp.count(" FETCH ") >= 10 + assert "F4 OK" in resp + + +def test_imap_uid_fetch_includes_uid_field(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "U1 UID FETCH 1:10 (FLAGS)") + resp = _replies(written) + assert b"UID 1" in resp + assert b"FETCH completed" in resp + + +def test_imap_close_returns_to_authenticated(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "C1 CLOSE") + resp = _replies(written) + assert b"CLOSE completed" in resp + assert proto._state == "AUTHENTICATED" + + +def test_imap_fetch_after_close_returns_bad(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _login(proto, written) + _select_inbox(proto, written) + _send(proto, "C1 CLOSE") + written.clear() + _send(proto, "C2 FETCH 1 FLAGS") + assert b"C2 BAD" in _replies(written) + + +def test_imap_logout_sends_bye_and_closes(imap_mod): proto, transport, written = _make_protocol(imap_mod) - _send(proto, 'A1 INVALID') - assert b"A1 BAD" in b"".join(written) + _login(proto, written) + _send(proto, "L1 LOGOUT") + resp = _replies(written) + assert b"* BYE" in resp + assert b"LOGOUT completed" in resp + transport.close.assert_called_once() + + +def test_imap_invalid_command(imap_mod): + proto, _, written = _make_protocol(imap_mod) + _send(proto, "A1 INVALID") + assert b"A1 BAD" in _replies(written) diff --git a/tests/service_testing/test_pop3.py b/tests/service_testing/test_pop3.py index 337f467..cde8a93 100644 --- a/tests/service_testing/test_pop3.py +++ b/tests/service_testing/test_pop3.py @@ -1,7 +1,10 @@ """ Tests for templates/pop3/server.py -Exercises POP3 state machine, auth, and negative tests. +Exercises the full POP3 state machine: + AUTHORIZATION → TRANSACTION + +Uses asyncio Protocol directly — no network socket needed. """ import importlib.util @@ -12,6 +15,8 @@ from unittest.mock import MagicMock, patch import pytest +# ── Helpers ─────────────────────────────────────────────────────────────────── + def _make_fake_decnet_logging() -> ModuleType: mod = ModuleType("decnet_logging") mod.syslog_line = MagicMock(return_value="") @@ -21,11 +26,12 @@ def _make_fake_decnet_logging() -> ModuleType: mod.SEVERITY_INFO = 6 return mod + def _load_pop3(): env = { "NODE_NAME": "testhost", "IMAP_USERS": "admin:admin123,root:toor", - "IMAP_BANNER": "+OK [testhost] Dovecot ready." + "IMAP_BANNER": "+OK [testhost] Dovecot ready.", } for key in list(sys.modules): if key in ("pop3_server", "decnet_logging"): @@ -33,13 +39,17 @@ def _load_pop3(): sys.modules["decnet_logging"] = _make_fake_decnet_logging() - spec = importlib.util.spec_from_file_location("pop3_server", "templates/pop3/server.py") + spec = importlib.util.spec_from_file_location( + "pop3_server", "templates/pop3/server.py" + ) mod = importlib.util.module_from_spec(spec) with patch.dict("os.environ", env, clear=False): spec.loader.exec_module(mod) return mod + def _make_protocol(mod): + """Return (protocol, transport, written). Banner already cleared.""" proto = mod.POP3Protocol() transport = MagicMock() written: list[bytes] = [] @@ -48,51 +58,229 @@ def _make_protocol(mod): written.clear() return proto, transport, written + def _send(proto, data: str) -> None: proto.data_received(data.encode() + b"\r\n") + +def _replies(written: list[bytes]) -> bytes: + return b"".join(written) + + +def _login(proto, written): + _send(proto, "USER admin") + _send(proto, "PASS admin123") + written.clear() + + @pytest.fixture def pop3_mod(): return _load_pop3() + +# ── Tests: banner & unauthenticated ────────────────────────────────────────── + +def test_pop3_banner_starts_with_ok(pop3_mod): + proto = pop3_mod.POP3Protocol() + transport = MagicMock() + written: list[bytes] = [] + transport.write.side_effect = written.append + proto.connection_made(transport) + banner = b"".join(written) + assert banner.startswith(b"+OK") + + +def test_pop3_capa_contains_top_uidl_user(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "CAPA") + resp = _replies(written) + assert b"TOP" in resp + assert b"UIDL" in resp + assert b"USER" in resp + + def test_pop3_login_success(pop3_mod): - proto, transport, written = _make_protocol(pop3_mod) - _send(proto, 'USER admin') - assert b"+OK" in b"".join(written) + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "USER admin") + assert b"+OK" in _replies(written) written.clear() - _send(proto, 'PASS admin123') - assert b"+OK Logged in" in b"".join(written) + _send(proto, "PASS admin123") + assert b"+OK Logged in" in _replies(written) assert proto._state == "TRANSACTION" + def test_pop3_login_fail(pop3_mod): - proto, transport, written = _make_protocol(pop3_mod) - _send(proto, 'USER admin') + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "USER admin") written.clear() - _send(proto, 'PASS wrongpass') - assert b"-ERR" in b"".join(written) + _send(proto, "PASS wrongpass") + assert b"-ERR" in _replies(written) assert proto._state == "AUTHORIZATION" -def test_pop3_pass_before_user(pop3_mod): + +def test_pop3_bad_pass_connection_stays_open(pop3_mod): proto, transport, written = _make_protocol(pop3_mod) - _send(proto, 'PASS admin123') - assert b"-ERR" in b"".join(written) + _send(proto, "USER admin") + _send(proto, "PASS wrongpass") + transport.close.assert_not_called() + + +def test_pop3_retry_after_bad_pass_succeeds(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "USER admin") + _send(proto, "PASS wrongpass") + written.clear() + _send(proto, "USER admin") + _send(proto, "PASS admin123") + assert b"+OK Logged in" in _replies(written) + + +def test_pop3_pass_before_user(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "PASS admin123") + assert b"-ERR" in _replies(written) + def test_pop3_stat_before_auth(pop3_mod): - proto, transport, written = _make_protocol(pop3_mod) - _send(proto, 'STAT') - assert b"-ERR" in b"".join(written) + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "STAT") + assert b"-ERR" in _replies(written) -def test_pop3_retr_after_auth(pop3_mod): - proto, transport, written = _make_protocol(pop3_mod) - _send(proto, 'USER admin') - _send(proto, 'PASS admin123') + +def test_pop3_retr_before_auth(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "RETR 1") + assert b"-ERR" in _replies(written) + + +def test_pop3_invalid_command(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "INVALID") + assert b"-ERR" in _replies(written) + + +# ── Tests: TRANSACTION state ────────────────────────────────────────────────── + +def test_pop3_stat_10_messages(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "STAT") + resp = _replies(written).decode() + assert resp.startswith("+OK 10 ") + + +def test_pop3_list_returns_10_entries(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "LIST") + resp = _replies(written).decode() + assert resp.startswith("+OK 10") + # Count individual message lines: "N size\r\n" + entries = [l for l in resp.split("\r\n") if l and l[0].isdigit()] + assert len(entries) == 10 + + +def test_pop3_retr_after_auth_msg1(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _send(proto, "USER admin") + _send(proto, "PASS admin123") written.clear() - _send(proto, 'RETR 1') - combined = b"".join(written) + _send(proto, "RETR 1") + combined = _replies(written) assert b"+OK" in combined assert b"AKIAIOSFODNN7EXAMPLE" in combined -def test_pop3_invalid_command(pop3_mod): + +def test_pop3_retr_msg5_root_password(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "RETR 5") + resp = _replies(written) + assert b"+OK" in resp + assert b"r00tM3T00!" in resp + + +def test_pop3_top_returns_headers_plus_lines(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "TOP 1 3") + resp = _replies(written).decode(errors="replace") + assert resp.startswith("+OK") + # Headers must be present + assert "From:" in resp + assert "Subject:" in resp + # Should NOT contain body content beyond 3 lines — but 3 lines of the + # AWS email body are enough to include the access key + assert ".\r\n" in resp + + +def test_pop3_top_3_body_lines_count(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + # Message 1 body after blank line: + # "Team,\r\n", "\r\n", "New AWS credentials...\r\n", ... + _send(proto, "TOP 1 3") + resp = _replies(written).decode(errors="replace") + # Strip headers up to blank line + parts = resp.split("\r\n\r\n", 1) + assert len(parts) == 2 + body_section = parts[1].rstrip("\r\n.") + body_lines = [l for l in body_section.split("\r\n") if l != "."] + assert len(body_lines) <= 3 + + +def test_pop3_uidl_returns_10_entries(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "UIDL") + resp = _replies(written).decode() + assert resp.startswith("+OK") + entries = [l for l in resp.split("\r\n") if l and l[0].isdigit()] + assert len(entries) == 10 + + +def test_pop3_uidl_format_msg_n(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "UIDL") + resp = _replies(written).decode() + assert "1 msg-1" in resp + assert "5 msg-5" in resp + + +def test_pop3_dele_removes_message(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "DELE 3") + resp = _replies(written) + assert b"+OK" in resp + assert 2 in proto._deleted # 0-based + + +def test_pop3_rset_clears_deletions(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "DELE 1") + _send(proto, "DELE 2") + written.clear() + _send(proto, "RSET") + resp = _replies(written) + assert b"+OK" in resp + assert len(proto._deleted) == 0 + + +def test_pop3_dele_then_stat_decrements_count(pop3_mod): + proto, _, written = _make_protocol(pop3_mod) + _login(proto, written) + _send(proto, "DELE 1") + written.clear() + _send(proto, "STAT") + resp = _replies(written).decode() + assert resp.startswith("+OK 9 ") + + +def test_pop3_quit_closes_connection(pop3_mod): proto, transport, written = _make_protocol(pop3_mod) - _send(proto, 'INVALID') - assert b"-ERR" in b"".join(written) + _login(proto, written) + _send(proto, "QUIT") + transport.close.assert_called_once()