Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions backend/models/schemas.py
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,10 @@ class Assignment(BaseModel):
reason: str | None = None # human-readable explanation shown to the trainee
principle: str | None = None # the Cialdini principle being remediated
retest_of: str | None = None # the remediation assignment this re-tests
# Translatable form of `reason` for system assignments: the client renders
# remediation.<reason_key> with these params; `reason` stays as the fallback.
reason_key: str | None = None
reason_params: dict[str, Any] | None = None

created_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())

Expand Down
69 changes: 65 additions & 4 deletions backend/routes/triage.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,15 @@
the server grades, computing d' with a false-alarm penalty.
"""

from fastapi import APIRouter, Depends
from pydantic import BaseModel, Field
import uuid
from typing import Literal

from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field, model_validator

from models.schemas import User
from services import triage
from services.auth import get_current_user
from services import audit, triage
from services.auth import get_current_user, require_trainer
from services.database import db

router = APIRouter(prefix="/triage", tags=["triage"])
Expand Down Expand Up @@ -43,3 +46,61 @@ async def submit(
set_id: str, data: TriageSubmission, current_user: User = Depends(get_current_user)
):
return await triage.grade(set_id, current_user.id, data.marks, data.duration_seconds)


# ---- authoring: trainers add their own sets (e.g. a unit-specific content pack)


class TriageItemIn(BaseModel):
model_config = {"extra": "forbid"}
channel: Literal["email_inbox", "whatsapp", "sms"] = "email_inbox"
# For chat channels `from` is the contact as shown in the chat header and
# `subject` is the one-line preview in the chat list.
from_: str = Field(alias="from", min_length=1, max_length=200)
subject: str = Field(min_length=1, max_length=200)
body: str = Field(min_length=1, max_length=5000)
is_pretext: bool
principle: str | None = Field(default=None, max_length=40)
explanation: str | None = Field(default=None, max_length=2000)

@model_validator(mode="after")
def _pretext_is_explained(self):
if self.is_pretext and not (self.principle and self.explanation):
raise ValueError("a pretext needs a principle and an explanation for the debrief")
return self


class TriageSetIn(BaseModel):
model_config = {"extra": "forbid"}
id: str | None = Field(default=None, min_length=3, max_length=80, pattern=r"^[a-z0-9-]+$")
title: str = Field(min_length=1, max_length=120)
description: str = Field(default="", max_length=1000)
language: Literal["en", "id"] = "en"
difficulty: Literal["easy", "medium", "hard"] = "medium"
items: list[TriageItemIn] = Field(min_length=4, max_length=40)

@model_validator(mode="after")
def _has_both_kinds(self):
# d' needs at least one pretext and one legitimate message to be defined.
kinds = {i.is_pretext for i in self.items}
if kinds != {True, False}:
raise ValueError("a set needs both pretexts and legitimate messages")
return self


@router.post("", status_code=201)
async def create_set(data: TriageSetIn, current_user: User = Depends(require_trainer)):
set_id = data.id or f"triage-{uuid.uuid4().hex[:12]}"
if await db.triage_sets.find_one({"id": set_id}, {"_id": 1}):
raise HTTPException(status_code=409, detail="A triage set with this id already exists")
doc = {
**data.model_dump(exclude={"items", "id"}),
"id": set_id,
"created_by": current_user.id,
"items": [
{"id": str(uuid.uuid4()), **item.model_dump(by_alias=True)} for item in data.items
],
}
await db.triage_sets.insert_one(doc)
await audit.record(current_user.id, "triage.set.create", set_id, {"items": len(data.items)})
return {"id": set_id, "items": len(data.items)}
4 changes: 3 additions & 1 deletion backend/services/demo.py
Original file line number Diff line number Diff line change
Expand Up @@ -303,9 +303,11 @@ def _assignment(
"trainee_id": trainee_id,
"content_type": content_type,
"content_id": content_id,
"title": f"{'Retest' if source == 'retest' else 'Remediation'}: {title}",
"title": title,
"instructions": reason,
"reason": reason,
"reason_key": "retest" if source == "retest" else "live_clicked",
"reason_params": {"principle": principle},
"principle": principle,
"source": source,
"retest_of": retest_of,
Expand Down
68 changes: 56 additions & 12 deletions backend/services/remediation.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,24 +33,47 @@
}


async def _pick_content(principle: str, exclude_ids: set[str]) -> dict | None:
# Tags that describe who an exercise is written for (language, setting). A
# remediation should feel like the exercise that was failed, so candidates that
# share more of these tags are preferred.
CONTEXT_TAGS = {"indonesia", "satuan", "military"}


async def _pick_content(
principle: str, exclude_ids: set[str], prefer_tags: set[str] | None = None
) -> dict | None:
"""Choose a lab exercise that trains `principle` and the trainee hasn't just done.

