Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(reports): WS-G2 executive weekly digest endpoint + UI (HTML/PDF)

Beenuc8148efed427
diff --git a/apps/web/src/app/(app)/reports/digest/page.tsx b/apps/web/src/app/(app)/reports/digest/page.tsx
new file mode 100644
index 000000000..96d6c3481
--- /dev/null
+++ b/apps/web/src/app/(app)/reports/digest/page.tsx
@@ -0,0 +1,11 @@
+import { ExecutiveDigest } from '@/components/reports/ExecutiveDigest';
+
+export const metadata = { title: 'Executive Digest — AiSOC' };
+
+export default function ExecutiveDigestPage() {
+ return (
+ <div className="p-6 max-w-7xl mx-auto">
+ <ExecutiveDigest />
+ </div>
+ );
+}
diff --git a/apps/web/src/components/layout/Sidebar.tsx b/apps/web/src/components/layout/Sidebar.tsx
index f952faabe..604bf6764 100644
--- a/apps/web/src/components/layout/Sidebar.tsx
+++ b/apps/web/src/components/layout/Sidebar.tsx
@@ -116,6 +116,12 @@ const MarketplaceIcon = () => (
</svg>
);
+const DocumentReportIcon = () => (
+ <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+ <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M9 17.25v-3.75M12 17.25V9.75M15 17.25v-1.5M19.5 19.5h-15A2.25 2.25 0 012.25 17.25V6.75A2.25 2.25 0 014.5 4.5h15a2.25 2.25 0 012.25 2.25v10.5a2.25 2.25 0 01-2.25 2.25z" />
+ </svg>
+);
+
const navSections: NavSection[] = [
{
items: [
@@ -271,6 +277,11 @@ const navSections: NavSection[] = [
href: '/sla',
icon: <ChartBarIcon />,
},
+ {
+ label: 'Executive Digest',
+ href: '/reports/digest',
+ icon: <DocumentReportIcon />,
+ },
{
label: 'Audit Log',
href: '/audit',
diff --git a/apps/web/src/components/reports/ExecutiveDigest.tsx b/apps/web/src/components/reports/ExecutiveDigest.tsx
new file mode 100644
index 000000000..a04670f21
--- /dev/null
+++ b/apps/web/src/components/reports/ExecutiveDigest.tsx
@@ -0,0 +1,437 @@
+'use client';
+
+/**
+ * Executive weekly digest panel — WS-G2.
+ *
+ * Renders the deterministic snapshot returned by
+ * `GET /api/v1/reports/digest/weekly?format=json` as an interactive dashboard,
+ * and exposes a "Print / Save as PDF" action that fetches the print-ready HTML
+ * variant (with the user's auth token) and opens it in a new tab. The browser's
+ * native "Save as PDF" then produces the board-ready document — no server-side
+ * PDF dependency required.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+import useSWR from 'swr';
+
+import { reportsApi, type ExecutiveDigest as ExecutiveDigestPayload } from '@/lib/api';
+
+const PERIOD_PRESETS: { label: string; days: number }[] = [
+ { label: 'Last 7 days', days: 7 },
+ { label: 'Last 14 days', days: 14 },
+ { label: 'Last 30 days', days: 30 },
+];
+
+const SEVERITY_ORDER: Array<keyof ExecutiveDigestPayload['alerts']['severity']> = [
+ 'critical',
+ 'high',
+ 'medium',
+ 'low',
+ 'info',
+];
+
+const SEVERITY_TEXT: Record<string, string> = {
+ critical: 'text-red-300',
+ high: 'text-orange-300',
+ medium: 'text-yellow-300',
+ low: 'text-blue-300',
+ info: 'text-gray-300',
+};
+
+const RECOMMENDATION_ACCENT: Record<string, string> = {
+ critical: 'border-red-500/40 bg-red-500/10 text-red-100',
+ warning: 'border-amber-500/40 bg-amber-500/10 text-amber-100',
+ info: 'border-sky-500/40 bg-sky-500/10 text-sky-100',
+};
+
+function fmtHours(hours: number | null | undefined): string {
+ if (hours === null || hours === undefined) return '—';
+ if (hours < 1) return `${Math.round(hours * 60)}m`;
+ if (hours < 24) return `${hours.toFixed(1)}h`;
+ const days = hours / 24;
+ return `${days.toFixed(1)}d`;
+}
+
+function fmtDateTime(iso: string): string {
+ try {
+ return new Date(iso).toLocaleString(undefined, {
+ year: 'numeric',
+ month: 'short',
+ day: 'numeric',
+ hour: 'numeric',
+ minute: '2-digit',
+ });
+ } catch {
+ return iso;
+ }
+}
+
+function fmtDate(iso: string): string {
+ try {
+ return new Date(iso).toLocaleDateString(undefined, {
+ year: 'numeric',
+ month: 'short',
+ day: 'numeric',
+ });
+ } catch {
+ return iso;
+ }
+}
+
+function fmtDelta(delta: number): string {
+ if (delta === 0) return '±0';
+ return delta > 0 ? `+${delta}` : `${delta}`;
+}
+
+function deltaClass(delta: number): string {
+ if (delta === 0) return 'text-gray-500';
+ // For tactic counts: positive (more activity) is concerning, negative (less) is good.
+ return delta > 0 ? 'text-amber-300' : 'text-emerald-300';
+}
+
+function periodWindow(days: number): { period_start: string; period_end: string } {
+ const end = new Date();
+ const start = new Date(end.getTime() - days * 24 * 60 * 60 * 1000);
+ return {
+ period_start: start.toISOString(),
+ period_end: end.toISOString(),
+ };
+}
+
+export function ExecutiveDigest() {
+ const [days, setDays] = useState<number>(7);
+ const [printing, setPrinting] = useState(false);
+ const [printError, setPrintError] = useState<string | null>(null);
+
+ const params = useMemo(() => periodWindow(days), [days]);
+
+ const { data, error, isLoading, mutate } = useSWR<ExecutiveDigestPayload>(
+ ['executive-digest', params.period_start, params.period_end],
+ () => reportsApi.weeklyDigest(params),
+ {
+ revalidateOnFocus: false,
+ shouldRetryOnError: false,
+ errorRetryCount: 0,
+ },
+ );
+
+ const handlePrint = useCallback(async () => {
+ setPrintError(null);
+ setPrinting(true);
+ try {
+ const html = await reportsApi.weeklyDigestHtml(params);
+ const blob = new Blob([html], { type: 'text/html;charset=utf-8' });
+ const url = URL.createObjectURL(blob);
+ // Open in a new tab so the user can hit Cmd/Ctrl+P or use the system print dialog.
+ const win = window.open(url, '_blank', 'noopener,noreferrer');
+ if (!win) {
+ setPrintError('Pop-up blocked — allow pop-ups for this site to open the printable digest.');
+ }
+ // Defer revoke so the new tab has time to load. 60 seconds is a generous safety net.
+ setTimeout(() => URL.revokeObjectURL(url), 60_000);
+ } catch (err) {
+ setPrintError(err instanceof Error ? err.message : 'Failed to load printable digest.');
+ } finally {
+ setPrinting(false);
+ }
+ }, [params]);
+
+ return (
+ <div className="space-y-6">
+ {/* Header */}
+ <div className="flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between">
+ <div>
+ <h1 className="text-2xl font-bold text-white">Executive Digest</h1>
+ <p className="mt-1 text-sm text-gray-400">
+ Board-ready weekly snapshot of SOC posture, MTT performance, and tuning recommendations.
+ </p>
+ </div>
+ <div className="flex flex-wrap items-center gap-2">
+ <select
+ value={days}
+ onChange={(e) => setDays(Number(e.target.value))}
+ className="rounded border border-gray-600 bg-gray-800 px-3 py-1.5 text-sm text-white"
+ >
+ {PERIOD_PRESETS.map((p) => (
+ <option key={p.days} value={p.days}>
+ {p.label}
+ </option>
+ ))}
+ </select>
+ <button
+ type="button"
+ onClick={() => mutate()}
+ className="rounded border border-gray-600 bg-gray-800 px-3 py-1.5 text-sm text-gray-200 hover:bg-gray-700"
+ >
+ Refresh
+ </button>
+ <button
+ type="button"
+ onClick={handlePrint}
+ disabled={printing || !data}
+ className="rounded bg-violet-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-violet-500 disabled:cursor-not-allowed disabled:opacity-50"
+ >
+ {printing ? 'Loading…' : 'Print / Save as PDF'}
+ </button>
+ </div>
+ </div>
+
+ {error && (
+ <div className="rounded-md border border-red-500/30 bg-red-500/10 px-4 py-2 text-sm text-red-200">
+ Failed to load digest: {error instanceof Error ? error.message : String(error)}
+ </div>
+ )}
+ {printError && (
+ <div className="rounded-md border border-amber-500/30 bg-amber-500/10 px-4 py-2 text-sm text-amber-200">
+ {printError}
+ </div>
+ )}
+
+ {isLoading && !data && (
+ <div className="rounded-xl border border-gray-700 bg-gray-900 p-6 text-sm text-gray-400">
+ Computing digest…
+ </div>
+ )}
+
+ {data && <DigestBody digest={data} />}
+ </div>
+ );
+}
+
+function DigestBody({ digest }: { digest: ExecutiveDigestPayload }) {
+ return (
+ <>
+ {/* Period + headline */}
+ <section className="rounded-xl border border-violet-500/30 bg-violet-950/20 p-5">
+ <p className="text-xs uppercase tracking-wide text-violet-300">Reporting period</p>
+ <p className="mt-1 text-lg font-semibold text-white">{digest.period.label}</p>
+ <p className="mt-3 text-sm leading-relaxed text-gray-200">{digest.headline}</p>
+ <p className="mt-2 text-xs text-gray-500">
+ {fmtDateTime(digest.period.start)} → {fmtDateTime(digest.period.end)}
+ </p>
+ </section>
+
+ {/* KPI strip */}
+ <section className="grid grid-cols-2 gap-4 sm:grid-cols-4">
+ <KpiCard label="New alerts" value={digest.alerts.new} sub={`${digest.alerts.total} total in window`} />
+ <KpiCard
+ label="Open alerts"
+ value={digest.alerts.open_at_period_end}
+ sub={`${digest.alerts.resolved} resolved this period`}
+ />
+ <KpiCard
+ label="Cases opened"
+ value={digest.cases.opened}
+ sub={`${digest.cases.closed} closed · ${digest.cases.sla_breached} SLA breaches`}
+ />
+ <KpiCard
+ label="Mean MTTR"
+ value={fmtHours(digest.mtt.mttr_hours)}
+ sub={`MTTD ${fmtHours(digest.mtt.mttd_hours)} · MTTC ${fmtHours(digest.mtt.mttc_hours)}`}
+ />
+ </section>
+
+ {/* Severity split + automation */}
+ <section className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+ <Card title="Alerts by severity" subtitle="Distribution of alerts created in the window">
+ <div className="space-y-2">
+ {SEVERITY_ORDER.map((sev) => {
+ const count = digest.alerts.severity[sev] ?? 0;
+ const pct = digest.alerts.total > 0 ? (count / digest.alerts.total) * 100 : 0;
+ return (
+ <div key={sev} className="flex items-center gap-3 text-sm">
+ <span className={`w-20 capitalize ${SEVERITY_TEXT[sev]}`}>{sev}</span>
+ <div className="h-2 flex-1 overflow-hidden rounded-full bg-gray-800">
+ <div
+ className="h-full rounded-full bg-violet-500"
+ style={{ width: `${Math.min(100, Math.max(0, pct))}%` }}
+ />
+ </div>
+ <span className="w-14 text-right text-gray-200 tabular-nums">{count}</span>
+ </div>
+ );
+ })}
+ </div>
+ </Card>
+
+ <Card title="Automation" subtitle="Remediation gate decisions in the window">
+ <dl className="grid grid-cols-2 gap-4 text-sm">
+ <Stat label="Total decisions" value={digest.automation.total_decisions} />
+ <Stat label="Auto-executed" value={digest.automation.auto_executed} accent="text-emerald-300" />
+ <Stat label="Escalated" value={digest.automation.escalated} accent="text-amber-300" />
+ <Stat label="Review pending" value={digest.automation.review_pending} accent="text-sky-300" />
+ </dl>
+ <p className="mt-4 text-xs text-gray-500">
+ {digest.automation.total_decisions === 0
+ ? 'No remediation decisions logged this period.'
+ : `${
+ Math.round(
+ (digest.automation.auto_executed / Math.max(1, digest.automation.total_decisions)) * 1000,
+ ) / 10
+ }% of decisions executed without analyst intervention.`}
+ </p>
+ </Card>
+ </section>
+
+ {/* Top tactics + top sources */}
+ <section className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+ <Card title="Top MITRE tactics" subtitle="Vs. prior comparable window">
+ {digest.top_tactics.length === 0 ? (
+ <p className="text-sm text-gray-500">No tactic-tagged alerts in this window.</p>
+ ) : (
+ <ul className="divide-y divide-gray-800">
+ {digest.top_tactics.map((t) => (
+ <li key={t.tactic} className="flex items-center justify-between py-2 text-sm">
+ <span className="text-gray-200">{t.tactic}</span>
+ <span className="flex items-center gap-3">
+ <span className="text-white tabular-nums">{t.count}</span>
+ <span className={`text-xs tabular-nums ${deltaClass(t.delta_from_prior)}`}>
+ {fmtDelta(t.delta_from_prior)}
+ </span>
+ </span>
+ </li>
+ ))}
+ </ul>
+ )}
+ </Card>
+
+ <Card title="Top alert sources" subtitle="Connectors driving the most volume">
+ {digest.top_sources.length === 0 ? (
+ <p className="text-sm text-gray-500">No connector-tagged alerts in this window.</p>
+ ) : (
+ <ul className="divide-y divide-gray-800">
+ {digest.top_sources.map((s) => (
+ <li key={s.connector_type} className="flex items-center justify-between py-2 text-sm">
+ <span className="text-gray-200">{s.connector_type}</span>
+ <span className="text-white tabular-nums">{s.count}</span>
+ </li>
+ ))}
+ </ul>
+ )}
+ </Card>
+ </section>
+
+ {/* High-risk alerts */}
+ <Card
+ title="Highest-risk alerts"
+ subtitle="Top alerts ranked by AI score and severity in the window"
+ >
+ {digest.high_risk_alerts.length === 0 ? (
+ <p className="text-sm text-gray-500">No high-risk alerts surfaced this period.</p>
+ ) : (
+ <div className="overflow-x-auto">
+ <table className="w-full min-w-[640px] text-left text-sm">
+ <thead>
+ <tr className="border-b border-gray-700 text-xs uppercase tracking-wide text-gray-500">
+ <th className="py-2 pr-4 font-medium">Title</th>
+ <th className="py-2 pr-4 font-medium">Severity</th>
+ <th className="py-2 pr-4 font-medium">AI score</th>
+ <th className="py-2 pr-4 font-medium">Tactics</th>
+ <th className="py-2 font-medium">Event time</th>
+ </tr>
+ </thead>
+ <tbody>
+ {digest.high_risk_alerts.map((a) => (
+ <tr key={a.alert_id} className="border-b border-gray-800/80">
+ <td className="py-2.5 pr-4 text-gray-100">{a.title || a.alert_id}</td>
+ <td className={`py-2.5 pr-4 capitalize ${SEVERITY_TEXT[a.severity] ?? 'text-gray-300'}`}>
+ {a.severity}
+ </td>
+ <td className="py-2.5 pr-4 text-gray-200 tabular-nums">
+ {a.ai_score === null || a.ai_score === undefined
+ ? '—'
+ : a.ai_score.toFixed(2)}
+ </td>
+ <td className="py-2.5 pr-4 text-gray-400">
+ {a.mitre_tactics.length === 0 ? '—' : a.mitre_tactics.join(', ')}
+ </td>
+ <td className="py-2.5 text-gray-400">{fmtDate(a.event_time)}</td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ )}
+ </Card>
+
+ {/* Recommendations */}
+ <Card
+ title="Recommendations"
+ subtitle="Auto-generated, deterministic guidance based on this window's signals"
+ >
+ {digest.recommendations.length === 0 ? (
+ <p className="text-sm text-gray-500">No recommendations triggered for this period.</p>
+ ) : (
+ <ul className="space-y-3">
+ {digest.recommendations.map((r, idx) => (
+ <li
+ key={`${r.title}-${idx}`}
+ className={`rounded-lg border p-4 ${
+ RECOMMENDATION_ACCENT[r.severity] ?? RECOMMENDATION_ACCENT.info
+ }`}
+ >
+ <p className="text-sm font-semibold">{r.title}</p>
+ <p className="mt-1 text-sm leading-relaxed opacity-90">{r.body}</p>
+ </li>
+ ))}
+ </ul>
+ )}
+ </Card>
+ </>
+ );
+}
+
+function Card({
+ title,
+ subtitle,
+ children,
+}: {
+ title: string;
+ subtitle?: string;
+ children: React.ReactNode;
+}) {
+ return (
+ <div className="rounded-xl border border-gray-700 bg-gray-900 p-5">
+ <div className="mb-4">
+ <h2 className="text-base font-semibold text-white">{title}</h2>
+ {subtitle && <p className="mt-0.5 text-xs text-gray-500">{subtitle}</p>}
+ </div>
+ {children}
+ </div>
+ );
+}
+
+function KpiCard({
+ label,
+ value,
+ sub,
+}: {
+ label: string;
+ value: number | string;
+ sub?: string;
+}) {
+ return (
+ <div className="rounded-lg border border-gray-700 bg-gray-800 p-4">
+ <p className="text-xs text-gray-400">{label}</p>
+ <p className="mt-1 text-2xl font-semibold text-white tabular-nums">{value}</p>
+ {sub && <p className="mt-1 text-xs text-gray-500">{sub}</p>}
+ </div>
+ );
+}
+
+function Stat({
+ label,
+ value,
+ accent,
+}: {
+ label: string;
+ value: number | string;
+ accent?: string;
+}) {
+ return (
+ <div>
+ <dt className="text-xs text-gray-500">{label}</dt>
+ <dd className={`mt-1 text-xl font-semibold tabular-nums ${accent ?? 'text-white'}`}>{value}</dd>
+ </div>
+ );
+}
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index ec4972ea7..a06302c09 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -3132,6 +3132,149 @@ export const deploymentApi = {
getLlmStatus: () => request<LlmStatus>('/api/v1/llm/status'),
};
+// ─── Reports / Executive digest (WS-G2) ─────────────────────────────────────
+
+export interface DigestPeriod {
+ start: string;
+ end: string;
+ label: string;
+}
+
+export interface SeveritySplit {
+ critical: number;
+ high: number;
+ medium: number;
+ low: number;
+ info: number;
+}
+
+export interface AlertSummary {
+ total: number;
+ new: number;
+ resolved: number;
+ open_at_period_end: number;
+ severity: SeveritySplit;
+}
+
+export interface CaseSummary {
+ opened: number;
+ closed: number;
+ open_at_period_end: number;
+ sla_breached: number;
+}
+
+export interface MttSummary {
+ mttd_hours: number | null;
+ mttr_hours: number | null;
+ mttc_hours: number | null;
+}
+
+export interface TacticHighlight {
+ tactic: string;
+ count: number;
+ delta_from_prior: number;
+}
+
+export interface TopSourceHighlight {
+ connector_type: string;
+ count: number;
+}
+
+export interface HighRiskAlertHighlight {
+ alert_id: string;
+ title: string;
+ severity: string;
+ ai_score: number | null;
+ mitre_tactics: string[];
+ event_time: string;
+}
+
+export interface AutomationSummary {
+ total_decisions: number;
+ auto_executed: number;
+ escalated: number;
+ review_pending: number;
+}
+
+export interface DigestRecommendation {
+ severity: 'info' | 'warning' | 'critical' | string;
+ title: string;
+ body: string;
+}
+
+export interface ExecutiveDigest {
+ tenant_id: string;
+ period: DigestPeriod;
+ headline: string;
+ alerts: AlertSummary;
+ cases: CaseSummary;
+ mtt: MttSummary;
+ top_tactics: TacticHighlight[];
+ top_sources: TopSourceHighlight[];
+ high_risk_alerts: HighRiskAlertHighlight[];
+ automation: AutomationSummary;
+ recommendations: DigestRecommendation[];
+}
+
+export interface WeeklyDigestParams {
+ /** ISO timestamp for the start of the window. Defaults to now-7d on the API. */
+ period_start?: string;
+ /** ISO timestamp for the end of the window. Defaults to now on the API. */
+ period_end?: string;
+}
+
+export const reportsApi = {
+ /**
+ * Fetch the executive weekly digest for the current tenant as structured
+ * JSON suitable for rendering an interactive panel in the web UI.
+ */
+ weeklyDigest: (params: WeeklyDigestParams = {}) =>
+ request<ExecutiveDigest>('/api/v1/reports/digest/weekly', {
+ params: { format: 'json', ...params },
+ }),
+
+ /**
+ * Fetch the print-ready HTML representation of the weekly digest as a string.
+ * Pairs naturally with `URL.createObjectURL(new Blob([html], …))` so the UI
+ * can pop a new tab and let the browser's native "Save as PDF" produce the
+ * board-ready document — no server-side PDF dependency required.
+ *
+ * Goes through the shared `request()` plumbing so it inherits the same auth
+ * (cookie + optional localStorage bearer) and tenant header treatment as the
+ * JSON variant.
+ */
+ weeklyDigestHtml: async (params: WeeklyDigestParams = {}): Promise<string> => {
+ const search = new URLSearchParams({ format: 'html' });
+ if (params.period_start) search.set('period_start', params.period_start);
+ if (params.period_end) search.set('period_end', params.period_end);
+
+ const headers: Record<string, string> = {
+ Accept: 'text/html',
+ 'X-Tenant-Id': TENANT_ID,
+ };
+ if (typeof window !== 'undefined') {
+ try {
+ const token = window.localStorage.getItem(AUTH_TOKEN_KEY);
+ if (token) headers.Authorization = `Bearer ${token}`;
+ } catch {
+ /* localStorage unavailable; ignore */
+ }
+ }
+
+ const url = `${API_BASE}/api/v1/reports/digest/weekly?${search.toString()}`;
+ const response = await fetch(url, { headers, cache: 'no-store' });
+ if (!response.ok) {
+ const detail = await response.text().catch(() => '');
+ throw new ApiError(
+ `API ${response.status} ${response.statusText} — /reports/digest/weekly`,
+ response.status,
+ detail,
+ );
+ }
+ return response.text();
+ },
+};
+
// ─── Realtime / WebSocket helpers ────────────────────────────────────────────
export const realtimeApi = {
@@ -3175,4 +3318,5 @@ export default {
autonomyPolicy: autonomyPolicyApi,
feedback: feedbackApi,
deployment: deploymentApi,
+ reports: reportsApi,
};
diff --git a/services/api/app/api/v1/endpoints/reports.py b/services/api/app/api/v1/endpoints/reports.py
index cb97a4371..d6f72d8d6 100644
--- a/services/api/app/api/v1/endpoints/reports.py
+++ b/services/api/app/api/v1/endpoints/reports.py
@@ -7,6 +7,7 @@ from datetime import datetime
from typing import Any
from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi.responses import HTMLResponse
from pydantic import BaseModel, Field
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
@@ -15,6 +16,8 @@ from app.api.v1.endpoints.auth import get_current_user
from app.db.database import get_db
from app.models.report import ReportArtefact, ReportTemplate
from app.models.tenant import User
+from app.services.digest_html import render_digest_html
+from app.services.executive_digest import ExecutiveDigest, build_weekly_digest
router = APIRouter(prefix="/reports", tags=["reports"])
@@ -192,3 +195,48 @@ async def get_artefact(
if not art or art.tenant_id != current_user.tenant_id:
raise HTTPException(status_code=404, detail="Artefact not found")
return art
+
+
+# ---------------------------------------------------------------------------
+# Executive weekly digest (WS-G2)
+# ---------------------------------------------------------------------------
+
+
+ "/digest/weekly",
+ summary="Executive weekly digest (JSON or print-ready HTML)",
+ # The endpoint returns either an ExecutiveDigest (JSON) or an HTMLResponse
+ # depending on the ?format= query param. FastAPI cannot synthesise a
+ # response_model from that union, so we opt out and let each branch
+ # serialise itself (Pydantic for JSON, HTMLResponse for HTML).
+ response_model=None,
+)
+async def weekly_digest(
+ fmt: str = Query("json", alias="format", pattern="^(json|html)$"),
+ period_start: datetime | None = Query(None, description="ISO timestamp; defaults to now-7d"),
+ period_end: datetime | None = Query(None, description="ISO timestamp; defaults to now"),
+ db: AsyncSession = Depends(get_db),
+ current_user: User = Depends(get_current_user),
+) -> ExecutiveDigest | HTMLResponse:
+ """Build a deterministic weekly digest for the caller's tenant.
+
+ The default window is the most recent seven days. Pass ``format=html`` to
+ receive a self-contained, print-ready document (use the browser's
+ "Save as PDF" to export).
+ """
+ if period_start and period_end and period_start >= period_end:
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail="period_start must be earlier than period_end",
+ )
+
+ digest = await build_weekly_digest(
+ db,
+ current_user.tenant_id,
+ period_start=period_start,
+ period_end=period_end,
+ )
+
+ if fmt == "html":
+ return HTMLResponse(content=render_digest_html(digest))
+ return digest
diff --git a/services/api/app/services/digest_html.py b/services/api/app/services/digest_html.py
new file mode 100644
index 000000000..e7284db4d
--- /dev/null
+++ b/services/api/app/services/digest_html.py
@@ -0,0 +1,293 @@
+"""HTML renderer for the executive weekly digest.
+
+WS-G2 — buyer-value plan
+========================
+Produces a self-contained, print-ready HTML document for the
+``ExecutiveDigest``. No external template engine, no PDF dependency: the
+browser's own "Save as PDF" handles export.
+
+Design goals
+------------
+* Pure function — same digest in, same HTML out.
+* Inline CSS only, so the document remains portable when downloaded.
+* Print-friendly typography and colour-blind-safe palette.
+* Light theme by default (matches WS-F1 design tokens).
+* Defensive HTML escaping — digest fields originate from tenant data.
+"""
+
+from __future__ import annotations
+
+import html
+from datetime import UTC, datetime
+
+from .executive_digest import (
+ AutomationSummary,
+ DigestRecommendation,
+ ExecutiveDigest,
+ HighRiskAlertHighlight,
+ SeveritySplit,
+ TacticHighlight,
+ TopSourceHighlight,
+)
+
+
+_SEVERITY_COLOURS: dict[str, str] = {
+ "critical": "#b91c1c",
+ "high": "#c2410c",
+ "medium": "#a16207",
+ "low": "#1d4ed8",
+ "info": "#475569",
+}
+
+_REC_COLOURS: dict[str, str] = {
+ "critical": "#b91c1c",
+ "warning": "#a16207",
+ "info": "#1d4ed8",
+}
+
+
+def _esc(value: object) -> str:
+ """HTML-safe rendering for arbitrary values."""
+ return html.escape("" if value is None else str(value))
+
+
+def _fmt_hours(hours: float | None) -> str:
+ if hours is None:
+ return "—"
+ if hours < 1:
+ return f"{round(hours * 60)}m"
+ return f"{hours:.1f}h"
+
+
+def _fmt_datetime(value: datetime) -> str:
+ return value.strftime("%Y-%m-%d %H:%M UTC")
+
+
+def _severity_chip(severity: str) -> str:
+ colour = _SEVERITY_COLOURS.get(severity, "#475569")
+ return (
+ f'<span style="display:inline-block;padding:2px 8px;border-radius:9999px;'
+ f'background:{colour};color:#fff;font-size:11px;text-transform:uppercase;'
+ f'letter-spacing:0.04em;">{_esc(severity)}</span>'
+ )
+
+
+def _kpi(label: str, value: str, *, hint: str | None = None) -> str:
+ hint_html = (
+ f'<div style="font-size:11px;color:#64748b;margin-top:2px;">{_esc(hint)}</div>'
+ if hint
+ else ""
+ )
+ return (
+ '<div style="flex:1 1 140px;background:#f8fafc;border:1px solid #e2e8f0;'
+ 'border-radius:8px;padding:12px 14px;min-width:140px;">'
+ f'<div style="font-size:11px;color:#64748b;text-transform:uppercase;'
+ f'letter-spacing:0.06em;">{_esc(label)}</div>'
+ f'<div style="font-size:22px;font-weight:600;color:#0f172a;'
+ f'margin-top:4px;">{_esc(value)}</div>'
+ f"{hint_html}</div>"
+ )
+
+
+def _severity_table(split: SeveritySplit) -> str:
+ rows: list[tuple[str, int]] = [
+ ("Critical", split.critical),
+ ("High", split.high),
+ ("Medium", split.medium),
+ ("Low", split.low),
+ ("Info", split.info),
+ ]
+ cells = "".join(
+ f'<tr><td style="padding:4px 8px;color:#0f172a;">'
+ f"{_severity_chip(label.lower())}</td>"
+ f'<td style="padding:4px 8px;text-align:right;font-weight:600;">{count}</td></tr>'
+ for label, count in rows
+ )
+ return (
+ '<table style="width:100%;border-collapse:collapse;font-size:13px;">'
+ f"<tbody>{cells}</tbody></table>"
+ )
+
+
+def _tactic_rows(tactics: list[TacticHighlight]) -> str:
+ if not tactics:
+ return (
+ '<p style="color:#64748b;font-size:13px;">No MITRE-tagged alerts in this period.</p>'
+ )
+ body = "".join(
+ f'<tr><td style="padding:6px 8px;">{_esc(t.tactic)}</td>'
+ f'<td style="padding:6px 8px;text-align:right;font-weight:600;">{t.count}</td>'
+ f'<td style="padding:6px 8px;text-align:right;color:'
+ f'{"#b91c1c" if t.delta_from_prior > 0 else "#15803d" if t.delta_from_prior < 0 else "#64748b"};">'
+ f"{'+' if t.delta_from_prior > 0 else ''}{t.delta_from_prior}</td></tr>"
+ for t in tactics
+ )
+ return (
+ '<table style="width:100%;border-collapse:collapse;font-size:13px;">'
+ '<thead><tr style="text-align:left;color:#64748b;font-size:11px;'
+ 'text-transform:uppercase;letter-spacing:0.06em;">'
+ '<th style="padding:6px 8px;">Tactic</th>'
+ '<th style="padding:6px 8px;text-align:right;">Count</th>'
+ '<th style="padding:6px 8px;text-align:right;">Δ vs prior</th></tr></thead>'
+ f"<tbody>{body}</tbody></table>"
+ )
+
+
+def _source_rows(sources: list[TopSourceHighlight]) -> str:
+ if not sources:
+ return (
+ '<p style="color:#64748b;font-size:13px;">No connector activity in this period.</p>'
+ )
+ body = "".join(
+ f'<tr><td style="padding:6px 8px;">{_esc(s.connector_type)}</td>'
+ f'<td style="padding:6px 8px;text-align:right;font-weight:600;">{s.count}</td></tr>'
+ for s in sources
+ )
+ return (
+ '<table style="width:100%;border-collapse:collapse;font-size:13px;">'
+ f"<tbody>{body}</tbody></table>"
+ )
+
+
+def _high_risk_table(items: list[HighRiskAlertHighlight]) -> str:
+ if not items:
+ return (
+ '<p style="color:#64748b;font-size:13px;">No high-risk alerts surfaced this period.</p>'
+ )
+ body = "".join(
+ "<tr>"
+ f'<td style="padding:6px 8px;">{_severity_chip(a.severity)}</td>'
+ f'<td style="padding:6px 8px;color:#0f172a;">{_esc(a.title)}</td>'
+ f'<td style="padding:6px 8px;color:#475569;">{_esc(", ".join(a.mitre_tactics)) or "—"}</td>'
+ f'<td style="padding:6px 8px;text-align:right;font-variant-numeric:tabular-nums;">'
+ f"{a.ai_score if a.ai_score is not None else '—'}</td>"
+ f'<td style="padding:6px 8px;color:#64748b;font-size:11px;'
+ f'white-space:nowrap;">{_fmt_datetime(a.event_time)}</td></tr>'
+ for a in items
+ )
+ return (
+ '<table style="width:100%;border-collapse:collapse;font-size:13px;">'
+ '<thead><tr style="text-align:left;color:#64748b;font-size:11px;'
+ 'text-transform:uppercase;letter-spacing:0.06em;">'
+ '<th style="padding:6px 8px;">Severity</th>'
+ '<th style="padding:6px 8px;">Title</th>'
+ '<th style="padding:6px 8px;">Tactics</th>'
+ '<th style="padding:6px 8px;text-align:right;">AI score</th>'
+ '<th style="padding:6px 8px;">Event time</th></tr></thead>'
+ f"<tbody>{body}</tbody></table>"
+ )
+
+
+def _automation_block(automation: AutomationSummary) -> str:
+ total = max(automation.total_decisions, 1)
+ auto_pct = round(automation.auto_executed / total * 100)
+ review_pct = round(automation.review_pending / total * 100)
+ escalate_pct = round(automation.escalated / total * 100)
+ return (
+ '<div style="display:flex;flex-wrap:wrap;gap:12px;">'
+ + _kpi("Decisions", str(automation.total_decisions))
+ + _kpi("Auto-executed", f"{automation.auto_executed}", hint=f"{auto_pct}%")
+ + _kpi("Review pending", f"{automation.review_pending}", hint=f"{review_pct}%")
+ + _kpi("Escalated", f"{automation.escalated}", hint=f"{escalate_pct}%")
+ + "</div>"
+ )
+
+
+def _recommendation_cards(recs: list[DigestRecommendation]) -> str:
+ if not recs:
+ return ""
+ cards = "".join(
+ '<div style="border-left:4px solid {colour};background:{bg};'
+ "padding:12px 14px;border-radius:6px;margin-bottom:10px;\">"
+ '<div style="font-weight:600;color:#0f172a;font-size:14px;'
+ f'margin-bottom:4px;">{_esc(r.title)}</div>'
+ f'<div style="color:#334155;font-size:13px;line-height:1.45;">{_esc(r.body)}</div>'
+ "</div>".format(colour=_REC_COLOURS.get(r.severity, "#475569"), bg="#f8fafc")
+ for r in recs
+ )
+ return cards
+
+
+def render_digest_html(digest: ExecutiveDigest) -> str:
+ """Render an ``ExecutiveDigest`` to a self-contained HTML document."""
+ headline = _esc(digest.headline)
+ period = digest.period
+
+ return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>AiSOC Executive Digest — {_esc(period.label)}</title>
+<style>
+ @page {{ margin: 18mm; }}
+ body {{
+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+ color: #0f172a;
+ background: #ffffff;
+ margin: 0;
+ padding: 24px 32px;
+ line-height: 1.45;
+ }}
+ h1, h2, h3 {{ color: #0f172a; margin-top: 0; }}
+ h1 {{ font-size: 22px; margin-bottom: 4px; }}
+ h2 {{ font-size: 15px; text-transform: uppercase; letter-spacing: 0.08em; color: #475569; margin: 20px 0 10px; border-top: 1px solid #e2e8f0; padding-top: 14px; }}
+ table th, table td {{ border-bottom: 1px solid #f1f5f9; }}
+ @media print {{
+ body {{ padding: 0; }}
+ h2 {{ page-break-after: avoid; }}
+ }}
+</style>
+</head>
+<body>
+ <header>
+ <div style="font-size:11px;color:#64748b;text-transform:uppercase;letter-spacing:0.08em;">
+ AiSOC weekly executive digest
+ </div>
+ <h1>{_esc(period.label)}</h1>
+ <div style="color:#334155;font-size:14px;margin-top:6px;">{headline}</div>
+ <div style="color:#94a3b8;font-size:11px;margin-top:6px;">
+ Tenant {_esc(digest.tenant_id)} · generated {_fmt_datetime(datetime.now(UTC))}
+ </div>
+ </header>
+
+ <h2>Headline metrics</h2>
+ <div style="display:flex;flex-wrap:wrap;gap:12px;">
+ {_kpi("Alerts (total seen)", str(digest.alerts.total))}
+ {_kpi("New this period", str(digest.alerts.new))}
+ {_kpi("Resolved", str(digest.alerts.resolved))}
+ {_kpi("Open at period end", str(digest.alerts.open_at_period_end))}
+ {_kpi("Cases opened", str(digest.cases.opened))}
+ {_kpi("Cases closed", str(digest.cases.closed))}
+ {_kpi("SLA breaches", str(digest.cases.sla_breached))}
+ {_kpi("MTTD", _fmt_hours(digest.mtt.mttd_hours))}
+ {_kpi("MTTR", _fmt_hours(digest.mtt.mttr_hours))}
+ {_kpi("MTTC", _fmt_hours(digest.mtt.mttc_hours))}
+ </div>
+
+ <h2>Severity distribution</h2>
+ {_severity_table(digest.alerts.severity)}
+
+ <h2>Top MITRE tactics</h2>
+ {_tactic_rows(digest.top_tactics)}
+
+ <h2>Top alert sources</h2>
+ {_source_rows(digest.top_sources)}
+
+ <h2>High-risk alerts</h2>
+ {_high_risk_table(digest.high_risk_alerts)}
+
+ <h2>Automation</h2>
+ {_automation_block(digest.automation)}
+
+ <h2>Recommendations</h2>
+ {_recommendation_cards(digest.recommendations)}
+
+ <footer style="margin-top:32px;color:#94a3b8;font-size:11px;text-align:center;">
+ AiSOC — open-source AI Security Operations Center.
+ Print this page (Ctrl/Cmd-P → Save as PDF) for board-ready archival.
+ </footer>
+</body>
+</html>"""
+
+
+__all__ = ["render_digest_html"]
diff --git a/services/api/app/services/executive_digest.py b/services/api/app/services/executive_digest.py
new file mode 100644
index 000000000..83daadf7e
--- /dev/null
+++ b/services/api/app/services/executive_digest.py
@@ -0,0 +1,722 @@
+"""Executive weekly digest builder.
+
+WS-G2 — buyer-value plan
+========================
+Produces a deterministic, board-ready snapshot of the SOC over a fixed window
+(default: the last 7 days). The output is plain Python dataclasses /
+dictionaries that downstream renderers convert into:
+
+ * JSON — for the web UI to render an interactive panel.
+ * HTML — for `print to PDF` (no external PDF dependency required).
+
+The module is intentionally split into:
+
+ 1. ``build_digest_from_rows`` — a *pure* function that consumes already-
+ queried rows and produces an ``ExecutiveDigest``. This is what tests
+ exercise; it has no async / DB dependencies and is fully deterministic.
+
+ 2. ``build_weekly_digest`` — a thin async orchestrator that runs SQL
+ queries against the live tenant database and forwards rows into the
+ pure builder. It contains *only* DB plumbing.
+
+Keeping the heavy logic pure means we can ship a 100% deterministic test
+matrix without spinning up Postgres, and we can later swap the data layer
+(e.g. read replicas, OLAP store) without touching the digest contract.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections import Counter
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+from pydantic import BaseModel, Field
+from sqlalchemy import and_, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.alert import Alert
+from app.models.case import Case
+from app.models.remediation import RemediationGateLog
+
+
+# ---------------------------------------------------------------------------
+# Output schemas (Pydantic) — what the endpoint actually returns.
+# ---------------------------------------------------------------------------
+
+
+class DigestPeriod(BaseModel):
+ start: datetime
+ end: datetime
+ label: str # e.g. "May 2 – May 9, 2026"
+
+
+class SeveritySplit(BaseModel):
+ critical: int = 0
+ high: int = 0
+ medium: int = 0
+ low: int = 0
+ info: int = 0
+
+
+class AlertSummary(BaseModel):
+ total: int
+ new: int
+ resolved: int
+ open_at_period_end: int
+ severity: SeveritySplit
+
+
+class CaseSummary(BaseModel):
+ opened: int
+ closed: int
+ open_at_period_end: int
+ sla_breached: int
+
+
+class MttSummary(BaseModel):
+ """Mean time-to-X in hours (None if no qualifying samples)."""
+
+ mttd_hours: float | None
+ mttr_hours: float | None
+ mttc_hours: float | None
+
+
+class TacticHighlight(BaseModel):
+ tactic: str
+ count: int
+ delta_from_prior: int # positive = increase vs prior week
+
+
+class TopSourceHighlight(BaseModel):
+ connector_type: str
+ count: int
+
+
+class HighRiskAlertHighlight(BaseModel):
+ alert_id: str
+ title: str
+ severity: str
+ ai_score: float | None
+ mitre_tactics: list[str]
+ event_time: datetime
+
+
+class AutomationSummary(BaseModel):
+ total_decisions: int
+ auto_executed: int
+ escalated: int
+ review_pending: int
+
+
+class DigestRecommendation(BaseModel):
+ severity: str # "info" | "warning" | "critical"
+ title: str
+ body: str
+
+
+class ExecutiveDigest(BaseModel):
+ """Top-level deterministic snapshot of one digest window."""
+
+ tenant_id: uuid.UUID
+ period: DigestPeriod
+ headline: str
+ alerts: AlertSummary
+ cases: CaseSummary
+ mtt: MttSummary
+ top_tactics: list[TacticHighlight] = Field(default_factory=list)
+ top_sources: list[TopSourceHighlight] = Field(default_factory=list)
+ high_risk_alerts: list[HighRiskAlertHighlight] = Field(default_factory=list)
+ automation: AutomationSummary
+ recommendations: list[DigestRecommendation] = Field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Pure-data input rows — what the orchestrator hands to the builder.
+# Plain dataclasses keep the test surface decoupled from SQLAlchemy.
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AlertRow:
+ severity: str
+ status: str
+ created_at: datetime
+ resolved_at: datetime | None
+ first_seen_at: datetime | None
+ disposition: str | None
+ mitre_tactics: list[str]
+ connector_type: str | None
+ ai_score: float | None
+ title: str
+ alert_id: str
+ event_time: datetime
+
+
+@dataclass(frozen=True)
+class CaseRow:
+ status: str
+ created_at: datetime
+ closed_at: datetime | None
+ sla_breached: bool
+
+
+@dataclass(frozen=True)
+class GateLogRow:
+ decision: str # "auto" | "review" | "escalate" | other
+
+
+@dataclass
+class DigestInputs:
+ """Bundle of pre-fetched rows for a tenant + period."""
+
+ tenant_id: uuid.UUID
+ period_start: datetime
+ period_end: datetime
+ current_alerts: list[AlertRow] = field(default_factory=list)
+ prior_alerts: list[AlertRow] = field(default_factory=list)
+ cases: list[CaseRow] = field(default_factory=list)
+ gate_log: list[GateLogRow] = field(default_factory=list)
+ open_alerts_at_period_end: int = 0
+ open_cases_at_period_end: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers (independently unit-tested).
+# ---------------------------------------------------------------------------
+
+
+def _format_period_label(start: datetime, end: datetime) -> str:
+ """Render a human-friendly span like "May 2 – May 9, 2026".
+
+ Inclusive on the end side for readability; the actual query uses [start, end).
+ """
+ same_year = start.year == end.year
+ same_month = same_year and start.month == end.month
+ if same_month:
+ return f"{start.strftime('%b %-d')} – {end.strftime('%-d, %Y')}"
+ if same_year:
+ return f"{start.strftime('%b %-d')} – {end.strftime('%b %-d, %Y')}"
+ return f"{start.strftime('%b %-d, %Y')} – {end.strftime('%b %-d, %Y')}"
+
+
+def _severity_split(rows: list[AlertRow]) -> SeveritySplit:
+ counts = Counter(r.severity for r in rows)
+ return SeveritySplit(
+ critical=counts.get("critical", 0),
+ high=counts.get("high", 0),
+ medium=counts.get("medium", 0),
+ low=counts.get("low", 0),
+ info=counts.get("info", 0),
+ )
+
+
+def _mean_hours(deltas: list[timedelta]) -> float | None:
+ if not deltas:
+ return None
+ seconds = sum(d.total_seconds() for d in deltas)
+ return round(seconds / len(deltas) / 3600, 2)
+
+
+def _compute_mtt(rows: list[AlertRow]) -> MttSummary:
+ """MTTD/MTTR/MTTC over a window."""
+ detect: list[timedelta] = []
+ respond: list[timedelta] = []
+ contain: list[timedelta] = []
+
+ for r in rows:
+ if r.first_seen_at and r.first_seen_at >= r.created_at:
+ detect.append(r.first_seen_at - r.created_at)
+ if r.resolved_at and r.resolved_at >= r.created_at:
+ respond.append(r.resolved_at - r.created_at)
+ if r.disposition == "true_positive":
+ contain.append(r.resolved_at - r.created_at)
+
+ return MttSummary(
+ mttd_hours=_mean_hours(detect),
+ mttr_hours=_mean_hours(respond),
+ mttc_hours=_mean_hours(contain),
+ )
+
+
+def _tactic_counts(rows: list[AlertRow]) -> Counter[str]:
+ counter: Counter[str] = Counter()
+ for r in rows:
+ for tactic in r.mitre_tactics or []:
+ if isinstance(tactic, str) and tactic.strip():
+ counter[tactic.strip()] += 1
+ return counter
+
+
+def _top_tactics(
+ current: list[AlertRow],
+ prior: list[AlertRow],
+ *,
+ limit: int = 5,
+) -> list[TacticHighlight]:
+ cur = _tactic_counts(current)
+ pri = _tactic_counts(prior)
+ highlights = [
+ TacticHighlight(
+ tactic=tactic,
+ count=count,
+ delta_from_prior=count - pri.get(tactic, 0),
+ )
+ for tactic, count in cur.most_common(limit)
+ ]
+ return highlights
+
+
+def _top_sources(rows: list[AlertRow], *, limit: int = 5) -> list[TopSourceHighlight]:
+ counter: Counter[str] = Counter()
+ for r in rows:
+ if r.connector_type:
+ counter[r.connector_type] += 1
+ return [
+ TopSourceHighlight(connector_type=ct, count=cnt)
+ for ct, cnt in counter.most_common(limit)
+ ]
+
+
+def _high_risk_alerts(rows: list[AlertRow], *, limit: int = 5) -> list[HighRiskAlertHighlight]:
+ """Return the top N alerts ranked by severity then ai_score then time.
+
+ Severity ranking is deterministic regardless of input order.
+ """
+ severity_rank = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}
+
+ def sort_key(r: AlertRow) -> tuple[int, float, datetime]:
+ sev = severity_rank.get(r.severity, 5)
+ # Higher AI score = more interesting; flip the sign so it sorts ascending.
+ score = -1.0 * (r.ai_score if r.ai_score is not None else 0.0)
+ # More recent first
+ # Subtract from a fixed epoch so ordering is purely deterministic.
+ return (sev, score, -r.event_time.timestamp())
+
+ ranked = sorted(rows, key=sort_key)[:limit]
+ return [
+ HighRiskAlertHighlight(
+ alert_id=r.alert_id,
+ title=r.title,
+ severity=r.severity,
+ ai_score=r.ai_score,
+ mitre_tactics=list(r.mitre_tactics or []),
+ event_time=r.event_time,
+ )
+ for r in ranked
+ ]
+
+
+def _automation_summary(gate_log: list[GateLogRow]) -> AutomationSummary:
+ counts = Counter(g.decision for g in gate_log)
+ return AutomationSummary(
+ total_decisions=len(gate_log),
+ auto_executed=counts.get("auto", 0),
+ escalated=counts.get("escalate", 0),
+ review_pending=counts.get("review", 0),
+ )
+
+
+def _case_summary(rows: list[CaseRow], open_at_end: int, period_start: datetime, period_end: datetime) -> CaseSummary:
+ opened = sum(1 for r in rows if period_start <= r.created_at < period_end)
+ closed = sum(
+ 1
+ for r in rows
+ if r.closed_at is not None and period_start <= r.closed_at < period_end
+ )
+ breached = sum(1 for r in rows if r.sla_breached)
+ return CaseSummary(
+ opened=opened,
+ closed=closed,
+ open_at_period_end=open_at_end,
+ sla_breached=breached,
+ )
+
+
+def _alert_summary(
+ rows: list[AlertRow],
+ open_at_end: int,
+ period_start: datetime,
+ period_end: datetime,
+) -> AlertSummary:
+ new = sum(1 for r in rows if period_start <= r.created_at < period_end)
+ resolved = sum(
+ 1
+ for r in rows
+ if r.resolved_at is not None and period_start <= r.resolved_at < period_end
+ )
+ return AlertSummary(
+ total=len(rows),
+ new=new,
+ resolved=resolved,
+ open_at_period_end=open_at_end,
+ severity=_severity_split(rows),
+ )
+
+
+def _build_headline(alerts: AlertSummary, mtt: MttSummary, automation: AutomationSummary) -> str:
+ """One-line summary the CISO sees first."""
+ parts: list[str] = []
+ parts.append(f"{alerts.new} alerts ingested")
+ if alerts.severity.critical:
+ parts.append(f"{alerts.severity.critical} critical")
+ parts.append(f"{alerts.resolved} resolved")
+ if mtt.mttr_hours is not None:
+ parts.append(f"MTTR {mtt.mttr_hours:.1f}h")
+ if automation.total_decisions:
+ auto_pct = round(automation.auto_executed / automation.total_decisions * 100)
+ parts.append(f"{auto_pct}% auto-actioned")
+ return " · ".join(parts)
+
+
+def _build_recommendations(
+ alerts: AlertSummary,
+ cases: CaseSummary,
+ mtt: MttSummary,
+ automation: AutomationSummary,
+ top_tactics: list[TacticHighlight],
+) -> list[DigestRecommendation]:
+ """Heuristic, deterministic CISO-facing call-to-actions.
+
+ All thresholds are fixed and explainable; no ML required.
+ """
+ recs: list[DigestRecommendation] = []
+
+ if alerts.severity.critical >= 5:
+ recs.append(
+ DigestRecommendation(
+ severity="critical",
+ title="Critical alert surge",
+ body=(
+ f"{alerts.severity.critical} critical-severity alerts this period — "
+ "review the high-risk-alerts table below and confirm ownership."
+ ),
+ )
+ )
+
+ if cases.sla_breached > 0:
+ recs.append(
+ DigestRecommendation(
+ severity="warning",
+ title=f"{cases.sla_breached} SLA breach{'es' if cases.sla_breached != 1 else ''}",
+ body=(
+ "One or more cases breached their SLA. Check assignment, escalation "
+ "paths, and on-call coverage."
+ ),
+ )
+ )
+
+ if mtt.mttr_hours is not None and mtt.mttr_hours > 24.0:
+ recs.append(
+ DigestRecommendation(
+ severity="warning",
+ title=f"MTTR is {mtt.mttr_hours:.1f}h",
+ body=(
+ "Mean time to respond exceeded 24h. Consider tuning playbooks, "
+ "auto-actions for high-confidence detections, or analyst staffing."
+ ),
+ )
+ )
+
+ if automation.total_decisions and automation.review_pending / max(automation.total_decisions, 1) > 0.3:
+ recs.append(
+ DigestRecommendation(
+ severity="info",
+ title="High review-queue ratio",
+ body=(
+ f"{automation.review_pending}/{automation.total_decisions} automation decisions "
+ "are still awaiting analyst review. Consider expanding the auto-execute "
+ "whitelist for low-blast-radius actions."
+ ),
+ )
+ )
+
+ rising = [t for t in top_tactics if t.delta_from_prior >= 5]
+ if rising:
+ names = ", ".join(t.tactic for t in rising[:3])
+ recs.append(
+ DigestRecommendation(
+ severity="info",
+ title="Rising MITRE tactics",
+ body=f"Notable week-over-week increase in {names}.",
+ )
+ )
+
+ if not recs:
+ recs.append(
+ DigestRecommendation(
+ severity="info",
+ title="No significant deviations",
+ body="All headline metrics are within expected bounds for this tenant.",
+ )
+ )
+
+ return recs
+
+
+# ---------------------------------------------------------------------------
+# Pure top-level builder.
+# ---------------------------------------------------------------------------
+
+
+def build_digest_from_rows(inputs: DigestInputs) -> ExecutiveDigest:
+ """Pure function: rows in → ExecutiveDigest out. Deterministic."""
+ period = DigestPeriod(
+ start=inputs.period_start,
+ end=inputs.period_end,
+ label=_format_period_label(inputs.period_start, inputs.period_end),
+ )
+
+ alerts = _alert_summary(
+ inputs.current_alerts,
+ inputs.open_alerts_at_period_end,
+ inputs.period_start,
+ inputs.period_end,
+ )
+ cases = _case_summary(
+ inputs.cases,
+ inputs.open_cases_at_period_end,
+ inputs.period_start,
+ inputs.period_end,
+ )
+ mtt = _compute_mtt(inputs.current_alerts)
+ top_tactics = _top_tactics(inputs.current_alerts, inputs.prior_alerts)
+ top_sources = _top_sources(inputs.current_alerts)
+ high_risk = _high_risk_alerts(inputs.current_alerts)
+ automation = _automation_summary(inputs.gate_log)
+ headline = _build_headline(alerts, mtt, automation)
+ recommendations = _build_recommendations(alerts, cases, mtt, automation, top_tactics)
+
+ return ExecutiveDigest(
+ tenant_id=inputs.tenant_id,
+ period=period,
+ headline=headline,
+ alerts=alerts,
+ cases=cases,
+ mtt=mtt,
+ top_tactics=top_tactics,
+ top_sources=top_sources,
+ high_risk_alerts=high_risk,
+ automation=automation,
+ recommendations=recommendations,
+ )
+
+
+# ---------------------------------------------------------------------------
+# DB orchestrator — the only place SQLAlchemy lives.
+# ---------------------------------------------------------------------------
+
+
+async def _fetch_alerts(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ start: datetime,
+ end: datetime,
+) -> list[AlertRow]:
+ rows: list[AlertRow] = []
+ result = await db.execute(
+ select(
+ Alert.id,
+ Alert.title,
+ Alert.severity,
+ Alert.status,
+ Alert.created_at,
+ Alert.resolved_at,
+ Alert.first_seen_at,
+ Alert.disposition,
+ Alert.mitre_tactics,
+ Alert.connector_type,
+ Alert.ai_score,
+ Alert.event_time,
+ ).where(
+ and_(
+ Alert.tenant_id == tenant_id,
+ Alert.created_at >= start,
+ Alert.created_at < end,
+ )
+ )
+ )
+ for r in result.all():
+ rows.append(
+ AlertRow(
+ alert_id=str(r.id),
+ title=r.title or "",
+ severity=r.severity or "info",
+ status=r.status or "new",
+ created_at=r.created_at,
+ resolved_at=r.resolved_at,
+ first_seen_at=r.first_seen_at,
+ disposition=r.disposition,
+ mitre_tactics=list(r.mitre_tactics or []),
+ connector_type=r.connector_type,
+ ai_score=float(r.ai_score) if r.ai_score is not None else None,
+ event_time=r.event_time or r.created_at,
+ )
+ )
+ return rows
+
+
+async def _fetch_cases(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ start: datetime,
+ end: datetime,
+) -> list[CaseRow]:
+ rows: list[CaseRow] = []
+ result = await db.execute(
+ select(
+ Case.status,
+ Case.created_at,
+ Case.closed_at,
+ Case.sla_breached,
+ ).where(
+ and_(
+ Case.tenant_id == tenant_id,
+ # Pull any case touched in the window: created OR closed in [start, end)
+ # We keep this simple: created_at filter for opens, closed_at filter for closes.
+ # Because we want both we union them.
+ # (start window ≤ end window — guarded at the endpoint.)
+ # SQLAlchemy doesn't have a clean OR boundary expression here,
+ # so use a permissive lower-bound: created_at >= start - 30d, then
+ # the pure builder filters precisely by date.
+ Case.created_at >= start - timedelta(days=30),
+ )
+ )
+ )
+ for r in result.all():
+ rows.append(
+ CaseRow(
+ status=r.status or "open",
+ created_at=r.created_at,
+ closed_at=r.closed_at,
+ sla_breached=bool(r.sla_breached),
+ )
+ )
+ return rows
+
+
+async def _fetch_gate_log(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ start: datetime,
+ end: datetime,
+) -> list[GateLogRow]:
+ result = await db.execute(
+ select(RemediationGateLog.decision).where(
+ and_(
+ RemediationGateLog.tenant_id == tenant_id,
+ RemediationGateLog.created_at >= start,
+ RemediationGateLog.created_at < end,
+ )
+ )
+ )
+ return [GateLogRow(decision=r.decision or "unknown") for r in result.all()]
+
+
+async def _count_open_alerts(db: AsyncSession, tenant_id: uuid.UUID, at: datetime) -> int:
+ """Open == not resolved as of `at`."""
+ val = await db.scalar(
+ select(func.count()).where(
+ and_(
+ Alert.tenant_id == tenant_id,
+ Alert.created_at < at,
+ Alert.status != "resolved",
+ Alert.status != "fp",
+ Alert.status != "closed",
+ )
+ )
+ )
+ return int(val or 0)
+
+
+async def _count_open_cases(db: AsyncSession, tenant_id: uuid.UUID, at: datetime) -> int:
+ val = await db.scalar(
+ select(func.count()).where(
+ and_(
+ Case.tenant_id == tenant_id,
+ Case.created_at < at,
+ Case.status != "resolved",
+ Case.status != "closed",
+ )
+ )
+ )
+ return int(val or 0)
+
+
+async def build_weekly_digest(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ *,
+ period_start: datetime | None = None,
+ period_end: datetime | None = None,
+) -> ExecutiveDigest:
+ """Async orchestrator: query the tenant DB and build an ``ExecutiveDigest``.
+
+ Defaults to the most recent 7-day window ending now.
+ """
+ end = period_end or datetime.now(UTC)
+ start = period_start or (end - timedelta(days=7))
+ if start >= end:
+ raise ValueError("period_start must be earlier than period_end")
+
+ prior_start = start - (end - start)
+ prior_end = start
+
+ current_alerts = await _fetch_alerts(db, tenant_id, start, end)
+ prior_alerts = await _fetch_alerts(db, tenant_id, prior_start, prior_end)
+ cases = await _fetch_cases(db, tenant_id, start, end)
+ gate_log = await _fetch_gate_log(db, tenant_id, start, end)
+ open_alerts = await _count_open_alerts(db, tenant_id, end)
+ open_cases = await _count_open_cases(db, tenant_id, end)
+
+ inputs = DigestInputs(
+ tenant_id=tenant_id,
+ period_start=start,
+ period_end=end,
+ current_alerts=current_alerts,
+ prior_alerts=prior_alerts,
+ cases=cases,
+ gate_log=gate_log,
+ open_alerts_at_period_end=open_alerts,
+ open_cases_at_period_end=open_cases,
+ )
+ return build_digest_from_rows(inputs)
+
+
+__all__ = [
+ "AlertRow",
+ "AlertSummary",
+ "AutomationSummary",
+ "CaseRow",
+ "CaseSummary",
+ "DigestInputs",
+ "DigestPeriod",
+ "DigestRecommendation",
+ "ExecutiveDigest",
+ "GateLogRow",
+ "HighRiskAlertHighlight",
+ "MttSummary",
+ "SeveritySplit",
+ "TacticHighlight",
+ "TopSourceHighlight",
+ "build_digest_from_rows",
+ "build_weekly_digest",
+]
+
+
+# Internal helpers exported for tests.
+_internal_helpers: dict[str, Any] = {
+ "_format_period_label": _format_period_label,
+ "_severity_split": _severity_split,
+ "_mean_hours": _mean_hours,
+ "_compute_mtt": _compute_mtt,
+ "_top_tactics": _top_tactics,
+ "_top_sources": _top_sources,
+ "_high_risk_alerts": _high_risk_alerts,
+ "_automation_summary": _automation_summary,
+ "_case_summary": _case_summary,
+ "_alert_summary": _alert_summary,
+ "_build_headline": _build_headline,
+ "_build_recommendations": _build_recommendations,
+}
diff --git a/services/api/tests/test_executive_digest.py b/services/api/tests/test_executive_digest.py
new file mode 100644
index 000000000..dea70d070
--- /dev/null
+++ b/services/api/tests/test_executive_digest.py
@@ -0,0 +1,379 @@
+"""Tests for WS-G2 — executive weekly digest builder + HTML renderer.
+
+The digest service is split into a *pure* builder (``build_digest_from_rows``)
+and a thin async DB orchestrator. We exercise the pure builder against
+deterministic input rows and snapshot the HTML render to lock the contract
+that downstream analyst tooling depends on.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import pytest
+from app.services.digest_html import render_digest_html
+from app.services.executive_digest import (
+ AlertRow,
+ AutomationSummary,
+ CaseRow,
+ DigestInputs,
+ GateLogRow,
+ MttSummary,
+ SeveritySplit,
+ _internal_helpers,
+ build_digest_from_rows,
+)
+
+PERIOD_START = datetime(2026, 5, 2, 0, 0, tzinfo=UTC)
+PERIOD_END = datetime(2026, 5, 9, 0, 0, tzinfo=UTC)
+TENANT_ID = uuid.uuid4()
+
+
+def _alert(
+ *,
+ severity: str = "low",
+ status: str = "open",
+ created_at: datetime | None = None,
+ resolved_at: datetime | None = None,
+ first_seen_at: datetime | None = None,
+ disposition: str | None = None,
+ mitre_tactics: list[str] | None = None,
+ connector_type: str | None = "edr-crowdstrike",
+ ai_score: float | None = None,
+ title: str = "Suspicious Activity",
+ alert_id: str | None = None,
+ event_time: datetime | None = None,
+) -> AlertRow:
+ """Builder that fills sensible defaults for a row."""
+ created = created_at or PERIOD_START + timedelta(hours=1)
+ return AlertRow(
+ severity=severity,
+ status=status,
+ created_at=created,
+ resolved_at=resolved_at,
+ first_seen_at=first_seen_at,
+ disposition=disposition,
+ mitre_tactics=list(mitre_tactics or []),
+ connector_type=connector_type,
+ ai_score=ai_score,
+ title=title,
+ alert_id=alert_id or str(uuid.uuid4()),
+ event_time=event_time or created,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+
+def test_format_period_label_same_month() -> None:
+ fmt = _internal_helpers["_format_period_label"]
+ label = fmt(PERIOD_START, PERIOD_END)
+ assert "May" in label
+ assert "2026" in label
+
+
+def test_severity_split_counts() -> None:
+ split = _internal_helpers["_severity_split"](
+ [
+ _alert(severity="critical"),
+ _alert(severity="critical"),
+ _alert(severity="high"),
+ _alert(severity="medium"),
+ _alert(severity="low"),
+ _alert(severity="info"),
+ ]
+ )
+ assert isinstance(split, SeveritySplit)
+ assert split.critical == 2
+ assert split.high == 1
+ assert split.medium == 1
+ assert split.low == 1
+ assert split.info == 1
+
+
+def test_mean_hours_zero_or_empty_returns_none() -> None:
+ mean = _internal_helpers["_mean_hours"]
+ assert mean([]) is None
+ assert mean([timedelta(hours=2), timedelta(hours=4)]) == 3.0
+
+
+def test_compute_mtt_only_counts_valid_pairs() -> None:
+ rows = [
+ _alert(
+ created_at=PERIOD_START,
+ first_seen_at=PERIOD_START + timedelta(minutes=30),
+ resolved_at=PERIOD_START + timedelta(hours=4),
+ disposition="true_positive",
+ ),
+ _alert(
+ created_at=PERIOD_START + timedelta(hours=1),
+ first_seen_at=None,
+ resolved_at=PERIOD_START + timedelta(hours=3),
+ disposition="false_positive",
+ ),
+ ]
+ mtt = _internal_helpers["_compute_mtt"](rows)
+ assert isinstance(mtt, MttSummary)
+ assert mtt.mttd_hours == 0.5 # only the first alert had first_seen_at
+ assert mtt.mttr_hours is not None
+ # MTTC only counts true positives
+ assert mtt.mttc_hours == 4.0
+
+
+def test_top_tactics_sorted_with_delta() -> None:
+ current = [
+ _alert(mitre_tactics=["initial_access", "execution"]),
+ _alert(mitre_tactics=["initial_access"]),
+ _alert(mitre_tactics=["lateral_movement"]),
+ ]
+ prior = [_alert(mitre_tactics=["initial_access"])]
+ tactics = _internal_helpers["_top_tactics"](current, prior, limit=3)
+ assert [t.tactic for t in tactics][0] == "initial_access"
+ initial = next(t for t in tactics if t.tactic == "initial_access")
+ assert initial.count == 2
+ assert initial.delta_from_prior == 1
+
+
+def test_top_sources_skips_blank_connectors() -> None:
+ current = [
+ _alert(connector_type="edr-crowdstrike"),
+ _alert(connector_type="edr-crowdstrike"),
+ _alert(connector_type="aws-cloudtrail"),
+ _alert(connector_type=None),
+ ]
+ sources = _internal_helpers["_top_sources"](current, limit=5)
+ assert sources[0].connector_type == "edr-crowdstrike"
+ assert sources[0].count == 2
+ assert {s.connector_type for s in sources} == {"edr-crowdstrike", "aws-cloudtrail"}
+
+
+def test_high_risk_alerts_sorted_by_severity_then_score() -> None:
+ rows = [
+ _alert(severity="low", ai_score=0.99, title="Noisy Low"),
+ _alert(severity="critical", ai_score=0.10, title="Sneaky Critical"),
+ _alert(severity="high", ai_score=0.95, title="Real High"),
+ _alert(severity="critical", ai_score=0.95, title="Loud Critical"),
+ ]
+ top = _internal_helpers["_high_risk_alerts"](rows, limit=3)
+ assert [a.title for a in top] == ["Loud Critical", "Sneaky Critical", "Real High"]
+
+
+def test_automation_summary_categorises_decisions() -> None:
+ log = [
+ GateLogRow(decision="auto"),
+ GateLogRow(decision="auto"),
+ GateLogRow(decision="review"),
+ GateLogRow(decision="escalate"),
+ GateLogRow(decision="something_unknown"),
+ ]
+ summary = _internal_helpers["_automation_summary"](log)
+ assert isinstance(summary, AutomationSummary)
+ assert summary.total_decisions == 5
+ assert summary.auto_executed == 2
+ assert summary.review_pending == 1
+ assert summary.escalated == 1
+
+
+def test_case_summary_filters_by_window() -> None:
+ rows = [
+ CaseRow(
+ status="open",
+ created_at=PERIOD_START + timedelta(hours=1),
+ closed_at=None,
+ sla_breached=False,
+ ),
+ CaseRow(
+ status="closed",
+ created_at=PERIOD_START + timedelta(hours=2),
+ closed_at=PERIOD_START + timedelta(hours=4),
+ sla_breached=True,
+ ),
+ CaseRow(
+ status="open",
+ created_at=PERIOD_START - timedelta(days=2),
+ closed_at=None,
+ sla_breached=False,
+ ),
+ ]
+ summary = _internal_helpers["_case_summary"](rows, 12, PERIOD_START, PERIOD_END)
+ assert summary.opened == 2
+ assert summary.closed == 1
+ assert summary.sla_breached == 1
+ assert summary.open_at_period_end == 12
+
+
+# ---------------------------------------------------------------------------
+# Top-level pure builder
+# ---------------------------------------------------------------------------
+
+
+def baseline_inputs() -> DigestInputs:
+ """A realistic, deterministic input bundle that exercises every section."""
+ return DigestInputs(
+ tenant_id=TENANT_ID,
+ period_start=PERIOD_START,
+ period_end=PERIOD_END,
+ current_alerts=[
+ _alert(
+ severity="critical",
+ title="Ransomware exec on FIN-LAPTOP-04",
+ created_at=PERIOD_START + timedelta(hours=2),
+ first_seen_at=PERIOD_START + timedelta(hours=2, minutes=15),
+ resolved_at=PERIOD_START + timedelta(hours=8),
+ disposition="true_positive",
+ mitre_tactics=["impact", "execution"],
+ ai_score=0.96,
+ ),
+ _alert(
+ severity="critical",
+ title="LSASS memory access — SVR-DC-01",
+ created_at=PERIOD_START + timedelta(hours=4),
+ ai_score=0.91,
+ mitre_tactics=["credential_access"],
+ ),
+ _alert(
+ severity="high",
+ title="OAuth grant from new IP",
+ created_at=PERIOD_START + timedelta(days=1),
+ resolved_at=PERIOD_START + timedelta(days=1, hours=6),
+ disposition="false_positive",
+ mitre_tactics=["initial_access"],
+ connector_type="azure-ad",
+ ),
+ _alert(
+ severity="medium",
+ title="Suspicious DNS tunnelling",
+ created_at=PERIOD_START + timedelta(days=2),
+ mitre_tactics=["command_and_control"],
+ connector_type="aws-vpc-flow",
+ ),
+ _alert(severity="low", title="Failed login spike"),
+ ],
+ prior_alerts=[
+ _alert(mitre_tactics=["initial_access"]),
+ _alert(mitre_tactics=["execution"]),
+ ],
+ cases=[
+ CaseRow(
+ status="open",
+ created_at=PERIOD_START + timedelta(hours=2),
+ closed_at=None,
+ sla_breached=False,
+ ),
+ CaseRow(
+ status="closed",
+ created_at=PERIOD_START + timedelta(hours=3),
+ closed_at=PERIOD_START + timedelta(hours=10),
+ sla_breached=True,
+ ),
+ ],
+ gate_log=[
+ GateLogRow(decision="auto"),
+ GateLogRow(decision="auto"),
+ GateLogRow(decision="auto"),
+ GateLogRow(decision="review"),
+ GateLogRow(decision="escalate"),
+ ],
+ open_alerts_at_period_end=42,
+ open_cases_at_period_end=7,
+ )
+
+
+def test_build_digest_basic_shape(baseline_inputs: DigestInputs) -> None:
+ digest = build_digest_from_rows(baseline_inputs)
+
+ assert digest.tenant_id == TENANT_ID
+ assert digest.period.start == PERIOD_START
+ assert digest.period.end == PERIOD_END
+ assert "May" in digest.period.label
+
+ assert digest.alerts.total == 5
+ assert digest.alerts.severity.critical == 2
+ assert digest.alerts.severity.high == 1
+ assert digest.alerts.severity.medium == 1
+ assert digest.alerts.severity.low == 1
+ assert digest.alerts.open_at_period_end == 42
+
+ assert digest.cases.opened == 2
+ assert digest.cases.closed == 1
+ assert digest.cases.sla_breached == 1
+ assert digest.cases.open_at_period_end == 7
+
+ assert digest.automation.total_decisions == 5
+ assert digest.automation.auto_executed == 3
+
+ assert len(digest.high_risk_alerts) >= 3
+ # High-risk alerts should be ordered with criticals first.
+ severities = [a.severity for a in digest.high_risk_alerts]
+ assert severities[0] == "critical"
+
+
+def test_build_digest_headline_and_recommendations(baseline_inputs: DigestInputs) -> None:
+ digest = build_digest_from_rows(baseline_inputs)
+
+ assert "alerts ingested" in digest.headline
+ # We have an SLA breach in the inputs, so a warning rec must appear.
+ titles = [r.title for r in digest.recommendations]
+ assert any("SLA" in t for t in titles)
+
+
+def test_build_digest_no_signals_falls_back_to_neutral_recommendation() -> None:
+ inputs = DigestInputs(
+ tenant_id=TENANT_ID,
+ period_start=PERIOD_START,
+ period_end=PERIOD_END,
+ )
+ digest = build_digest_from_rows(inputs)
+ assert digest.alerts.total == 0
+ assert digest.cases.opened == 0
+ assert digest.recommendations
+ assert digest.recommendations[0].severity == "info"
+ assert "No significant deviations" in digest.recommendations[0].title
+
+
+def test_build_digest_is_deterministic(baseline_inputs: DigestInputs) -> None:
+ """Same inputs must yield byte-identical outputs."""
+ a = build_digest_from_rows(baseline_inputs).model_dump_json()
+ b = build_digest_from_rows(baseline_inputs).model_dump_json()
+ assert a == b
+
+
+# ---------------------------------------------------------------------------
+# HTML renderer
+# ---------------------------------------------------------------------------
+
+
+def test_render_digest_html_contains_sections(baseline_inputs: DigestInputs) -> None:
+ digest = build_digest_from_rows(baseline_inputs)
+ html = render_digest_html(digest)
+
+ assert "<!DOCTYPE html>" in html
+ assert "AiSOC weekly executive digest" in html
+ assert digest.period.label in html
+ assert "Headline metrics" in html
+ assert "Severity distribution" in html
+ assert "Top MITRE tactics" in html
+ assert "High-risk alerts" in html
+ assert "Automation" in html
+ assert "Recommendations" in html
+
+
+def test_render_digest_html_escapes_user_data() -> None:
+ inputs = DigestInputs(
+ tenant_id=TENANT_ID,
+ period_start=PERIOD_START,
+ period_end=PERIOD_END,
+ current_alerts=[
+ _alert(title="<script>alert('xss')</script>", severity="critical", ai_score=0.99),
+ ],
+ )
+ digest = build_digest_from_rows(inputs)
+ html = render_digest_html(digest)
+
+ # Raw script tag must not appear; escaped form must.
+ assert "<script>alert" not in html
+ assert "&lt;script&gt;alert" in html