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
2 changes: 2 additions & 0 deletions backend/routes/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
from routes.organizations import router as organizations_router
from routes.personas import router as personas_router
from routes.quizzes import router as quizzes_router
from routes.readiness import router as readiness_router
from routes.report_inbox import router as report_inbox_router
from routes.reports import router as reports_router
from routes.risk_profile import router as risk_profile_router
Expand Down Expand Up @@ -56,5 +57,6 @@
"live_router",
"audit_router",
"attack_surface_router",
"readiness_router",
"report_inbox_router",
]
21 changes: 21 additions & 0 deletions backend/routes/readiness.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
from fastapi import APIRouter, Depends

from models.schemas import User
from services import readiness
from services.auth import require_trainer

router = APIRouter(prefix="/readiness", tags=["readiness"])


@router.get("")
async def get_readiness(user: User = Depends(require_trainer)):
"""Cohort-level readiness overview: index, report-rate trend, remediation loop,
weakest principles and attack-surface posture. Admins see every organization;
trainers only their own."""
scope = {} if user.role == "admin" else {"organization_id": user.organization_id}
return await readiness.overview(
user_scope=scope,
campaign_scope=scope,
# Same workspace the Attack Surface Map uses for this user.
org_id=user.organization_id or f"org-{user.id}",
)
2 changes: 2 additions & 0 deletions backend/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
organizations_router,
personas_router,
quizzes_router,
readiness_router,
report_inbox_router,
reports_router,
risk_profile_router,
Expand Down Expand Up @@ -487,6 +488,7 @@ async def health_check():
api_router.include_router(audit_router)
api_router.include_router(attack_surface_router)
api_router.include_router(report_inbox_router)
api_router.include_router(readiness_router)

app.include_router(api_router)

Expand Down
181 changes: 181 additions & 0 deletions backend/services/readiness.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,181 @@
"""
Readiness overview — the first screen a commander or trainer sees.

One read-only aggregate that tells the Pretexta story on a single page:
measure (live report rate, lab discrimination) -> remediate (targeted
practice for the principle someone fell for) -> retest. Everything here is
cohort-level; no individual is named (G13), and live results never feed
gamification (G15).
"""

from statistics import mean
from typing import Any

from services import attack_surface
from services.database import db
from services.live import launch as launch_svc

PRINCIPLES = ("reciprocity", "scarcity", "authority", "commitment", "liking", "social_proof")

# How much each component contributes to the readiness index. Report rate leads:
# it is the defensive behaviour we are training for. Components without data are
# left out and the remaining weights renormalised, so an org that has only run
# lab exercises still gets a meaningful number.
WEIGHTS = {"report_rate": 0.4, "no_click": 0.2, "principles": 0.2, "triage": 0.2}

# The trend uses this many most-recent launched campaigns.
TREND_CAMPAIGNS = 8


async def _live(scope: dict) -> dict[str, Any]:
campaigns = (
await db.live_campaigns.find(
{**scope, "launched_at": {"$ne": None}},
{"_id": 0, "id": 1, "name": 1, "launched_at": 1},
)
.sort("launched_at", -1)
.to_list(TREND_CAMPAIGNS)
)
campaigns.reverse() # oldest -> newest for the trend line

trend, recipients, reported, clicked = [], 0, 0, 0
for c in campaigns:
m = await launch_svc.report_rate(c["id"])
trend.append(
{
"name": c["name"],
"launched_at": c["launched_at"],
"report_rate": m["report_rate"],
"click_rate": m["click_rate"],
"median_time_to_report_min": m["median_time_to_report_min"],
}
)
recipients += m["recipients"]
reported += m["reported"]
clicked += m["clicked"]

rates = [t["report_rate"] for t in trend if t["report_rate"] is not None]
return {
"campaigns": len(campaigns),
"recipients": recipients,
"reported": reported,
"clicked": clicked,
"report_rate": round(reported / recipients, 3) if recipients else None,
"click_rate": round(clicked / recipients, 3) if recipients else None,
# Change between the first and the latest campaign in the window.
"report_rate_delta": round(rates[-1] - rates[0], 3) if len(rates) >= 2 else None,
"trend": trend,
}


async def _principles(user_ids: list[str]) -> dict[str, float | None]:
profiles = await db.risk_profiles.find(
{"user_id": {"$in": user_ids}}, {"_id": 0, "current_vector": 1}
).to_list(5000)
out: dict[str, float | None] = {}
for p in PRINCIPLES:
values = [
prof["current_vector"][p]
for prof in profiles
if isinstance(prof.get("current_vector"), dict) and p in prof["current_vector"]
]
out[p] = round(mean(values), 1) if values else None
return out


