From 284ec74a34fd9f43af1358da32ab2eabb5fb4441 Mon Sep 17 00:00:00 2001 From: Danang Avan Maulana Date: Thu, 29 Oct 2026 06:42:51 +0700 Subject: [PATCH 1/4] feat(live): recurring campaign schedules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A schedule materialises a fresh campaign on a cadence (baseline -> periodic retest) without rebuilding it each time. Guardrail-safe: each run is created in pending_approval, never auto-sent, so two-person approval and the kill switch still apply — the schedule only automates the drafting cadence. - backend: CampaignSchedule + CampaignTemplate schemas; services/live/scheduler.py (materialize/run_due/run_scheduler background loop wired into lifespan); /live/schedules CRUD + run-now; index. 6 tests. - frontend: a "Jadwalkan berulang" toggle on the create form (reuses all its fields) + a "Kampanye terjadwal" card (run-now / pause / delete). Verified: 194 backend tests pass, ruff clean, frontend builds clean. Co-Authored-By: Claude Opus 4.8 --- backend/models/schemas.py | 40 +++++++ backend/routes/live.py | 96 ++++++++++++++++- backend/server.py | 6 ++ backend/services/live/scheduler.py | 79 ++++++++++++++ backend/tests/test_live_scheduler.py | 117 +++++++++++++++++++++ frontend/src/pages/LiveCampaignsPage.js | 132 +++++++++++++++++++++--- 6 files changed, 454 insertions(+), 16 deletions(-) create mode 100644 backend/services/live/scheduler.py create mode 100644 backend/tests/test_live_scheduler.py diff --git a/backend/models/schemas.py b/backend/models/schemas.py index 842c2f7..6536f75 100644 --- a/backend/models/schemas.py +++ b/backend/models/schemas.py @@ -746,4 +746,44 @@ class LiveCampaign(LiveCampaignCreate): gophish_campaign_id: int | None = None # Opaque token in the Reply-To address, used to match inbound replies (P3). reply_token: str = Field(default_factory=lambda: secrets.token_urlsafe(12)) + # QR / "quishing" variant: the lure is a QR code that encodes the tracked URL. + use_qr: bool = False + created_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat()) + + +class CampaignTemplate(BaseModel): + """The content of a campaign, without the per-run time window. Used as the + body that a schedule materialises into a fresh campaign each cycle.""" + + model_config = ConfigDict(extra="forbid") + name: str = Field(min_length=1, max_length=120) + objective: str + principles: list[str] = Field(min_length=1) + sender_name: str = Field(min_length=1, max_length=80) + sender_email: str = Field(min_length=3, max_length=254) + subject: str = Field(min_length=1, max_length=200) + body_html: str = Field(min_length=1, max_length=20000) + recipients: list[str] = Field(min_length=1, max_length=5000) + max_turns: int = Field(default=4, ge=0, le=6) + language: str = "en" + use_qr: bool = False + + +class CampaignSchedule(BaseModel): + """A recurring campaign. Each cycle it materialises a fresh campaign in + `pending_approval` — never auto-sent, so the two-person approval guardrail + (G2) still holds; the schedule only automates the drafting cadence.""" + + model_config = ConfigDict(extra="ignore") + id: str = Field(default_factory=lambda: str(uuid.uuid4())) + organization_id: str | None = None + name: str = Field(min_length=1, max_length=120) + interval_days: int = Field(ge=1, le=365) + window_days: int = Field(default=5, ge=1, le=30) # active window of each run + next_run: str # ISO timestamp of the next materialisation + active: bool = True + template: dict # a CampaignTemplate + created_by: str + last_run_at: str | None = None + last_campaign_id: str | None = None created_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat()) diff --git a/backend/routes/live.py b/backend/routes/live.py index 73d4b8a..40e3a96 100644 --- a/backend/routes/live.py +++ b/backend/routes/live.py @@ -5,12 +5,20 @@ `killed` reachable from any non-final state. See docs/design/live-campaigns.md. """ +from datetime import UTC, datetime, timedelta from typing import Any from fastapi import APIRouter, Depends, HTTPException, Query from pydantic import BaseModel, Field -from models.schemas import LiveCampaign, LiveCampaignCreate, User, VerifiedDomain +from models.schemas import ( + CampaignSchedule, + CampaignTemplate, + LiveCampaign, + LiveCampaignCreate, + User, + VerifiedDomain, +) from services import audit from services.ai_gateway import AIGateway from services.auth import require_admin, require_trainer @@ -18,6 +26,7 @@ from services.live import conversation from services.live import domains as domain_svc from services.live import launch as launch_svc +from services.live import scheduler as sched_svc from services.live.domains import email_domain from services.live.gophish import GophishClient, GophishError from services.live.preflight import has_errors, run_preflight @@ -411,6 +420,91 @@ async def live_analytics(current_user: User = Depends(require_trainer)): } +# ==================== RECURRING SCHEDULES ==================== + + +class ScheduleCreate(BaseModel): + name: str = Field(min_length=1, max_length=120) + interval_days: int = Field(ge=1, le=365) + window_days: int = Field(default=5, ge=1, le=30) + start_in_days: int = Field(default=0, ge=0, le=365) + template: CampaignTemplate + + +class ScheduleUpdate(BaseModel): + active: bool | None = None + interval_days: int | None = Field(default=None, ge=1, le=365) + window_days: int | None = Field(default=None, ge=1, le=30) + + +@router.get("/schedules") +async def list_schedules(current_user: User = Depends(require_trainer)): + return ( + await db.campaign_schedules.find(_scope(current_user), {"_id": 0}) + .sort("created_at", -1) + .to_list(200) + ) + + +@router.post("/schedules", status_code=201) +async def create_schedule(body: ScheduleCreate, current_user: User = Depends(require_trainer)): + next_run = (datetime.now(UTC) + timedelta(days=body.start_in_days)).isoformat() + schedule = CampaignSchedule( + organization_id=current_user.organization_id, + name=body.name, + interval_days=body.interval_days, + window_days=body.window_days, + next_run=next_run, + template=body.template.model_dump(), + created_by=current_user.id, + ) + await db.campaign_schedules.insert_one(schedule.model_dump()) + await audit.record(current_user.id, "live.schedule.create", schedule.id, {"name": body.name}) + return schedule.model_dump() + + +@router.patch("/schedules/{schedule_id}") +async def update_schedule( + schedule_id: str, body: ScheduleUpdate, current_user: User = Depends(require_trainer) +): + updates = {k: v for k, v in body.model_dump(exclude_unset=True).items() if v is not None} + if not updates: + raise HTTPException(422, "No fields to update") + res = await db.campaign_schedules.update_one( + {"id": schedule_id, **_scope(current_user)}, {"$set": updates} + ) + if not res.matched_count: + raise HTTPException(404, "Schedule not found") + return {"updated": schedule_id, **updates} + + +@router.delete("/schedules/{schedule_id}") +async def delete_schedule(schedule_id: str, current_user: User = Depends(require_trainer)): + res = await db.campaign_schedules.delete_one({"id": schedule_id, **_scope(current_user)}) + if not res.deleted_count: + raise HTTPException(404, "Schedule not found") + await audit.record(current_user.id, "live.schedule.delete", schedule_id) + return {"deleted": schedule_id} + + +@router.post("/schedules/{schedule_id}/run-now") +async def run_schedule_now(schedule_id: str, current_user: User = Depends(require_trainer)): + """Materialise one campaign from the schedule immediately (still pending_approval).""" + schedule = await db.campaign_schedules.find_one( + {"id": schedule_id, **_scope(current_user)}, {"_id": 0} + ) + if not schedule: + raise HTTPException(404, "Schedule not found") + cid = await sched_svc.materialize(schedule) + if not cid: + raise HTTPException(422, "Schedule template is invalid — edit the schedule") + await db.campaign_schedules.update_one( + {"id": schedule_id}, + {"$set": {"last_run_at": datetime.now(UTC).isoformat(), "last_campaign_id": cid}}, + ) + return {"created_campaign": cid} + + # ==================== CONVERSATION & REVIEW QUEUE (P3) ==================== diff --git a/backend/server.py b/backend/server.py index 8621257..d9e9874 100644 --- a/backend/server.py +++ b/backend/server.py @@ -368,6 +368,8 @@ async def lifespan(app: FastAPI): await db.phish_reports.create_index("id", unique=True) await db.phish_reports.create_index([("organization_id", 1), ("created_at", -1)]) await db.phish_reports.create_index([("organization_id", 1), ("verdict", 1)]) + await db.campaign_schedules.create_index("id", unique=True) + await db.campaign_schedules.create_index([("active", 1), ("next_run", 1)]) # G14: live campaign telemetry expires after 180 days await db.live_events.create_index("at", expireAfterSeconds=180 * 24 * 3600) await db.live_events.create_index([("campaign_id", 1), ("type", 1)]) @@ -398,8 +400,10 @@ async def lifespan(app: FastAPI): import asyncio from services.live.inbound import run_poller + from services.live.scheduler import run_scheduler poller_task = asyncio.create_task(run_poller()) + scheduler_task = asyncio.create_task(run_scheduler()) yield @@ -408,6 +412,8 @@ async def lifespan(app: FastAPI): if poller_task: poller_task.cancel() + if scheduler_task: + scheduler_task.cancel() client.close() diff --git a/backend/services/live/scheduler.py b/backend/services/live/scheduler.py new file mode 100644 index 0000000..ad8fba2 --- /dev/null +++ b/backend/services/live/scheduler.py @@ -0,0 +1,79 @@ +""" +Recurring live campaigns (LIVE OPS). A schedule materialises a fresh campaign on +a cadence so an organization can run a baseline and periodic retests without +re-building the campaign each time. + +Guardrail note (G2): a scheduled run is created in `pending_approval`, never sent +automatically. A second admin still has to approve and launch each instance, so +two-person approval and the kill switch continue to apply. The schedule only +automates the drafting cadence, not the send ("supervised auto-send" stays a +separate, deferred step). +""" + +import asyncio +import logging +from datetime import UTC, datetime, timedelta + +from models.schemas import CampaignTemplate, LiveCampaign +from services.database import db +from services.live.preflight import run_preflight + +logger = logging.getLogger(__name__) + +SCHEDULER_INTERVAL_SECONDS = 300 # how often the loop checks for due schedules + + +async def materialize(schedule: dict, now: datetime | None = None) -> str | None: + """Create one campaign instance from a schedule's template (pending_approval).""" + now = now or datetime.now(UTC) + try: + template = CampaignTemplate(**schedule["template"]) + except Exception as exc: # a bad template must not wedge the whole loop + logger.warning(f"Schedule {schedule['id']} has an invalid template: {exc}") + return None + + window = int(schedule.get("window_days", 5)) + campaign = LiveCampaign( + **template.model_dump(), + starts_at=now, + ends_at=now + timedelta(days=window), + organization_id=schedule.get("organization_id"), + created_by=schedule["created_by"], + status="pending_approval", + ) + doc = campaign.model_dump() + doc["preflight"] = await run_preflight(doc) + doc["scheduled_from"] = schedule["id"] + await db.live_campaigns.insert_one(dict(doc)) + logger.info(f"Schedule {schedule['id']} created campaign {campaign.id}") + return campaign.id + + +async def run_due(now: datetime | None = None) -> list[str]: + """Materialise every active schedule whose next_run has passed, and advance it.""" + now = now or datetime.now(UTC) + created: list[str] = [] + cursor = db.campaign_schedules.find( + {"active": True, "next_run": {"$lte": now.isoformat()}}, {"_id": 0} + ) + async for schedule in cursor: + cid = await materialize(schedule, now) + updates = { + "next_run": (now + timedelta(days=int(schedule["interval_days"]))).isoformat(), + "last_run_at": now.isoformat(), + } + if cid: + updates["last_campaign_id"] = cid + created.append(cid) + await db.campaign_schedules.update_one({"id": schedule["id"]}, {"$set": updates}) + return created + + +async def run_scheduler(interval_seconds: int = SCHEDULER_INTERVAL_SECONDS) -> None: + """Background loop. Always running; a no-op until a schedule is due.""" + while True: + try: + await run_due() + except Exception as exc: # never let the loop die + logger.warning(f"scheduler tick failed: {exc}") + await asyncio.sleep(interval_seconds) diff --git a/backend/tests/test_live_scheduler.py b/backend/tests/test_live_scheduler.py new file mode 100644 index 0000000..187c63a --- /dev/null +++ b/backend/tests/test_live_scheduler.py @@ -0,0 +1,117 @@ +"""Recurring campaign schedules: materialisation, the due loop, and the API.""" + +from datetime import UTC, datetime, timedelta + +from services.database import db +from services.live import scheduler +from tests.conftest import make_user + +TEMPLATE = { + "name": "Monthly helpdesk drill", + "objective": "click_link", + "principles": ["authority"], + "sender_name": "IT Helpdesk", + "sender_email": "helpdesk@acme.test", + "subject": "Password reset required", + "body_html": "

