feat(security): wire Dependabot alert posture into portfolio risk model

Schema 0.4.0 -> 0.5.0: new SecurityFields (Dependabot / code-scanning /
secret-scanning counts) on every PortfolioTruthProject. New risk factor
active-high-severity-alerts — open high alerts add one factor toward the
3+ elevation threshold; an open critical alert force-elevates on its own,
so a lone unpatched critical CVE cannot hide in a clean repo.

Opt-in via --portfolio-truth-include-security, overlaying the latest
output/ghas-alerts-<user>-*.json (mirrors the release_count overlay; the
truth pipeline itself stays network-free / offline-testable). Weekly
digest gains a ## Security Posture section distinguishing scanned-clean
from unscanned repos. Fully inert unless fed: defaults keep the factor
dormant and all existing risk tiers unchanged.

27 new tests across risk math, GHAS mapping, opt-in, force-elevate,
deferred short-circuit, digest states, and the CLI loader. 2140 pass.

Author: saagpatel

src/cli.py

@@ -620,6 +620,15 @@ def build_parser() -> argparse.ArgumentParser:
             "output/audit-report-<username>-*.json warehouse file (requires a prior audit run)"
         ),
     )
+    parser.add_argument(
+        "--portfolio-truth-include-security",
+        action="store_true",
+        help=(
+            "Overlay the security.* GHAS alert counts on each project from the latest "
+            "output/ghas-alerts-<username>-*.json file, feeding the active-high-severity-alerts "
+            "risk factor (requires a prior `audit report --ghas-alerts` run)"
+        ),
+    )
     parser.add_argument(
         "--portfolio-context-recovery",
         action="store_true",
@@ -5187,6 +5196,52 @@ def _load_release_count_by_name(*, output_dir: Path, username: str) -> dict[str,
     return result
 
 
+def _load_security_alerts_by_name(*, output_dir: Path, username: str) -> dict[str, dict] | None:
+    """Load per-repo GHAS alert counts from the latest output/ghas-alerts-<username>-*.json.
+
+    The file is already keyed by display name in the shape SecurityFields expects
+    ({name: {"dependabot": {...}, "code_scanning": {...}, "secret_scanning": {...}}}),
+    so the overlay needs no transformation. Returns None (with a warning) if no GHAS
+    report is found — the security overlay is then skipped, leaving counts at zero.
+    """
+    import logging
+
+    _log = logging.getLogger(__name__)
+
+    ghas_files = sorted(
+        output_dir.glob(f"ghas-alerts-{username}-*.json"),
+        key=lambda p: p.stat().st_mtime,
+    )
+    if not ghas_files:
+        _log.warning(
+            "--portfolio-truth-include-security requires a prior `audit report --ghas-alerts` "
+            "run; no ghas-alerts-%s-*.json found in %s — skipping security overlay",
+            username,
+            output_dir,
+        )
+        return None
+
+    ghas_path = ghas_files[-1]
+    try:
+        with ghas_path.open() as fh:
+            data = json.load(fh)
+    except Exception as exc:  # noqa: BLE001
+        _log.warning(
+            "--portfolio-truth-include-security: could not read %s: %s — skipping",
+            ghas_path,
+            exc,
+        )
+        return None
+
+    if not isinstance(data, dict):
+        _log.warning(
+            "--portfolio-truth-include-security: %s is not a name-keyed object — skipping",
+            ghas_path,
+        )
+        return None
+    return {name: entry for name, entry in data.items() if isinstance(entry, dict)}
+
+
 def _run_portfolio_truth_mode(args) -> None:
     from src.portfolio_truth_publish import publish_portfolio_truth
 
@@ -5211,6 +5266,13 @@ def _run_portfolio_truth_mode(args) -> None:
             username=args.username,
         )
 
+    security_alerts_by_name: dict[str, dict] | None = None
+    if getattr(args, "portfolio_truth_include_security", False):
+        security_alerts_by_name = _load_security_alerts_by_name(
+            output_dir=output_dir,
+            username=args.username,
+        )
+
     result = publish_portfolio_truth(
         workspace_root=workspace_root,
         output_dir=output_dir,
@@ -5220,6 +5282,7 @@ def _run_portfolio_truth_mode(args) -> None:
         legacy_registry_path=legacy_registry_path,
         include_notion=True,
         release_count_by_name=release_count_by_name,
+        security_alerts_by_name=security_alerts_by_name,
     )
     print_info(f"Portfolio truth snapshot: {result.latest_path}")
     print_info(f"Portfolio truth history snapshot: {result.snapshot_path}")
@@ -5381,7 +5444,9 @@ def _run_context_triage_mode(args) -> None:
         project_key = identity.get("project_key") or ""
         name = identity.get("display_name") or project.get("name", "")
         repo_keys.extend(key for key in (project_key, name) if key)
-    catalog_scores = validate_catalog(catalog_path, sorted(set(repo_keys))) if catalog_path.exists() else {}
+    catalog_scores = (
+        validate_catalog(catalog_path, sorted(set(repo_keys))) if catalog_path.exists() else {}
+    )
 
     enriched: list[dict] = []
     for project in projects:

src/portfolio_risk.py

@@ -27,6 +27,7 @@
     "missing-doctor-standard": "doctor standard not declared",
     "no-run-instructions": "run instructions missing",
     "undocumented-risks": "known risks not documented",
+    "active-high-severity-alerts": "open high/critical security alerts",
 }
 
 _DEFERRED_ARCHIVED = {
@@ -36,6 +37,7 @@
     "doctor_gap": False,
     "context_risk": False,
     "path_risk": False,
+    "security_risk": False,
 }
 
 _DEFERRED_STALE = {
@@ -45,6 +47,7 @@
     "doctor_gap": False,
     "context_risk": False,
     "path_risk": False,
+    "security_risk": False,
 }
 
 