Prefers an interactive scenario; falls back to a quiz on the same principle.
Within a type, prefers content sharing the most `prefer_tags`.
"""
prefer_tags = prefer_tags or set()
for coll, content_type in (("challenges", "challenge"), ("quizzes", "quiz")):
async for doc in db[coll].find(
{"cialdini_categories": principle}, {"_id": 0, "id": 1, "title": 1}
):
if doc["id"] not in exclude_ids:
return {
"content_type": content_type,
"content_id": doc["id"],
"title": doc["title"],
}
candidates = [
doc
async for doc in db[coll].find(
{"cialdini_categories": principle},
{"_id": 0, "id": 1, "title": 1, "metadata.tags": 1},
)
if doc["id"] not in exclude_ids
]
if candidates:
# max() keeps the first of equal scores, so the stored order breaks ties.
best = max(
candidates,
key=lambda d: len(prefer_tags & set((d.get("metadata") or {}).get("tags") or [])),
)
return {"content_type": content_type, "content_id": best["id"], "title": best["title"]}
return None


async def _context_tags(challenge_id: str | None) -> set[str]:
if not challenge_id:
return set()
doc = await db.challenges.find_one({"id": challenge_id}, {"_id": 0, "metadata.tags": 1})
return CONTEXT_TAGS & set(((doc or {}).get("metadata") or {}).get("tags") or [])


async def _recent_content_ids(user_id: str) -> set[str]:
"""Content the user already has active, or passed recently — don't re-assign it."""
ids: set[str] = set()
Expand All @@ -69,6 +92,10 @@ async def assign_remediation(
source: str = "remediation",
retest_of: str | None = None,
due_days: int = REMEDIATION_DUE_DAYS,
reason_key: str | None = None,
reason_params: dict | None = None,
prefer_tags: set[str] | None = None,
exclude_content: str | None = None,
) -> str | None:
"""Create a remediation assignment for `principle`. Idempotent per principle:
skips if the user already has an active remediation for it."""
Expand All @@ -86,7 +113,10 @@ async def assign_remediation(
if existing:
return None

content = await _pick_content(principle, await _recent_content_ids(user_id))
exclude = await _recent_content_ids(user_id)
if exclude_content:
exclude.add(exclude_content) # never "remediate" with the exercise just failed
content = await _pick_content(principle, exclude, prefer_tags)
if not content:
logger.info(f"No remediation content for principle '{principle}'")
return None
Expand All @@ -96,9 +126,12 @@ async def assign_remediation(
trainee_id=user_id,
content_type=content["content_type"],
content_id=content["content_id"],
title=f"Remediation: {content['title']}",
# The UI badges the source (remediation / retest), so the title stays the exercise's own.
title=content["title"],
instructions=reason,
reason=reason,
reason_key=reason_key,
reason_params={"principle": principle, **(reason_params or {})},
principle=principle,
source=source,
retest_of=retest_of,
Expand All @@ -121,12 +154,17 @@ async def on_lab_result(sim: dict, user_id: str) -> None:
return
principles = (sim.get("challenge_data") or {}).get("cialdini_categories") or []
title = sim.get("title", "an exercise")
prefer = await _context_tags(sim.get("challenge_id"))
for principle in principles[:2]:
await assign_remediation(
user_id,
principle,
f"You scored {round(score)}% on '{title}', which tested {_label(principle)}. "
f"This exercise gives you focused practice.",
reason_key="lab_fail",
reason_params={"score": round(score), "title": title},
prefer_tags=prefer,
exclude_content=sim.get("challenge_id"),
)


Expand All @@ -150,6 +188,8 @@ async def on_live_fail(campaign: dict, email: str, outcome: str) -> None:
principle,
f"In a live phishing simulation you {verb} a message that used {_label(principle)}. "
f"This exercise helps you recognise it next time.",
reason_key=f"live_{outcome}",
prefer_tags={"indonesia"} if campaign.get("language") == "id" else set(),
)


Expand All @@ -165,4 +205,8 @@ async def on_assignment_passed(assignment: dict, user_id: str) -> None:
source="retest",
retest_of=assignment["id"],
due_days=RETEST_AFTER_DAYS,
reason_key="retest",
# A variant: same context as the practice, but not the same exercise.
prefer_tags=await _context_tags(assignment.get("content_id")),
exclude_content=assignment.get("content_id"),
)
73 changes: 73 additions & 0 deletions backend/tests/test_remediation.py
Original file line number Diff line number Diff line change
Expand Up @@ -129,3 +129,76 @@ async def test_retest_not_scheduled_for_manual_assignment(api):
{"id": "m1", "source": "manual", "principle": "authority"}, user.id
)
assert await db.assignments.count_documents({"source": "retest"}) == 0


async def test_reason_is_translatable(api):
"""System assignments carry a reason key + params so the UI can localise them."""
from services import remediation

user, _ = await make_user("user")
await db.challenges.insert_one(
{
"id": "c-auth",
"title": "Authority drill",
"cialdini_categories": ["authority"],
"nodes": [],
}
)
await remediation.on_lab_result(
{
"score": 40,
"title": "Boss on WhatsApp",
"challenge_data": {"cialdini_categories": ["authority"]},
},
user.id,
)
a = await db.assignments.find_one({"trainee_id": user.id})
assert a["reason_key"] == "lab_fail"
assert a["reason_params"] == {
"principle": "authority",
"score": 40,
"title": "Boss on WhatsApp",
}