async def _lab(user_ids: list[str]) -> dict[str, Any]:
sims = await db.simulations.find(
{"user_id": {"$in": user_ids}, "simulation_type": "triage", "status": "completed"},
{"_id": 0, "score": 1, "events": 1},
).to_list(5000)
d_primes = [
e["payload"]["d_prime"]
for s in sims
for e in s.get("events") or []
if e.get("event_type") == "triage_graded" and "d_prime" in (e.get("payload") or {})
]
scores = [s["score"] for s in sims if s.get("score") is not None]
return {
"triage_runs": len(sims),
"avg_triage_score": round(mean(scores), 1) if scores else None,
"avg_d_prime": round(mean(d_primes), 2) if d_primes else None,
}


async def _loop(user_ids: list[str]) -> dict[str, Any]:
base = {"trainee_id": {"$in": user_ids}}

async def count(extra: dict) -> int:
return await db.assignments.count_documents({**base, **extra})

loop = {
"remediation_assigned": await count({"source": "remediation"}),
"remediation_passed": await count({"source": "remediation", "status": "completed"}),
"retest_assigned": await count({"source": "retest"}),
"retest_passed": await count({"source": "retest", "status": "completed"}),
}
# Anonymous activity feed: what the loop did, never who it did it to.
recent = (
await db.assignments.find(
{**base, "source": {"$in": ["remediation", "retest"]}},
{"_id": 0, "source": 1, "principle": 1, "status": 1, "created_at": 1},
)
.sort("created_at", -1)
.to_list(8)
)
loop["recent"] = recent
return loop


def _index(live: dict, principles: dict, lab: dict) -> dict[str, Any]:
known = [v for v in principles.values() if v is not None]
components = {
"report_rate": None if live["report_rate"] is None else live["report_rate"] * 100,
"no_click": None if live["click_rate"] is None else (1 - live["click_rate"]) * 100,
"principles": mean(known) if known else None,
"triage": lab["avg_triage_score"],
}
available = {k: v for k, v in components.items() if v is not None}
weight = sum(WEIGHTS[k] for k in available)
score = round(sum(WEIGHTS[k] * v for k, v in available.items()) / weight) if weight else None
return {
"score": score,
"components": {k: None if v is None else round(v) for k, v in components.items()},
"weights": WEIGHTS,
}


async def overview(*, user_scope: dict, campaign_scope: dict, org_id: str) -> dict[str, Any]:
users = await db.users.find({**user_scope, "role": "user"}, {"_id": 0, "id": 1}).to_list(10000)
user_ids = [u["id"] for u in users]

live = await _live(campaign_scope)
principles = await _principles(user_ids)
lab = await _lab(user_ids)
loop = await _loop(user_ids)

known = {k: v for k, v in principles.items() if v is not None}
weakest = sorted(known, key=known.get)[:2]

surface = None
graph = await attack_surface.build_graph(org_id, refresh=False)
if any(n.get("is_asset") for n in graph.get("nodes", [])):
analysis = await attack_surface.analyze(org_id)
top = (analysis.get("attack_paths") or [None])[0]
surface = {
"posture": analysis.get("posture"),
"counts": analysis.get("counts"),
# Asset and probability only — the entry person stays on the staff-only map.
"top_path": top and {"asset": top["asset_name"], "probability": top["probability"]},
}

return {
"index": _index(live, principles, lab),
"people": len(user_ids),
"live": live,
"principles": principles,
"weakest_principles": weakest,
"lab": lab,
"loop": loop,
"attack_surface": surface,
}
127 changes: 127 additions & 0 deletions backend/tests/test_readiness.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
"""Readiness overview: cohort aggregate, org scoping, no individual names."""

from datetime import UTC, datetime

from services.database import db
from tests.conftest import make_user


async def _campaign(org, cid, recipients, launched="2026-10-01T00:00:00+00:00"):
await db.live_campaigns.insert_one(
{"id": cid, "name": cid, "organization_id": org, "launched_at": launched}
)
for i, (state, reported) in enumerate(recipients):
await db.live_recipients.insert_one(
{
"campaign_id": cid,
"email": f"{cid}-{i}@acme.test",
"state": state,
"reported": reported,
}
)


async def test_requires_staff(api):
_, h = await make_user("user")
assert (await api.get("/api/readiness", headers=h)).status_code == 403


async def test_empty_org_has_no_index(api):
_, h = await make_user("trainer", organization_id="org-a")
body = (await api.get("/api/readiness", headers=h)).json()
assert body["index"]["score"] is None
assert body["live"]["campaigns"] == 0
assert body["attack_surface"] is None


async def test_index_and_loop(api):
trainee, _ = await make_user("user", organization_id="org-a")
_, h = await make_user("trainer", organization_id="org-a")