Reset: {{.URL}}

", + "recipients": ["alice@acme.test", "bob@acme.test"], + "max_turns": 0, + "language": "en", +} + + +async def _schedule(**over): + doc = { + "id": over.get("id", "sch-1"), + "organization_id": None, + "name": "sched", + "interval_days": 30, + "window_days": 5, + "next_run": datetime.now(UTC).isoformat(), + "active": True, + "template": TEMPLATE, + "created_by": "sys", + } + doc.update(over) + await db.campaign_schedules.insert_one(doc) + return doc + + +# ---------- materialisation ---------- + + +async def test_materialize_creates_pending_approval_campaign(api): + s = await _schedule() + cid = await scheduler.materialize(s) + camp = await db.live_campaigns.find_one({"id": cid}, {"_id": 0}) + assert camp["status"] == "pending_approval" # never auto-sent (G2) + assert camp["objective"] == "click_link" + assert camp["scheduled_from"] == "sch-1" + assert camp["recipients"] == ["alice@acme.test", "bob@acme.test"] + + +async def test_materialize_bad_template_returns_none(api): + s = await _schedule(id="bad", template={"name": "x"}) # missing required fields + assert await scheduler.materialize(s) is None + + +# ---------- the due loop ---------- + + +async def test_run_due_materialises_and_advances(api): + await _schedule(next_run=(datetime.now(UTC) - timedelta(minutes=1)).isoformat()) + created = await scheduler.run_due() + assert len(created) == 1 + s = await db.campaign_schedules.find_one({"id": "sch-1"}, {"_id": 0}) + # next_run advanced ~interval_days into the future + assert datetime.fromisoformat(s["next_run"]) > datetime.now(UTC) + timedelta(days=29) + assert s["last_campaign_id"] == created[0] + + +async def test_run_due_skips_future_and_inactive(api): + await _schedule(id="future", next_run=(datetime.now(UTC) + timedelta(days=10)).isoformat()) + await _schedule( + id="off", active=False, next_run=(datetime.now(UTC) - timedelta(days=1)).isoformat() + ) + created = await scheduler.run_due() + assert created == [] + + +# ---------- API ---------- + + +async def test_schedule_crud(api): + _, h = await make_user("trainer", organization_id="acme") + body = { + "name": "Monthly", + "interval_days": 30, + "window_days": 5, + "start_in_days": 0, + "template": TEMPLATE, + } + created = (await api.post("/api/live/schedules", json=body, headers=h)).json() + sid = created["id"] + assert created["active"] is True and created["interval_days"] == 30 + + listed = (await api.get("/api/live/schedules", headers=h)).json() + assert len(listed) == 1 + + # run-now materialises a pending_approval campaign + run = await api.post(f"/api/live/schedules/{sid}/run-now", headers=h) + assert run.status_code == 200 + cid = run.json()["created_campaign"] + assert (await db.live_campaigns.find_one({"id": cid}))["status"] == "pending_approval" + + # pause it + await api.patch(f"/api/live/schedules/{sid}", json={"active": False}, headers=h) + assert (await db.campaign_schedules.find_one({"id": sid}))["active"] is False + + # delete + assert (await api.delete(f"/api/live/schedules/{sid}", headers=h)).status_code == 200 + assert await db.campaign_schedules.count_documents({"id": sid}) == 0 + + +async def test_schedules_require_staff(api): + _, h = await make_user("user") + assert (await api.get("/api/live/schedules", headers=h)).status_code == 403 + assert (await api.post("/api/live/schedules", json={}, headers=h)).status_code == 403 diff --git a/frontend/src/pages/LiveCampaignsPage.js b/frontend/src/pages/LiveCampaignsPage.js index 98775c5..5b2a9e9 100644 --- a/frontend/src/pages/LiveCampaignsPage.js +++ b/frontend/src/pages/LiveCampaignsPage.js @@ -1,8 +1,8 @@ -import React, { useEffect, useState, useCallback } from 'react'; +import React, { useEffect, useState, useCallback, useRef } from 'react'; import { Radio, Plus, ShieldCheck, Send, Play, Octagon, CheckCircle2, XCircle, AlertTriangle, Info, RefreshCw, Globe, Inbox, MousePointerClick, Flag, - MessageSquare, Clock, Trash2, ShieldOff, X, + MessageSquare, Clock, Trash2, ShieldOff, X, Repeat, Calendar, PlayCircle, PauseCircle, } from 'lucide-react'; import { Card } from '../components/ui/card'; import { Button } from '../components/ui/button'; @@ -182,6 +182,60 @@ function ExclusionsCard() { ); } +const SchedulesCard = React.forwardRef(function SchedulesCard(_props, ref) { + const [rows, setRows] = useState([]); + const load = useCallback(async () => { + try { setRows((await api.get('/live/schedules')).data); } catch { /* noop */ } + }, []); + useEffect(() => { load(); }, [load]); + React.useImperativeHandle(ref, () => ({ reload: load }), [load]); + + const runNow = async (id) => { + try { await api.post(`/live/schedules/${id}/run-now`); toast.success('Kampanye dibuat (menunggu persetujuan)'); load(); } + catch (e) { toast.error(e.response?.data?.detail || 'Gagal'); } + }; + const toggle = async (s) => { await api.patch(`/live/schedules/${s.id}`, { active: !s.active }); load(); }; + const remove = async (id) => { + if (!window.confirm('Hapus jadwal ini?')) return; + await api.delete(`/live/schedules/${id}`); load(); + }; + + if (rows.length === 0) return null; + return ( + +