async def test_remediation_prefers_same_context_and_skips_the_failed_exercise(api):
from services import remediation

user, _ = await make_user("user")
await db.challenges.insert_many(
[
{
"id": "en-auth",
"title": "Generic CEO fraud",
"cialdini_categories": ["authority"],
"metadata": {"tags": ["bec"]},
"nodes": [],
},
{
"id": "unit-failed",
"title": "Boss on WhatsApp",
"cialdini_categories": ["authority"],
"metadata": {"tags": ["whatsapp", "satuan", "military", "indonesia"]},
"nodes": [],
},
{
"id": "unit-other",
"title": "Nota dinas APK",
"cialdini_categories": ["authority"],
"metadata": {"tags": ["email", "satuan", "military", "indonesia"]},
"nodes": [],
},
]
)
await remediation.on_lab_result(
{
"score": 40,
"title": "Boss on WhatsApp",
"challenge_id": "unit-failed",
"challenge_data": {"cialdini_categories": ["authority"]},
},
user.id,
)
a = await db.assignments.find_one({"trainee_id": user.id})
assert a["content_id"] == "unit-other" # same unit context, not the one just failed
assert a["title"] == "Nota dinas APK" # no English "Remediation:" prefix
47 changes: 47 additions & 0 deletions backend/tests/test_triage.py
Original file line number Diff line number Diff line change
Expand Up @@ -149,3 +149,50 @@ async def test_seed_fills_missing_set_without_touching_edited_one(api):
await triage.seed_default_set()
assert (await db.triage_sets.find_one({"id": "triage-inbox-01"}))["title"] == "Edited"
assert await db.triage_sets.find_one({"id": "triage-inbox-01-id"})


def _set_payload(**over):
items = [
{
"channel": "whatsapp",
"from": "Atasan (nomor baru)",
"subject": "Tolong transfer dulu",
"body": "..",
"is_pretext": True,
"principle": "authority",
"explanation": "nomor baru",
},
{"from": "hr@acme.com", "subject": "Timesheet", "body": "..", "is_pretext": False},
{"from": "cal@acme.com", "subject": "Invite", "body": "..", "is_pretext": False},
{
"channel": "whatsapp",
"from": "Grup Kantor",
"subject": "Rapat jam 9",
"body": "..",
"is_pretext": False,
},
]
return {"id": "pack-1", "title": "Pack", "language": "id", "items": items, **over}


async def test_trainer_can_add_a_set_with_chat_items(api):
_, h = await make_user("trainer")
r = await api.post("/api/triage", json=_set_payload(), headers=h)
assert r.status_code == 201, r.text
taker, th = await make_user("user")
got = (await api.get("/api/triage/pack-1", headers=th)).json()
assert got["items"][0]["channel"] == "whatsapp"
assert "is_pretext" not in got["items"][0] # labels stay on the server
assert (await api.post("/api/triage", json=_set_payload(), headers=h)).status_code == 409


async def test_set_authoring_rules(api):
_, uh = await make_user("user")
assert (await api.post("/api/triage", json=_set_payload(), headers=uh)).status_code == 403
_, h = await make_user("trainer")
only_legit = _set_payload()
only_legit["items"] = [dict(i, is_pretext=False) for i in only_legit["items"]]
assert (await api.post("/api/triage", json=only_legit, headers=h)).status_code == 422
unexplained = _set_payload()
unexplained["items"][0].pop("explanation")
assert (await api.post("/api/triage", json=unexplained, headers=h)).status_code == 422
15 changes: 15 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,14 @@ Scenarios — `/api/scenarios`:
| POST | `/resume` | U | Resume/begin a session by `simulation_id` |
| GET | `/session/{id}` | U | Current session state |

Inbox Triage — `/api/triage`:

| Method | Path | Role | Notes |
|--------|------|------|-------|
| GET | `` / `/{id}` | U | List sets; `/{id}` strips labels and explanations |
| POST | `/{id}/submit` | U | Server grades with signal detection (d′) |
| POST | `` | T | Add a set (e.g. a unit-specific content pack). Items may be `email_inbox`, `whatsapp` or `sms`; a set needs both pretexts and legitimate messages, and every pretext needs a principle + explanation |

Simulations, debrief, reports — `/api/simulations`, `/api/debrief`,
`/api/reports`: read your own
(staff may review trainees). Clients **cannot** create graded simulation types
Expand Down Expand Up @@ -109,6 +117,13 @@ Audit — `/api/audit` (admin): `GET /` (entries), `GET /verify` (chain integrit
- `GET /api/attack-surface/targets` — emailable people on the map, ranked
most-susceptible first, to seed a campaign aimed at the human weak points.

- `GET /api/readiness` — staff home screen: readiness index (components and
weights exposed), report-rate trend, remediation-loop counts, principle
resistance, lab d′ and attack-surface posture. Cohort-level only (G13).
- `/api/demo` (admin) — `GET` status, `POST` load the fictional demo
organization (`demo.test`), `DELETE` remove it; only records tagged as demo
are touched.

## Health

`GET /api/health` — liveness + DB connectivity (used by Docker healthchecks).
Loading