# Two campaigns: report rate goes 25% -> 75%; one click in each.
await _campaign(
"org-a",
"c1",
[("clicked", False), ("sent", True), ("sent", False), ("sent", False)],
launched="2026-09-01T00:00:00+00:00",
)
await _campaign(
"org-a",
"c2",
[("clicked", False), ("sent", True), ("sent", True), ("sent", True)],
launched="2026-10-01T00:00:00+00:00",
)
vector = dict.fromkeys(
("reciprocity", "scarcity", "commitment", "liking", "social_proof"), 80.0
)
await db.risk_profiles.insert_one(
{"user_id": trainee.id, "current_vector": {**vector, "authority": 20.0}}
)
await db.simulations.insert_one(
{
"user_id": trainee.id,
"simulation_type": "triage",
"status": "completed",
"score": 90,
"events": [{"event_type": "triage_graded", "payload": {"d_prime": 2.0}}],
}
)
now = datetime.now(UTC).isoformat()
for source, status in (
("remediation", "completed"),
("remediation", "active"),
("retest", "completed"),
):
await db.assignments.insert_one(
{
"trainee_id": trainee.id,
"source": source,
"status": status,
"principle": "authority",
"reason": "secret detail about the person",
"created_at": now,
}
)

body = (await api.get("/api/readiness", headers=h)).json()

live = body["live"]
assert live["report_rate"] == 0.5 and live["click_rate"] == 0.25
assert live["report_rate_delta"] == 0.5
assert [t["name"] for t in live["trend"]] == ["c1", "c2"]

assert body["weakest_principles"][0] == "authority"
assert body["lab"] == {"triage_runs": 1, "avg_triage_score": 90.0, "avg_d_prime": 2.0}

comps = body["index"]["components"]
assert comps == {"report_rate": 50, "no_click": 75, "principles": 70, "triage": 90}
# 0.4*50 + 0.2*75 + 0.2*70 + 0.2*90 = 67
assert body["index"]["score"] == 67

loop = body["loop"]
assert (loop["remediation_assigned"], loop["remediation_passed"]) == (2, 1)
assert (loop["retest_assigned"], loop["retest_passed"]) == (1, 1)
# The feed is anonymous: no person, no free-text reason.
for item in loop["recent"]:
assert set(item) <= {"source", "principle", "status", "created_at"}


async def test_trainer_sees_only_own_org(api):
await _campaign("org-b", "other", [("clicked", False), ("sent", False)])
_, h = await make_user("trainer", organization_id="org-a")
body = (await api.get("/api/readiness", headers=h)).json()
assert body["live"]["campaigns"] == 0

_, admin_h = await make_user("admin")
assert (await api.get("/api/readiness", headers=admin_h)).json()["live"]["campaigns"] == 1


async def test_weights_renormalise_without_live_data(api):
trainee, _ = await make_user("user", organization_id="org-a")
_, h = await make_user("trainer", organization_id="org-a")
await db.simulations.insert_one(
{"user_id": trainee.id, "simulation_type": "triage", "status": "completed", "score": 60}
)
index = (await api.get("/api/readiness", headers=h)).json()["index"]
assert index["components"]["report_rate"] is None
assert index["score"] == 60 # triage is the only component with data
7 changes: 5 additions & 2 deletions frontend/src/App.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ const MyAssignmentsPage = lazy(() => import('./pages/MyAssignmentsPage'));

// ── Trainer/Admin pages ────────────────────────────────────────────────────
const InstructorDashboard = lazy(() => import('./pages/InstructorDashboard'));
const ReadinessPage = lazy(() => import('./pages/ReadinessPage'));
const TraineesPage = lazy(() => import('./pages/TraineesPage'));
const AssignmentsPage = lazy(() => import('./pages/AssignmentsPage'));
const InstructorReportsPage = lazy(() => import('./pages/InstructorReportsPage'));
Expand Down Expand Up @@ -59,7 +60,8 @@ function PageLoader() {
function AdminRoutes() {
return (
<Routes>
<Route path="/" element={<InstructorDashboard />} />
<Route path="/" element={<ReadinessPage />} />
<Route path="/command" element={<InstructorDashboard />} />
{/* User management — admin only */}
<Route path="/users" element={<UsersPage />} />
{/* Trainer management */}
Expand Down Expand Up @@ -100,7 +102,8 @@ function AdminRoutes() {
function TrainerRoutes() {
return (
<Routes>
<Route path="/" element={<InstructorDashboard />} />
<Route path="/" element={<ReadinessPage />} />
<Route path="/command" element={<InstructorDashboard />} />
{/* Trainer tools */}
<Route path="/users" element={<UsersPage />} />
<Route path="/trainer/groups" element={<TraineesPage />} />
Expand Down
Loading