anti/DECNET
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(imap,pop3): full IMAP4rev1 + POP3 bait mailbox implementation

Browse Source 
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.
This commit is contained in:
anti
2026-04-11 03:12:32 -04:00
parent 1196363d0b
commit c7713c6228
5 changed files with 1326 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

560
templates/imap/server.py
View File

@@ -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 <devops@company.internal>\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 <monitoring@company.internal>\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 <noreply@github.com>\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 <admin@company.internal>\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 <sysadmin@company.internal>\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 <backup@company.internal>\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 <alerts@company.internal>\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 <vendor@external.com>\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 <helpdesk@company.internal>\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 <noreply@aws.amazon.com>\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():

467
templates/pop3/server.py
View File

@@ -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 <devops@company.internal>\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 <monitoring@company.internal>\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 <noreply@github.com>\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 <admin@company.internal>\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 <sysadmin@company.internal>\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 <backup@company.internal>\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 <alerts@company.internal>\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 <vendor@external.com>\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 <helpdesk@company.internal>\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 <noreply@aws.amazon.com>\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())