Kampanye terjadwal

+
+ {rows.map((s) => ( +
+
+ {s.name} + + {s.active ? 'aktif' : 'jeda'} + +
+

+ tiap {s.interval_days} hari · jendela {s.window_days} hari + {s.next_run && <> · berikutnya {new Date(s.next_run).toLocaleDateString('id-ID')}} +

+
+ + + +
+
+ ))} +
+
+ ); +}); + const BLANK = { name: '', objective: 'click_link', principles: ['authority'], sender_name: 'IT Helpdesk', sender_email: 'helpdesk@acme.test', @@ -189,10 +243,12 @@ const BLANK = { recipients: '', starts_at: '', ends_at: '', max_turns: 0, }; -function CreateForm({ onClose, onCreated }) { +function CreateForm({ onClose, onCreated, onScheduled }) { const [f, setF] = useState(BLANK); const [templates, setTemplates] = useState([]); const [aiMode, setAiMode] = useState(false); // click campaign by default + const [recurring, setRecurring] = useState(false); + const [sched, setSched] = useState({ interval_days: 30, window_days: 5 }); const set = (k, v) => setF((p) => ({ ...p, [k]: v })); const togglePrinciple = (p) => set('principles', f.principles.includes(p) ? f.principles.filter((x) => x !== p) : [...f.principles, p]); @@ -225,15 +281,34 @@ function CreateForm({ onClose, onCreated }) { }; const submit = async () => { - const payload = { - ...f, - max_turns: Number(f.max_turns), - recipients: f.recipients.split(/[\s,;]+/).map((x) => x.trim()).filter(Boolean), - starts_at: new Date(f.starts_at).toISOString(), - ends_at: new Date(f.ends_at).toISOString(), - }; + const recipients = f.recipients.split(/[\s,;]+/).map((x) => x.trim()).filter(Boolean); try { - const res = await api.post('/live/campaigns', payload); + if (recurring) { + // Build the schedule template — only the content fields (no time window). + const template = { + name: f.name, objective: f.objective, principles: f.principles, + sender_name: f.sender_name, sender_email: f.sender_email, + subject: f.subject, body_html: f.body_html, recipients, + max_turns: Number(f.max_turns), language: f.language || 'en', + use_qr: !!f.use_qr, + }; + await api.post('/live/schedules', { + name: f.name || 'Jadwal kampanye', + interval_days: Number(sched.interval_days), + window_days: Number(sched.window_days), + start_in_days: 0, + template, + }); + toast.success('Jadwal dibuat — tiap siklus membuat kampanye untuk disetujui'); + onScheduled?.(); + onClose?.(); + return; + } + const res = await api.post('/live/campaigns', { + ...f, max_turns: Number(f.max_turns), recipients, + starts_at: new Date(f.starts_at).toISOString(), + ends_at: new Date(f.ends_at).toISOString(), + }); toast.success('Campaign drafted'); onCreated(res.data.id); } catch (e) { @@ -287,8 +362,28 @@ function CreateForm({ onClose, onCreated }) {
set('sender_name', e.target.value)} />
set('sender_email', e.target.value)} />
-
set('starts_at', e.target.value)} />
-
set('ends_at', e.target.value)} />
+ {!recurring && <> +
set('starts_at', e.target.value)} />
+
set('ends_at', e.target.value)} />
+ } +
+ + {/* Recurring schedule: each cycle materialises a campaign for approval (G2). */} +
+ + {recurring && ( +
+
setSched((p) => ({ ...p, interval_days: e.target.value }))} />
+
setSched((p) => ({ ...p, window_days: e.target.value }))} />
+
+ )}
{/* Advanced AI settings only when the AI mode is chosen. */} @@ -329,7 +424,11 @@ function CreateForm({ onClose, onCreated }) {