@@ -61,6 +64,8 @@ def build_risk_entry(
     doctor_standard: str,
     known_risks_present: bool,
     run_instructions_present: bool,
+    security_high_alerts: int = 0,
+    security_critical_alerts: int = 0,
 ) -> dict[str, Any]:
     # Short-circuit deferred: archived or archive-path
     if registry_status == "archived" or operating_path == "archive":
@@ -91,9 +96,20 @@ def build_risk_entry(
     if criticality in {"high", "critical"} and not known_risks_present:
         factors.append("undocumented-risks")
 
+    # Active repo carrying open high- or critical-severity Dependabot alerts.
+    # High alerts contribute one normal factor toward the 3+ elevation threshold;
+    # an open critical alert force-elevates on its own (see is_elevated below) — a
+    # lone unpatched critical CVE cannot hide in an otherwise-clean repo.
+    active = activity_status in ACTIVE_STATUSES
+    if active and (security_high_alerts > 0 or security_critical_alerts > 0):
+        factors.append("active-high-severity-alerts")
+
     # Derive tier
-    is_elevated = len(factors) >= 3 or (
-        "weak-context-active" in factors and "investigate-override" in factors
+    security_forces_elevated = active and security_critical_alerts > 0
+    is_elevated = (
+        len(factors) >= 3
+        or ("weak-context-active" in factors and "investigate-override" in factors)
+        or security_forces_elevated
     )
     if is_elevated:
         risk_tier = "elevated"
@@ -106,6 +122,7 @@ def build_risk_entry(
     doctor_gap = "missing-doctor-standard" in factors
     context_risk = "weak-context-active" in factors
     path_risk = "investigate-override" in factors or "missing-operating-path" in factors
+    security_risk = "active-high-severity-alerts" in factors
 
     # Build summary
     if not factors:
@@ -121,6 +138,7 @@ def build_risk_entry(
         "doctor_gap": doctor_gap,
         "context_risk": context_risk,
         "path_risk": path_risk,
+        "security_risk": security_risk,
     }
 
 

src/portfolio_truth_publish.py

@@ -36,6 +36,7 @@ def publish_portfolio_truth(
     legacy_registry_path: Path | None = None,
     include_notion: bool = True,
     release_count_by_name: dict[str, int] | None = None,
+    security_alerts_by_name: dict[str, dict] | None = None,
 ) -> PortfolioTruthPublishResult:
     validate_publish_targets(
         workspace_root=workspace_root,
@@ -49,6 +50,7 @@ def publish_portfolio_truth(
         legacy_registry_path=legacy_registry_path,
         include_notion=include_notion,
         release_count_by_name=release_count_by_name,
+        security_alerts_by_name=security_alerts_by_name,
     )
     validate_truth_snapshot(build_result.snapshot)
 

src/portfolio_truth_reconcile.py

@@ -28,6 +28,7 @@
     PortfolioTruthProject,
     PortfolioTruthSnapshot,
     RiskFields,
+    SecurityFields,
 )
 from src.registry_parser import _normalize
 
@@ -180,6 +181,7 @@ def build_portfolio_truth_snapshot(
     include_notion: bool = True,
     now: datetime | None = None,
     release_count_by_name: dict[str, int] | None = None,
+    security_alerts_by_name: dict[str, dict] | None = None,
 ) -> PortfolioTruthBuildResult:
     now = now or datetime.now(timezone.utc)
     catalog_data = load_portfolio_catalog(catalog_path)
@@ -199,6 +201,7 @@ def build_portfolio_truth_snapshot(
             notion_context=notion_context,
             now=now,
             release_count_by_name=release_count_by_name,
+            security_alerts_by_name=security_alerts_by_name,
         )
         for raw_project in workspace_projects
     ]
@@ -259,21 +262,44 @@ def _unresolved_duplicate_display_names(projects: list[PortfolioTruthProject]) -
     return sorted(
         name
         for name, members in grouped.items()
-        if len(members) > 1
-        and any(not _has_path_catalog_contract(project) for project in members)
+        if len(members) > 1 and any(not _has_path_catalog_contract(project) for project in members)
     )
 
 
 def _has_path_catalog_contract(project: PortfolioTruthProject) -> bool:
     for source in project.provenance.values():
-        if (
-            source.get("source") == "catalog_repo"
-            and source.get("detail") == project.identity.path
-        ):
+        if source.get("source") == "catalog_repo" and source.get("detail") == project.identity.path:
             return True
     return False
 
 
+def _build_security_fields(ghas_entry: dict[str, Any] | None) -> SecurityFields:
+    """Map a per-repo GHAS alert entry (from output/ghas-alerts-<username>-*.json)
+    into SecurityFields. A missing/None entry yields all-zero counts with
+    alerts_available=False (the repo was not scanned) — distinct from a clean scan,
+    and keeps the security overlay strictly opt-in (no entry → no security signal)."""
+    if not ghas_entry:
+        return SecurityFields()
+    dependabot = ghas_entry.get("dependabot") or {}
+    code_scanning = ghas_entry.get("code_scanning") or {}
+    secret_scanning = ghas_entry.get("secret_scanning") or {}
+
+    def _count(source: dict[str, Any], key: str) -> int:
+        value = source.get(key)
+        return value if isinstance(value, int) and value >= 0 else 0
+
+    return SecurityFields(
+        alerts_available=bool(dependabot.get("available", False)),
+        dependabot_critical=_count(dependabot, "critical"),
+        dependabot_high=_count(dependabot, "high"),
+        dependabot_medium=_count(dependabot, "medium"),
+        dependabot_low=_count(dependabot, "low"),
+        code_scanning_critical=_count(code_scanning, "critical"),
+        code_scanning_high=_count(code_scanning, "high"),
+        secret_scanning_open=_count(secret_scanning, "open"),
+    )
+
+
 def _build_truth_project(
     raw_project: dict[str, Any],
     *,
@@ -282,6 +308,7 @@ def _build_truth_project(
     notion_context: dict[str, dict[str, str]],
     now: datetime,
     release_count_by_name: dict[str, int] | None = None,
+    security_alerts_by_name: dict[str, dict] | None = None,
 ) -> PortfolioTruthProject:
     relative_path = raw_project["path"]
     group_entry = group_entry_for_path(relative_path, catalog_data)
@@ -393,6 +420,12 @@ def _build_truth_project(
         "detail": "derived",
     }
 
+    security_entry = (security_alerts_by_name or {}).get(raw_project["name"])
+    security = _build_security_fields(security_entry)
+
+    # Only Dependabot high/critical counts drive the risk tier today. Code-scanning
+    # and secret-scanning counts are captured in SecurityFields for visibility but do
+    # not yet feed the active-high-severity-alerts factor (Dependabot-only scope).
     risk_entry = build_risk_entry(
         display_name=raw_project["name"],
         operating_path=path_entry.get("operating_path", ""),
@@ -405,6 +438,8 @@ def _build_truth_project(
         doctor_standard=declared_values["doctor_standard"],
         known_risks_present=bool(raw_project["known_risks_present"]),
         run_instructions_present=bool(raw_project["run_instructions_present"]),
+        security_high_alerts=security.dependabot_high,
+        security_critical_alerts=security.dependabot_critical,
     )
 
     declared = DeclaredFields(
@@ -516,6 +551,7 @@ def _build_truth_project(
         doctor_gap=risk_entry["doctor_gap"],
         context_risk=risk_entry["context_risk"],
         path_risk=risk_entry["path_risk"],
+        security_risk=risk_entry["security_risk"],
     )
     provenance["risk.risk_tier"] = {"source": "derived", "detail": risk_entry["risk_tier"]}
     provenance["risk.doctor_gap"] = {
@@ -527,6 +563,7 @@ def _build_truth_project(
         declared=declared,
         derived=derived,
         risk=risk,
+        security=security,
         advisory=advisory,
         provenance=provenance,
         warnings=warnings,

src/portfolio_truth_types.py

@@ -5,7 +5,7 @@
 from datetime import datetime
 from typing import Any
 
-SCHEMA_VERSION = "0.4.0"
+SCHEMA_VERSION = "0.5.0"
 
 VALID_CONTEXT_QUALITY = {"full", "standard", "minimum-viable", "boilerplate", "none"}
 VALID_ACTIVITY_STATUS = {"active", "recent", "stale", "archived"}
@@ -124,6 +124,32 @@ class RiskFields:
     doctor_gap: bool = False
     context_risk: bool = False
     path_risk: bool = False
+    security_risk: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(self)
+
+
+@dataclass(frozen=True)
+class SecurityFields:
+    """Live GitHub Advanced Security alert counts, overlaid opt-in from the latest
+    output/ghas-alerts-<username>-*.json. When alerts_available is False the repo was
+    not scanned (no token / GHAS disabled / not fetched) — distinct from a clean scan
+    with zero open alerts, so consumers don't mislabel an unscanned repo as secure."""
+
+    alerts_available: bool = False
+    dependabot_critical: int = 0
+    dependabot_high: int = 0
+    dependabot_medium: int = 0
+    dependabot_low: int = 0
+    code_scanning_critical: int = 0
+    code_scanning_high: int = 0
+    secret_scanning_open: int = 0
+
+    @property
+    def open_high_critical(self) -> int:
+        """Dependabot high + critical — the security-risk-factor trigger surface."""
+        return self.dependabot_high + self.dependabot_critical
 
     def to_dict(self) -> dict[str, Any]:
         return dataclasses.asdict(self)
@@ -135,6 +161,7 @@ class PortfolioTruthProject:
     declared: DeclaredFields
     derived: DerivedFields
     risk: RiskFields = field(default_factory=RiskFields)
+    security: SecurityFields = field(default_factory=SecurityFields)
     advisory: AdvisoryFields = field(default_factory=AdvisoryFields)
     provenance: dict[str, dict[str, str]] = field(default_factory=dict)
     warnings: list[str] = field(default_factory=list)
@@ -145,6 +172,7 @@ def to_dict(self) -> dict[str, Any]:
             "declared": self.declared.to_dict(),
             "derived": self.derived.to_dict(),
             "risk": self.risk.to_dict(),
+            "security": self.security.to_dict(),
             "advisory": self.advisory.to_dict(),
             "provenance": self.provenance,
             "warnings": list(self.warnings),