From 14ba7fcf6f20f1623e61eb978cd9903979c33224 Mon Sep 17 00:00:00 2001 From: Danang Avan Maulana Date: Sat, 31 Oct 2026 04:33:18 +0700 Subject: [PATCH] feat(report-inbox): report mailbox that credits forwarded reports automatically Staff forward a suspicious email to a configured report mailbox (e.g. lapor@acme.test). The poller reads it alongside the reply mailbox, pulls the original sender and subject out of inline, attached or HTML-only forwards, and feeds the report inbox, so reporting a simulation now raises the campaign's report rate without a trainer recording it by hand. - live config: report_imap_user / report_imap_password (masked); rejected when equal to the reply mailbox, since replies would count as reports. - GET /report-inbox/mailbox and POST /report-inbox/poll for staff; POST /live/poll now polls both mailboxes. - Classification prefers the newest matching campaign the reporter actually received and has not reported yet, so campaigns that reuse a sender or subject credit the right one. - Mailbox-path reports are filed under the campaign's (or reporter's) org. - Report inbox page shows the address and a "check now" button. Co-Authored-By: Claude Opus 5.5 --- backend/routes/live.py | 24 ++- backend/routes/report_inbox.py | 18 ++- backend/services/live/inbound.py | 132 ++++++++++++++- backend/services/report_inbox.py | 54 +++++-- backend/tests/test_report_mailbox.py | 222 ++++++++++++++++++++++++++ docs/api.md | 4 +- docs/live-campaign-walkthrough.md | 3 + docs/user-guide.md | 13 +- frontend/src/pages/ReportInboxPage.js | 45 +++++- frontend/src/pages/SettingsPage.js | 4 + 10 files changed, 488 insertions(+), 31 deletions(-) create mode 100644 backend/tests/test_report_mailbox.py diff --git a/backend/routes/live.py b/backend/routes/live.py index 25824a9..23a1c7c 100644 --- a/backend/routes/live.py +++ b/backend/routes/live.py @@ -646,6 +646,9 @@ async def set_kill_switch(data: KillSwitchRequest, current_user: User = Depends( # ==================== GOPHISH CONFIG (admin) ==================== +_SECRETS = ("gophish_api_key", "smtp_password", "imap_password", "report_imap_password") + + class LiveConfig(BaseModel): model_config = {"extra": "forbid"} gophish_base_url: str = Field(min_length=1, max_length=300) @@ -666,6 +669,10 @@ class LiveConfig(BaseModel): imap_ssl: bool = True imap_user: str = "" imap_password: str = "" + # Report mailbox on the same IMAP server: staff forward suspicious mail here + # and reporters of our simulations are credited automatically. + report_imap_user: str = Field(default="", max_length=200) + report_imap_password: str = "" @router.get("/config") @@ -674,7 +681,7 @@ async def get_config(current_user: User = Depends(require_admin)): if not config: return None # Never return stored secrets - for secret in ("gophish_api_key", "smtp_password", "imap_password"): + for secret in _SECRETS: if config.get(secret): config[secret] = "***" return config @@ -682,10 +689,11 @@ async def get_config(current_user: User = Depends(require_admin)): @router.post("/poll") async def poll_inbox(current_user: User = Depends(require_admin)): - """Fetch and route inbound replies now. The poller also runs on a timer.""" - from services.live.inbound import poll_once + """Fetch and route inbound replies and forwarded reports now. The poller + also runs on a timer.""" + from services.live.inbound import poll_once, poll_reports_once - return await poll_once() + return {"replies": await poll_once(), "reports": await poll_reports_once()} @router.put("/config") @@ -694,9 +702,15 @@ async def set_config(data: LiveConfig, current_user: User = Depends(require_admi # field (e.g. an older client without the IMAP-SSL toggle) does not reset it # to the model default. doc = {"id": "live_config", **data.model_dump(exclude_unset=True)} + report_box = (doc.get("report_imap_user") or "").strip().lower() + if report_box and report_box == (doc.get("imap_user") or "").strip().lower(): + # Replies would then be counted as reports. + raise HTTPException( + status_code=400, detail="Report mailbox must differ from the reply mailbox" + ) # A resubmitted mask ("***") means "keep the stored secret", not overwrite it. existing = await db.live_config.find_one({"id": "live_config"}, {"_id": 0}) - for secret in ("gophish_api_key", "smtp_password", "imap_password"): + for secret in _SECRETS: if doc.get(secret) in ("", "***") and existing: doc[secret] = existing.get(secret, "") await db.live_config.update_one({"id": "live_config"}, {"$set": doc}, upsert=True) diff --git a/backend/routes/report_inbox.py b/backend/routes/report_inbox.py index 15c0aad..00f41ac 100644 --- a/backend/routes/report_inbox.py +++ b/backend/routes/report_inbox.py @@ -43,6 +43,22 @@ async def report_leaderboard(user: User = Depends(require_trainer)): return await report_inbox.leaderboard(_scope(user)) +@router.get("/mailbox") +async def report_mailbox(user: User = Depends(require_trainer)): + """The address staff forward suspicious mail to, if a report mailbox is set up.""" + config = await db.live_config.find_one({"id": "live_config"}, {"_id": 0}) or {} + address = (config.get("report_imap_user") or "").strip().lower() + return {"address": address or None, "configured": bool(address and config.get("imap_host"))} + + +@router.post("/poll") +async def poll_report_mailbox(user: User = Depends(require_trainer)): + """Fetch forwarded reports now instead of waiting for the next poller tick.""" + from services.live.inbound import poll_reports_once + + return await poll_reports_once() + + class ReportIn(BaseModel): reporter_email: str = Field(min_length=3, max_length=320) subject: str = Field(default="", max_length=400) @@ -52,7 +68,7 @@ class ReportIn(BaseModel): @router.post("/ingest", status_code=201) async def ingest(body: ReportIn, user: User = Depends(require_trainer)): - """Record a reported message (the integration point the mail poller also uses).""" + """Record a reported message by hand (the report mailbox poller feeds the same path).""" org_id = None if user.role == "admin" else user.organization_id report = await report_inbox.ingest_report( org_id, body.reporter_email, body.subject, body.from_address, body.body diff --git a/backend/services/live/inbound.py b/backend/services/live/inbound.py index b3dc28e..b4a353f 100644 --- a/backend/services/live/inbound.py +++ b/backend/services/live/inbound.py @@ -1,16 +1,23 @@ """ -IMAP poller for live-campaign replies (P3 plumbing). +IMAP pollers for live campaigns: recipient replies (P3 plumbing) and the +report mailbox staff forward suspicious mail to. A recipient's reply arrives at the Reply-To address `+@`. The poller reads the mailbox, maps the token to a campaign, matches the recipient by the reply's From address, strips quoted history, and hands the fresh text to the conversation engine. +The report mailbox is a second inbox (e.g. lapor@acme.test). Every message in +it is a forwarded report: it is parsed for the original sender and subject and +handed to the report inbox, which credits the reporter when it is one of our +simulations — the behaviour report rate measures. + Pure parsing (token, body, sender) is separated from IMAP I/O so it can be tested without a server. """ import asyncio +import html import imaplib import logging import re @@ -18,6 +25,7 @@ from email.message import Message from email.utils import parseaddr +from services import report_inbox from services.ai_gateway import AIGateway from services.database import db from services.live import conversation @@ -34,6 +42,13 @@ re.compile(r"^\s*_{5,}\s*$"), ) +# Header lines inside an inline-forwarded message (Gmail, Outlook, Thunderbird; EN/ID). +_FWD_FROM_RE = re.compile(r"^\s*\*?(?:From|Dari)\s*:\*?\s*(.+)$", re.IGNORECASE | re.MULTILINE) +_FWD_SUBJECT_RE = re.compile( + r"^\s*\*?(?:Subject|Subjek|Perihal)\s*:\*?\s*(.+)$", re.IGNORECASE | re.MULTILINE +) +_TAG_RE = re.compile(r"<[^>]+>") + def parse_token(*header_values: str | None) -> str | None: """Extract the campaign token from any plus-addressed recipient header.""" @@ -82,6 +97,56 @@ def extract_body(msg: Message) -> str: return payload.decode(msg.get_content_charset() or "utf-8", "replace") +def _text_of(msg: Message) -> str: + """Plain text of a message, falling back to tag-stripped HTML.""" + html_text = "" + for part in msg.walk(): + ctype = part.get_content_type() + if ctype not in ("text/plain", "text/html") or "attachment" in str( + part.get("Content-Disposition", "") + ): + continue + payload = part.get_payload(decode=True) + if not payload: + continue + text = payload.decode(part.get_content_charset() or "utf-8", "replace") + if ctype == "text/plain": + return text + html_text = html_text or html.unescape(_TAG_RE.sub("\n", text)) + return html_text + + +def parse_report(raw: bytes) -> dict | None: + """Pull the reporter and the reported message out of one forwarded email. + + Handles "forward as attachment" (a message/rfc822 part) and inline + forwards, where the original From/Subject appear as lines in the body. + """ + msg = message_from_bytes(raw) + reporter = sender_address(msg.get("From")) + if not reporter: + return None + for part in msg.walk(): + if part.get_content_type() == "message/rfc822": + inner = part.get_payload(0) if part.is_multipart() else None + if isinstance(inner, Message): + return { + "reporter_email": reporter, + "subject": str(inner.get("Subject") or msg.get("Subject") or ""), + "from_address": sender_address(inner.get("From")) or "", + "body": _text_of(inner), + } + body = _text_of(msg) + fwd_from = _FWD_FROM_RE.search(body) + fwd_subject = _FWD_SUBJECT_RE.search(body) + return { + "reporter_email": reporter, + "subject": fwd_subject.group(1).strip() if fwd_subject else str(msg.get("Subject") or ""), + "from_address": sender_address(fwd_from.group(1)) if fwd_from else "", + "body": body, + } + + async def route_message(raw: bytes, gateway=None) -> dict: """Parse one raw RFC822 message and dispatch it to the conversation engine.""" msg = message_from_bytes(raw) @@ -125,7 +190,9 @@ async def route_message(raw: bytes, gateway=None) -> dict: # ── IMAP I/O ───────────────────────────────────────────────────────── -def _fetch_new(config: dict, last_uid: int, last_uidvalidity: int) -> tuple[list[bytes], int, int]: +def _fetch_new( + config: dict, user: str, password: str, last_uid: int, last_uidvalidity: int +) -> tuple[list[bytes], int, int]: """Blocking IMAP fetch of messages with UID greater than the watermark. Returns (raw messages, current UIDVALIDITY, highest UID fetched). Runs in a thread.""" host, _, port = config["imap_host"].partition(":") @@ -135,7 +202,7 @@ def _fetch_new(config: dict, last_uid: int, last_uidvalidity: int) -> tuple[list else imaplib.IMAP4(host, int(port or 143)) ) try: - conn.login(config["imap_user"], config.get("imap_password", "")) + conn.login(user, password) conn.select("INBOX") # Track by UID, not the \Seen flag: a human reading the mailbox (e.g. in # Thunderbird) marks replies seen, which an UNSEEN search would then skip. @@ -175,7 +242,12 @@ async def poll_once() -> dict: state = await db.live_state.find_one({"id": "imap_watermark"}, {"_id": 0}) or {} try: raws, uidvalidity, max_uid = await asyncio.to_thread( - _fetch_new, config, int(state.get("last_uid", 0)), int(state.get("uidvalidity", 0)) + _fetch_new, + config, + config["imap_user"], + config.get("imap_password", ""), + int(state.get("last_uid", 0)), + int(state.get("uidvalidity", 0)), ) except Exception as exc: logger.warning(f"IMAP poll failed: {exc}") @@ -203,14 +275,58 @@ async def poll_once() -> dict: return {"polled": len(raws), "outcomes": outcomes} +async def poll_reports_once() -> dict: + """Fetch forwarded reports from the report mailbox and credit the reporters.""" + config = await db.live_config.find_one({"id": "live_config"}, {"_id": 0}) + mailbox = ((config or {}).get("report_imap_user") or "").strip().lower() + if not config or not config.get("imap_host") or not mailbox: + return {"polled": 0, "reason": "report_mailbox_not_configured"} + + state = await db.live_state.find_one({"id": "report_imap_watermark"}, {"_id": 0}) or {} + try: + raws, uidvalidity, max_uid = await asyncio.to_thread( + _fetch_new, + config, + mailbox, + config.get("report_imap_password", ""), + int(state.get("last_uid", 0)), + int(state.get("uidvalidity", 0)), + ) + except Exception as exc: + logger.warning(f"report mailbox poll failed: {exc}") + return {"polled": 0, "error": str(exc)} + + outcomes: dict[str, int] = {} + for raw in raws: + try: + parsed = parse_report(raw) + if not parsed or parsed["reporter_email"] == mailbox: + status = "skipped" + else: + report = await report_inbox.ingest_report(None, **parsed) + status = "credited" if report["credited"] else report["verdict"] + except Exception as exc: + logger.warning(f"ingesting a forwarded report failed: {exc}") + status = "ingest_error" + outcomes[status] = outcomes.get(status, 0) + 1 + + await db.live_state.update_one( + {"id": "report_imap_watermark"}, + {"$set": {"last_uid": max_uid, "uidvalidity": uidvalidity}}, + upsert=True, + ) + return {"polled": len(raws), "outcomes": outcomes} + + async def run_poller(interval_seconds: int = 30) -> None: """Background loop, always running. poll_once is a no-op until IMAP is configured, so saving the config in Settings takes effect on the next tick without a restart.""" logger.info("Live reply poller started") while True: - try: - await poll_once() - except Exception as exc: - logger.warning(f"poller iteration error: {exc}") + for poll in (poll_once, poll_reports_once): + try: + await poll() + except Exception as exc: + logger.warning(f"poller iteration error: {exc}") await asyncio.sleep(interval_seconds) diff --git a/backend/services/report_inbox.py b/backend/services/report_inbox.py index 14d79ee..3e11360 100644 --- a/backend/services/report_inbox.py +++ b/backend/services/report_inbox.py @@ -39,28 +39,50 @@ def _clean_subject(subject: str) -> str: async def classify( - org_scope: dict, subject: str, from_address: str, body: str + org_scope: dict, subject: str, from_address: str, body: str, reporter_email: str = "" ) -> tuple[str, str | None]: """Decide whether a reported message is one of our simulations. Matches by the campaign's sender address (in the From or anywhere in the - forwarded body) or by an exact subject match. Returns (verdict, campaign_id). + forwarded body) or by an exact subject match. Campaigns often reuse a + sender, so among matches the newest one the reporter actually received + wins (preferring one they have not been credited for yet). + Returns (verdict, campaign_id). """ clean_subj = _clean_subject(subject) from_addr = (from_address or "").strip().lower() body_l = (body or "").lower() + matches: list[str] = [] async for c in db.live_campaigns.find( {**org_scope, "status": {"$in": list(_SENT_STATUSES)}}, {"_id": 0, "id": 1, "sender_email": 1, "subject": 1}, - ): + ).sort("created_at", -1): sender = (c.get("sender_email") or "").strip().lower() - if sender and (sender == from_addr or sender in body_l): - return "simulation", c["id"] csubj = (c.get("subject") or "").strip().lower() - if csubj and clean_subj and csubj == clean_subj: - return "simulation", c["id"] - return "needs_review", None + if (sender and (sender == from_addr or sender in body_l)) or ( + csubj and clean_subj and csubj == clean_subj + ): + matches.append(c["id"]) + if not matches: + return "needs_review", None + + email = (reporter_email or "").strip().lower() + if email: + received = { + r["campaign_id"]: r.get("reported", False) + async for r in db.live_recipients.find( + {"campaign_id": {"$in": matches}, "email": email}, + {"_id": 0, "campaign_id": 1, "reported": 1}, + ) + } + for cid in matches: + if cid in received and not received[cid]: + return "simulation", cid + for cid in matches: + if cid in received: + return "simulation", cid + return "simulation", matches[0] async def credit_reporter(campaign_id: str, reporter_email: str) -> bool: @@ -103,13 +125,25 @@ async def ingest_report( """Store one reported message and, if it is ours, credit the reporter.""" org_scope = {} if org_id is None else {"organization_id": org_id} redacted, _ = scrub(body or "") - verdict, campaign_id = await classify(org_scope, subject, from_address, body) + verdict, campaign_id = await classify(org_scope, subject, from_address, body, reporter_email) credited = False if verdict == "simulation" and campaign_id: credited = await credit_reporter(campaign_id, reporter_email) - user = await db.users.find_one({"email": reporter_email.strip().lower()}, {"_id": 0, "id": 1}) + user = await db.users.find_one( + {"email": reporter_email.strip().lower()}, {"_id": 0, "id": 1, "organization_id": 1} + ) + if org_id is None: + # Arrived through the report mailbox, not a staff member's scope: file it + # under the matched campaign's organization, else the reporter's. + if campaign_id: + campaign = await db.live_campaigns.find_one( + {"id": campaign_id}, {"_id": 0, "organization_id": 1} + ) + org_id = (campaign or {}).get("organization_id") + if org_id is None: + org_id = (user or {}).get("organization_id") report = PhishReport( organization_id=org_id, reporter_email=reporter_email.strip().lower(), diff --git a/backend/tests/test_report_mailbox.py b/backend/tests/test_report_mailbox.py new file mode 100644 index 0000000..704ec38 --- /dev/null +++ b/backend/tests/test_report_mailbox.py @@ -0,0 +1,222 @@ +"""Report mailbox: forwarded reports are parsed, classified and credited.""" + +from email.message import EmailMessage + +from services import report_inbox +from services.database import db +from services.live import inbound +from tests.conftest import make_user + +LURE_FROM = "IT Helpdesk " +LURE_SUBJECT = "Action required: verify your mailbox" + + +async def _campaign_with_recipient(org="acme", email="davan@acme.test"): + await db.live_campaigns.insert_one( + { + "id": "camp-1", + "organization_id": org, + "status": "running", + "sender_email": "helpdesk@acme.test", + "subject": LURE_SUBJECT, + } + ) + await db.live_recipients.insert_one( + {"campaign_id": "camp-1", "email": email, "reported": False} + ) + + +def _inline_forward(reporter="Davan ") -> bytes: + msg = EmailMessage() + msg["From"] = reporter + msg["To"] = "lapor@acme.test" + msg["Subject"] = f"Fwd: {LURE_SUBJECT}" + msg.set_content( + "Ini mencurigakan.\n\n" + "-------- Forwarded Message --------\n" + f"Subject: {LURE_SUBJECT}\n" + f"From: {LURE_FROM}\n" + "To: davan@acme.test\n\n" + "Please verify your mailbox here.\n" + ) + return msg.as_bytes() + + +def _attached_forward() -> bytes: + original = EmailMessage() + original["From"] = LURE_FROM + original["To"] = "davan@acme.test" + original["Subject"] = LURE_SUBJECT + original.set_content("Please verify your mailbox here.") + msg = EmailMessage() + msg["From"] = "davan@acme.test" + msg["To"] = "lapor@acme.test" + msg["Subject"] = "Laporan phishing" + msg.set_content("Lihat lampiran.") + msg.add_attachment(original) + return msg.as_bytes() + + +# ---------- parsing ---------- + + +def test_parse_inline_forward_finds_original_sender_and_subject(): + parsed = inbound.parse_report(_inline_forward()) + assert parsed["reporter_email"] == "davan@acme.test" + assert parsed["from_address"] == "helpdesk@acme.test" + assert parsed["subject"] == LURE_SUBJECT + + +def test_parse_forward_as_attachment_reads_inner_message(): + parsed = inbound.parse_report(_attached_forward()) + assert parsed["reporter_email"] == "davan@acme.test" + assert parsed["from_address"] == "helpdesk@acme.test" + assert parsed["subject"] == LURE_SUBJECT + + +def test_parse_html_only_forward(): + msg = EmailMessage() + msg["From"] = "davan@acme.test" + msg["Subject"] = f"Fwd: {LURE_SUBJECT}" + msg.set_content( + "
Cek ini

From: IT Helpdesk <helpdesk@acme.test>

verify

", + subtype="html", + ) + parsed = inbound.parse_report(msg.as_bytes()) + assert parsed["from_address"] == "helpdesk@acme.test" + + +# ---------- ingest through the mailbox path ---------- + + +async def test_mailbox_report_credits_reporter_under_campaign_org(api): + await _campaign_with_recipient() + report = await report_inbox.ingest_report(None, **inbound.parse_report(_inline_forward())) + assert report["verdict"] == "simulation" and report["credited"] is True + assert report["organization_id"] == "acme" + rec = await db.live_recipients.find_one({"campaign_id": "camp-1"}) + assert rec["reported"] is True + + +async def _configure(**over): + await db.live_config.insert_one( + { + "id": "live_config", + "imap_host": "greenmail:3143", + "imap_user": "sim-reply@acme.test", + "report_imap_user": "lapor@acme.test", + **over, + } + ) + + +async def test_poll_reports_without_mailbox(api): + assert (await inbound.poll_reports_once())["reason"] == "report_mailbox_not_configured" + await _configure(report_imap_user="") + assert (await inbound.poll_reports_once())["reason"] == "report_mailbox_not_configured" + + +async def test_poll_reports_ingests_and_advances_watermark(api, monkeypatch): + await _campaign_with_recipient() + await _configure() + calls = [] + + def fake_fetch(config, user, password, last_uid, uidvalidity): + calls.append(user) + if last_uid: + return [], 7, last_uid + return [_inline_forward(), _inline_forward("Lapor ")], 7, 2 + + monkeypatch.setattr(inbound, "_fetch_new", fake_fetch) + result = await inbound.poll_reports_once() + assert calls == ["lapor@acme.test"] + # The mailbox's own message (e.g. an auto-reply) is not a report. + assert result["outcomes"] == {"credited": 1, "skipped": 1} + assert (await db.live_state.find_one({"id": "report_imap_watermark"}))["last_uid"] == 2 + + again = await inbound.poll_reports_once() + assert again["polled"] == 0 + assert await db.phish_reports.count_documents({}) == 1 + + +# ---------- API ---------- + + +async def test_mailbox_endpoint_shows_address_to_staff(api): + _, trainer = await make_user("trainer") + assert (await api.get("/api/report-inbox/mailbox", headers=trainer)).json() == { + "address": None, + "configured": False, + } + await _configure() + got = (await api.get("/api/report-inbox/mailbox", headers=trainer)).json() + assert got == {"address": "lapor@acme.test", "configured": True} + _, user = await make_user("user") + assert (await api.get("/api/report-inbox/mailbox", headers=user)).status_code == 403 + assert (await api.post("/api/report-inbox/poll", headers=user)).status_code == 403 + + +async def test_report_mailbox_must_differ_from_reply_mailbox(api): + _, admin = await make_user("admin") + base = { + "gophish_base_url": "https://gp:3333", + "gophish_api_key": "k", + "phish_url": "http://phish", + "smtp_host": "mail:25", + "imap_host": "greenmail:3143", + "imap_user": "sim-reply@acme.test", + } + r = await api.put( + "/api/live/config", headers=admin, json={**base, "report_imap_user": "SIM-REPLY@acme.test"} + ) + assert r.status_code == 400 + r = await api.put( + "/api/live/config", + headers=admin, + json={**base, "report_imap_user": "lapor@acme.test", "report_imap_password": "pw"}, + ) + assert r.status_code == 200 + got = (await api.get("/api/live/config", headers=admin)).json() + assert got["report_imap_user"] == "lapor@acme.test" and got["report_imap_password"] == "***" + + +async def test_reused_sender_credits_the_campaign_the_reporter_received(api): + # An older campaign with the same sender and subject that the reporter + # already reported, and a newer running one they have not. + await db.live_campaigns.insert_many( + [ + { + "id": "old", + "organization_id": "acme", + "status": "killed", + "sender_email": "helpdesk@acme.test", + "subject": LURE_SUBJECT, + "created_at": "2026-10-26T10:00:00+00:00", + }, + { + "id": "new", + "organization_id": "acme", + "status": "running", + "sender_email": "helpdesk@acme.test", + "subject": LURE_SUBJECT, + "created_at": "2026-10-30T10:00:00+00:00", + }, + { + "id": "other", + "organization_id": "acme", + "status": "running", + "sender_email": "helpdesk@acme.test", + "subject": LURE_SUBJECT, + "created_at": "2026-10-31T10:00:00+00:00", + }, + ] + ) + await db.live_recipients.insert_many( + [ + {"campaign_id": "old", "email": "davan@acme.test", "reported": True}, + {"campaign_id": "new", "email": "davan@acme.test", "reported": False}, + {"campaign_id": "other", "email": "someone@acme.test", "reported": False}, + ] + ) + report = await report_inbox.ingest_report(None, **inbound.parse_report(_inline_forward())) + assert report["campaign_id"] == "new" and report["credited"] is True diff --git a/docs/api.md b/docs/api.md index 34ea7cd..bb6932d 100644 --- a/docs/api.md +++ b/docs/api.md @@ -108,7 +108,9 @@ Audit — `/api/audit` (admin): `GET /` (entries), `GET /verify` (chain integrit analysis, node/edge CRUD. - `/api/report-inbox` — Report-Phish mailbox (staff only): list/stats/leaderboard, `POST /ingest` (classify a reported message; credits the reporter if it's ours), - `PATCH /{id}` (triage). `DELETE /api/live/campaigns/{id}` removes a finished campaign. + `PATCH /{id}` (triage), `GET /mailbox` (the configured report address), + `POST /poll` (fetch forwarded reports from the report mailbox now). `POST + /api/live/poll` (admin) polls both the reply and the report mailbox. `DELETE /api/live/campaigns/{id}` removes a finished campaign. - `GET /api/live/analytics` — historical behaviour across launched campaigns: report-rate trend, per-campaign comparison, and repeat offenders. - `/api/live/schedules` — recurring campaigns (staff): CRUD + `POST /{id}/run-now`. diff --git a/docs/live-campaign-walkthrough.md b/docs/live-campaign-walkthrough.md index 948e787..97d2605 100644 --- a/docs/live-campaign-walkthrough.md +++ b/docs/live-campaign-walkthrough.md @@ -98,6 +98,7 @@ fill the **Live Campaigns (GoPhish)** panel: | IMAP host | `greenmail:3143` (GreenMail plain IMAP; use `:3993` for SSL) | | IMAP SSL | off for GreenMail's 3143 | | IMAP user / password | `sim-reply@acme.test` / `sim-reply@acme.test` (GreenMail accepts anything) | +| Report mailbox / password | `lapor@acme.test` / `lapor@acme.test` — where staff forward suspicious mail; must differ from the IMAP user | **Configure IMAP if you want replies to be ingested.** Pretexta polls this mailbox itself — reading the mail in Thunderbird or any other client does **not** @@ -306,6 +307,8 @@ To run against a real organization instead of the sandbox: | Can't approve a campaign | You are the creator. Approve from a different admin account (step 5). | | Pre-flight error about recipients | A recipient is outside a verified domain, or on the exclusion list. | | My reply never appears at all | IMAP isn't configured (Settings → Live), or the reply went to the sender address instead of the `Reply-To`. Check the campaign **Conversation** panel and run **Poll now** (Settings/API `POST /live/poll`). | +| I replied to the lure but **Reported** stays 0 | Replying is engaging, not reporting. Forward the email to the report mailbox (`lapor@acme.test`); it is credited within ~30 s, or click **Periksa sekarang** on Laporan Phishing. | +| My reply lands in the wrong place | The IMAP user must be the reply mailbox (`sim-reply@acme.test`), not the campaign sender. | | Reply shows in Conversation but not in Reply Review | No LLM provider configured — the persona can't draft a reply. Configure one in Settings → LLM (local Ollama works). | | Reply read in Thunderbird, poller skipped it | Fixed: the poller tracks UIDs, not the read/\Seen flag, so this no longer happens. | | Phishing link won't open (`http://gophish?rid=…`) | `phish_url` is set to an internal Docker name. Set it to a browser-reachable address (`http://localhost:8080` locally, or your public phishing URL), then **launch a new campaign** — the URL is baked in at launch. | diff --git a/docs/user-guide.md b/docs/user-guide.md index bfae29c..a88c1b7 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -218,9 +218,16 @@ mailbox, the server classifies it and the page shows each report with a verdict: - **Perlu ditinjau** — not one of yours; click **Tandai ancaman** or **Tandai aman** to triage it. -A **top-reporters** leaderboard surfaces who defends actively. In production a mail -rule or poller feeds the inbox; the **Catat laporan** form lets you record one by -hand for a demo. (Integration endpoint: `POST /report-inbox/ingest`.) +A **top-reporters** leaderboard surfaces who defends actively. + +**Report mailbox.** Set **Report mailbox** in Settings → Live Campaigns (for example +`lapor@acme.test`, on the same IMAP server as replies). Pretexta polls it every 30 +seconds: staff simply **forward** the suspicious email there — inline or as an +attachment — and the original sender and subject are read from the forward. The +**Mailbox pelaporan** card shows the address and a **Periksa sekarang** button. The +report mailbox must be different from the reply mailbox, or replies would count as +reports. Reports that arrive another way (phone, chat, ticket) can be recorded with +the **Catat laporan** form. (Integration endpoint: `POST /report-inbox/ingest`.) ### Analitik Live diff --git a/frontend/src/pages/ReportInboxPage.js b/frontend/src/pages/ReportInboxPage.js index efd0ae9..47f6fa1 100644 --- a/frontend/src/pages/ReportInboxPage.js +++ b/frontend/src/pages/ReportInboxPage.js @@ -1,7 +1,7 @@ import React, { useState } from 'react'; import { ShieldAlert, Flag, Inbox, AlertTriangle, CheckCircle2, Trophy, - Loader2, Plus, ShieldCheck, Bug, CircleHelp, + Loader2, Plus, ShieldCheck, Bug, CircleHelp, Mail, RefreshCw, } from 'lucide-react'; import PageHeader from '../components/PageHeader'; import SectionCard from '../components/SectionCard'; @@ -31,6 +31,44 @@ function VerdictBadge({ verdict }) { ); } +function MailboxCard({ onDone }) { + const { data: box } = useApi('/report-inbox/mailbox'); + const [busy, setBusy] = useState(false); + const poll = async () => { + setBusy(true); + try { + const res = await api.post('/report-inbox/poll'); + const n = res.data.polled || 0; + toast.success(n ? `${n} laporan baru diproses` : 'Tidak ada laporan baru'); + onDone?.(); + } catch (e) { toast.error(e.response?.data?.detail || 'Gagal'); } + finally { setBusy(false); } + }; + if (!box) return null; + return ( + + {box.configured ? ( + <> +

+ Personel cukup meneruskan (forward) email mencurigakan ke alamat ini. Laporan diperiksa + otomatis tiap 30 detik; pelapor simulasi langsung masuk ke report rate. +

+

{box.address}

+ + + ) : ( +

+ Belum diatur. Admin dapat mengisi “Report mailbox” di Pengaturan → Live Campaigns agar + email yang di-forward personel tercatat otomatis. +

+ )} +
+ ); +} + function RecordForm({ onDone }) { const [f, setF] = useState({ reporter_email: '', subject: '', from_address: '', body: '' }); const [busy, setBusy] = useState(false); @@ -49,8 +87,8 @@ function RecordForm({ onDone }) { return (

- Saat karyawan meneruskan email mencurigakan ke mailbox abuse, sistem memilahnya otomatis. - Di produksi ini disuplai oleh poller mailbox; di sini bisa dicatat manual untuk uji coba. + Untuk laporan yang masuk lewat jalur lain (telepon, chat, tiket), catat manual di sini. + Sistem memilahnya dengan cara yang sama.

+ {(board ?? []).length === 0 ? ( diff --git a/frontend/src/pages/SettingsPage.js b/frontend/src/pages/SettingsPage.js index f16963a..a53a187 100644 --- a/frontend/src/pages/SettingsPage.js +++ b/frontend/src/pages/SettingsPage.js @@ -155,6 +155,8 @@ function LiveConfigCard() { imap_ssl: !!f.imap_ssl, imap_user: f.imap_user || '', imap_password: f.imap_password || '', + report_imap_user: f.report_imap_user || '', + report_imap_password: f.report_imap_password || '', smtp_starttls: !!f.smtp_starttls, }); toast.success('Live config saved'); @@ -197,6 +199,8 @@ function LiveConfigCard() { {field('imap_host', 'IMAP host for replies (host:port)')} {field('imap_user', 'IMAP username')} {field('imap_password', 'IMAP password', 'password')} + {field('report_imap_user', 'Report mailbox (staff forward suspicious mail here, e.g. lapor@acme.test)')} + {field('report_imap_password', 'Report mailbox password', 'password')}