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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
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.tsxnew file mode 100644index 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.tsxindex 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.tsxnew file mode 100644index 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.tsindex 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.pyindex 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 datetimefrom typing import Anyfrom fastapi import APIRouter, Depends, HTTPException, Query, status+from fastapi.responses import HTMLResponsefrom pydantic import BaseModel, Fieldfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession@@ -15,6 +16,8 @@ from app.api.v1.endpoints.auth import get_current_userfrom app.db.database import get_dbfrom app.models.report import ReportArtefact, ReportTemplatefrom app.models.tenant import User+from app.services.digest_html import render_digest_html+from app.services.executive_digest import ExecutiveDigest, build_weekly_digestrouter = 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 digestdiff --git a/services/api/app/services/digest_html.py b/services/api/app/services/digest_html.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 "<script>alert" in html