actshield 0.9.0__py3-none-any.whl

actshield/threatmodel/exporters.py

@@ -0,0 +1,49 @@
+"""Threat model exporters — JSON, YAML, Markdown."""
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+from actshield.threatmodel.models import AnalysisResult
+from actshield.threatmodel.report import ThreatReportRenderer
+
+ExportFormat = Literal["json", "yaml", "markdown"]
+
+
+class ThreatModelExporter:
+    """Exports threat analysis results to external formats."""
+
+    def export(self, result: AnalysisResult, format: ExportFormat = "json") -> str:
+        if format == "json":
+            return self._to_json(result)
+        elif format == "yaml":
+            return self._to_yaml(result)
+        elif format == "markdown":
+            renderer = ThreatReportRenderer()
+            return renderer.to_markdown(result)
+        else:
+            raise ValueError(f"Unsupported export format: {format}. Use json, yaml, or markdown.")
+
+    def _to_json(self, result: AnalysisResult) -> str:
+        return json.dumps(result.to_dict(), indent=2, default=str)
+
+    def _to_yaml(self, result: AnalysisResult) -> str:
+        try:
+            import yaml  # type: ignore[import]
+            return yaml.dump(result.to_dict(), default_flow_style=False, allow_unicode=True)
+        except ImportError:
+            # Fallback: minimal YAML-like output without PyYAML
+            data = result.to_dict()
+            lines = ["# ActShield Threat Model Export (YAML)"]
+            lines.append(f"overall_risk_score: {data.get('overall_risk_score', 0)}")
+            lines.append("model:")
+            model = data.get("model", {})
+            for k, v in model.items():
+                lines.append(f"  {k}: {json.dumps(v)}")
+            lines.append("threats_by_severity:")
+            for sev, threats in data.get("threats_by_severity", {}).items():
+                lines.append(f"  {sev}: {len(threats)} threat(s)")
+            lines.append(
+                "# Install PyYAML for full YAML export: pip install pyyaml"
+            )
+            return "\n".join(lines)

actshield/threatmodel/mitigations.py

@@ -0,0 +1,209 @@
+"""Control-to-threat mapping — how ActShield controls mitigate each threat."""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from actshield.threatmodel.models import ControlEffectiveness
+
+
+class Mitigation(BaseModel):
+    """A single ActShield control and its relationship to a threat."""
+    control_id: str
+    control_name: str
+    description: str
+    # How the control works mechanically
+    mechanism: str
+    # Enforcement action
+    enforcement_action: str  # BLOCK | MONITOR | DETECT | ALERT
+    # Where in the ActShield pipeline this runs
+    pipeline_stage: str  # provenance | taint | intent | authority | policy | evidence
+
+
+class ControlMapping(BaseModel):
+    """Maps a threat to the set of ActShield controls that mitigate it."""
+    threat_id: str
+    controls: list[Mitigation] = Field(default_factory=list)
+    combined_effectiveness: ControlEffectiveness = ControlEffectiveness.REDUCES
+    notes: str = ""
+
+
+# ── ActShield control definitions ─────────────────────────────────────────────
+
+ACTSHIELD_CONTROLS: dict[str, Mitigation] = {
+    "provenance_tracking": Mitigation(
+        control_id="ctl_provenance",
+        control_name="Context Provenance Tracking",
+        description=(
+            "Every piece of context entering the agent system is tagged with its "
+            "origin source, trust level, and a provenance chain."
+        ),
+        mechanism=(
+            "ProvenanceHop records are attached to each context element. "
+            "External sources receive EXTERNAL trust level."
+        ),
+        enforcement_action="DETECT",
+        pipeline_stage="provenance",
+    ),
+    "taint_tracking": Mitigation(
+        control_id="ctl_taint",
+        control_name="Taint Propagation",
+        description=(
+            "Context derived from untrusted or external sources is marked TAINTED "
+            "and that taint propagates through the reasoning chain."
+        ),
+        mechanism=(
+            "TaintState.TAINTED is set on context from external sources. "
+            "Tainted context cannot authorize CRITICAL tool execution."
+        ),
+        enforcement_action="BLOCK",
+        pipeline_stage="taint",
+    ),
+    "mcp_gateway": Mitigation(
+        control_id="ctl_mcp",
+        control_name="MCP Gateway Interception",
+        description="All MCP server communications are intercepted and inspected.",
+        mechanism=(
+            "MCPGateway wraps all MCP calls. Responses are analyzed, "
+            "taint-marked, and provenance-recorded before entering agent context."
+        ),
+        enforcement_action="BLOCK",
+        pipeline_stage="provenance",
+    ),
+    "http_gateway": Mitigation(
+        control_id="ctl_http",
+        control_name="HTTP Gateway Interception",
+        description="All external HTTP calls are intercepted and responses are taint-marked.",
+        mechanism=(
+            "HTTPGateway intercepts outbound requests and inbound responses. "
+            "External responses marked EXTERNAL and TAINTED."
+        ),
+        enforcement_action="DETECT",
+        pipeline_stage="provenance",
+    ),
+    "intent_analysis": Mitigation(
+        control_id="ctl_intent",
+        control_name="Intent Analysis (AI Secura / Deterministic)",
+        description=(
+            "AI-powered and deterministic intent analysis classifies whether "
+            "a tool request is aligned with the declared task."
+        ),
+        mechanism=(
+            "DeterministicIntentAnalyzer checks keywords, patterns, and taint. "
+            "AI Secura provides probabilistic scoring. Results inform policy."
+        ),
+        enforcement_action="ALERT",
+        pipeline_stage="intent",
+    ),
+    "authority_containment": Mitigation(
+        control_id="ctl_authority",
+        control_name="Authority Containment",
+        description=(
+            "Agents cannot claim authority beyond what was explicitly delegated. "
+            "The containment invariant: effective ≤ delegated ≤ declared."
+        ),
+        mechanism=(
+            "Effective authority is computed from the delegation chain. "
+            "Tool requests requiring authority exceeding effective are blocked."
+        ),
+        enforcement_action="BLOCK",
+        pipeline_stage="authority",
+    ),
+    "effective_authority_check": Mitigation(
+        control_id="ctl_eff_auth",
+        control_name="Effective Authority Verification",
+        description="Verifies the computed effective authority before any tool execution.",
+        mechanism=(
+            "DECLARED → DELEGATED → EFFECTIVE chain is computed and compared "
+            "against required tool authority."
+        ),
+        enforcement_action="BLOCK",
+        pipeline_stage="authority",
+    ),
+    "delegation_tracking": Mitigation(
+        control_id="ctl_delegation",
+        control_name="Delegation Chain Tracking",
+        description="Full delegation graph is maintained and verified for every agent action.",
+        mechanism="Delegation records are immutable and cryptographically linked.",
+        enforcement_action="DETECT",
+        pipeline_stage="authority",
+    ),
+    "policy_evaluation": Mitigation(
+        control_id="ctl_policy",
+        control_name="Deterministic Policy Evaluation",
+        description=(
+            "The PolicyEvaluator applies rules deterministically — AI advice "
+            "is input to policy, not the policy itself."
+        ),
+        mechanism=(
+            "PolicyEvaluator evaluates RuleCondition sets. "
+            "Output: ALLOW | MONITOR | HITL | QUARANTINE | BLOCK | REVOKE."
+        ),
+        enforcement_action="BLOCK",
+        pipeline_stage="policy",
+    ),
+    "tool_interception": Mitigation(
+        control_id="ctl_tool",
+        control_name="Tool Interception (@protect decorator)",
+        description="Protected tools cannot execute without passing the full ActShield pipeline.",
+        mechanism=(
+            "@guard.protect() wraps tool functions. All executions pass through "
+            "provenance → taint → intent → authority → policy before execution."
+        ),
+        enforcement_action="BLOCK",
+        pipeline_stage="policy",
+    ),
+    "audit_logging": Mitigation(
+        control_id="ctl_audit",
+        control_name="Structured Audit Logging",
+        description="Every security decision produces a structured, immutable audit record.",
+        mechanism=(
+            "SecurityEvent records are written with: who, what, when, why, "
+            "context, authority, tool, resource, decision, outcome."
+        ),
+        enforcement_action="DETECT",
+        pipeline_stage="evidence",
+    ),
+    "source_attribution": Mitigation(
+        control_id="ctl_attribution",
+        control_name="Source Attribution",
+        description="Context elements are attributed to their originating source at retrieval time.",
+        mechanism="ProvenanceHop records source URL, trust level, and retrieval timestamp.",
+        enforcement_action="DETECT",
+        pipeline_stage="provenance",
+    ),
+    "sensitivity_classification": Mitigation(
+        control_id="ctl_sensitivity",
+        control_name="Tool Sensitivity Classification",
+        description="Tools are classified by sensitivity level (LOW → CRITICAL).",
+        mechanism=(
+            "SensitivityLevel is declared on ToolDefinition. "
+            "CRITICAL tools require authority + clean taint + explicit policy."
+        ),
+        enforcement_action="BLOCK",
+        pipeline_stage="policy",
+    ),
+}
+
+
+def get_control(control_id: str) -> Mitigation | None:
+    return ACTSHIELD_CONTROLS.get(control_id)
+
+
+def get_all_controls() -> list[Mitigation]:
+    return list(ACTSHIELD_CONTROLS.values())
+
+
+def build_control_coverage_map(threat_control_ids: list[str]) -> dict[str, bool]:
+    """Return which ActShield control domains are covered."""
+    domains = {
+        "Identity": any(c in threat_control_ids for c in ["provenance_tracking", "delegation_tracking"]),
+        "Authority": any(c in threat_control_ids for c in ["authority_containment", "effective_authority_check", "delegation_tracking"]),
+        "Context": any(c in threat_control_ids for c in ["taint_tracking", "provenance_tracking", "source_attribution"]),
+        "Tool Security": any(c in threat_control_ids for c in ["tool_interception", "sensitivity_classification"]),
+        "MCP": any(c in threat_control_ids for c in ["mcp_gateway"]),
+        "Data Access": any(c in threat_control_ids for c in ["authority_containment", "policy_evaluation"]),
+        "Delegation": any(c in threat_control_ids for c in ["delegation_tracking", "authority_containment"]),
+        "Enforcement": any(c in threat_control_ids for c in ["policy_evaluation"]),
+        "Evidence": any(c in threat_control_ids for c in ["audit_logging"]),
+    }
+    return domains

actshield/threatmodel/models.py

@@ -0,0 +1,80 @@
+"""Threat modeling core models — ThreatModel, AnalysisResult, enumerations."""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ThreatSeverity(str, Enum):
+    """CVSS-inspired severity classification."""
+    CRITICAL = "CRITICAL"
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+    INFORMATIONAL = "INFORMATIONAL"
+
+
+class ThreatCategory(str, Enum):
+    """Top-level threat category aligned to STRIDE + MITRE ATLAS concepts."""
+    # STRIDE
+    SPOOFING = "SPOOFING"                  # Identity / agent impersonation
+    TAMPERING = "TAMPERING"                # Context or data tampering
+    REPUDIATION = "REPUDIATION"            # Lack of audit trail
+    INFORMATION_DISCLOSURE = "INFO_DISCLOSURE"  # Data exfiltration
+    DENIAL_OF_SERVICE = "DENIAL_OF_SERVICE"
+    ELEVATION_OF_PRIVILEGE = "PRIVILEGE_ESCALATION"
+    # MITRE ATLAS / Agentic AI specific
+    PROMPT_INJECTION = "PROMPT_INJECTION"
+    INDIRECT_PROMPT_INJECTION = "INDIRECT_PROMPT_INJECTION"
+    TOOL_POISONING = "TOOL_POISONING"
+    CONTEXT_POISONING = "CONTEXT_POISONING"
+    DELEGATION_ABUSE = "DELEGATION_ABUSE"
+    CREDENTIAL_THEFT = "CREDENTIAL_THEFT"
+    MCP_COMPROMISE = "MCP_COMPROMISE"
+    SUPPLY_CHAIN = "SUPPLY_CHAIN"
+    RAG_POISONING = "RAG_POISONING"
+
+
+class ControlEffectiveness(str, Enum):
+    """How effectively the mapped ActShield control mitigates the threat."""
+    PREVENTS = "PREVENTS"      # Control fully prevents exploitation
+    DETECTS = "DETECTS"        # Control detects but may not prevent
+    REDUCES = "REDUCES"        # Control reduces likelihood / impact
+    MONITORS = "MONITORS"      # Control provides observability only
+    NONE = "NONE"              # No current control coverage
+
+
+class ThreatModel(BaseModel):
+    """Container for the full threat model of a deployed agent system."""
+    model_id: str = Field(default_factory=lambda: f"tm_{uuid.uuid4().hex[:8]}")
+    system_name: str = "ActShield-Monitored System"
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    version: str = "1.0.0"
+
+    # Populated by the registry/analyzer
+    asset_count: int = 0
+    actor_count: int = 0
+    boundary_count: int = 0
+    threat_count: int = 0
+    scenario_count: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="json")
+
+
+class AnalysisResult(BaseModel):
+    """Complete output of a ThreatAnalyzer.analyze() run."""
+    model: ThreatModel
+    threats_by_severity: dict[str, list[dict[str, Any]]] = Field(default_factory=dict)
+    control_coverage: dict[str, bool] = Field(default_factory=dict)
+    residual_risks: list[dict[str, Any]] = Field(default_factory=list)
+    attack_paths: list[dict[str, Any]] = Field(default_factory=list)
+    analysis_timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    overall_risk_score: float = 0.0  # 0-10 scale
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="json")

actshield/threatmodel/report.py

@@ -0,0 +1,341 @@
+"""Threat model Rich CLI renderer — professional security report output."""
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.tree import Tree
+from rich.columns import Columns
+from rich.text import Text
+from rich import box
+
+from actshield.cli.theme import ACTSHIELD_THEME
+from actshield.threatmodel.models import (
+    ThreatModel,
+    AnalysisResult,
+    ThreatSeverity,
+    ControlEffectiveness,
+)
+from actshield.threatmodel.threats import Threat
+
+console = Console(theme=ACTSHIELD_THEME)
+
+# Severity → Rich style
+_SEV_STYLE: dict[str, str] = {
+    ThreatSeverity.CRITICAL.value: "ag.critical",
+    ThreatSeverity.HIGH.value: "ag.attack",
+    ThreatSeverity.MEDIUM.value: "ag.warning",
+    ThreatSeverity.LOW.value: "ag.monitor",
+    ThreatSeverity.INFORMATIONAL.value: "ag.dim",
+}
+
+_EFF_LABEL: dict[ControlEffectiveness, str] = {
+    ControlEffectiveness.PREVENTS: "✓ PREVENTS",
+    ControlEffectiveness.DETECTS: "◉ DETECTS",
+    ControlEffectiveness.REDUCES: "◈ REDUCES",
+    ControlEffectiveness.MONITORS: "○ MONITORS",
+    ControlEffectiveness.NONE: "✗ NONE",
+}
+
+_EFF_STYLE: dict[ControlEffectiveness, str] = {
+    ControlEffectiveness.PREVENTS: "ag.healthy",
+    ControlEffectiveness.DETECTS: "ag.monitor",
+    ControlEffectiveness.REDUCES: "ag.warning",
+    ControlEffectiveness.MONITORS: "ag.hitl",
+    ControlEffectiveness.NONE: "ag.violation",
+}
+
+
+class ThreatReportRenderer:
+    """Renders threat model data as Rich terminal output."""
+
+    # ── Summary ──────────────────────────────────────────────────────────────
+
+    def render_model_summary(self, model: ThreatModel) -> None:
+        console.print()
+        console.print(Panel(
+            f"[ag.header]System[/ag.header]       {model.system_name}\n"
+            f"[ag.header]Model ID[/ag.header]     [ag.id]{model.model_id}[/ag.id]\n"
+            f"[ag.header]Version[/ag.header]      {model.version}\n\n"
+            f"[ag.label]Assets         [/ag.label][bold]{model.asset_count}[/bold]\n"
+            f"[ag.label]Threat Actors  [/ag.label][bold]{model.actor_count}[/bold]\n"
+            f"[ag.label]Trust Boundaries[/ag.label][bold]{model.boundary_count}[/bold]\n"
+            f"[ag.label]Threats        [/ag.label][bold]{model.threat_count}[/bold]\n"
+            f"[ag.label]Attack Scenarios[/ag.label][bold]{model.scenario_count}[/bold]",
+            title="[ag.brand]ACTSHIELD  THREAT MODEL[/ag.brand]",
+            border_style="rgb(59,130,246)",
+            expand=False,
+        ))
+        console.print()
+
+    # ── Threat list ──────────────────────────────────────────────────────────
+
+    def render_threat_list(self, threats: list[Threat]) -> None:
+        table = Table(
+            box=box.SIMPLE_HEAD,
+            show_header=True,
+            header_style="ag.header",
+            pad_edge=False,
+            expand=False,
+        )
+        table.add_column("ID", style="ag.id", no_wrap=True)
+        table.add_column("Name", min_width=32)
+        table.add_column("Category", style="ag.label")
+        table.add_column("Severity", no_wrap=True)
+        table.add_column("Control Effectiveness", no_wrap=True)
+        table.add_column("Entry Point(s)", style="ag.dim")
+
+        for t in sorted(
+            threats,
+            key=lambda x: list(ThreatSeverity).index(x.severity)
+        ):
+            sev_style = _SEV_STYLE.get(t.severity.value, "")
+            eff_label = _EFF_LABEL.get(t.control_effectiveness, "?")
+            eff_style = _EFF_STYLE.get(t.control_effectiveness, "")
+            table.add_row(
+                t.threat_id,
+                t.name,
+                t.category.value.replace("_", " "),
+                Text(t.severity.value, style=sev_style),
+                Text(eff_label, style=eff_style),
+                ", ".join(t.entry_points[:2]),
+            )
+
+        console.print()
+        console.print(table)
+        console.print(f"  [ag.dim]{len(threats)} threat(s)[/ag.dim]")
+        console.print()
+
+    # ── Threat detail ────────────────────────────────────────────────────────
+
+    def render_threat_detail(self, threat: Threat) -> None:
+        sev_style = _SEV_STYLE.get(threat.severity.value, "")
+        eff_label = _EFF_LABEL.get(threat.control_effectiveness, "?")
+        eff_style = _EFF_STYLE.get(threat.control_effectiveness, "")
+
+        # Attack path tree
+        path_tree = Tree("[ag.label]Attack Path[/ag.label]")
+        for step in threat.attack_path:
+            path_tree.add(f"[ag.dim]{step}[/ag.dim]")
+
+        # Controls table
+        controls_text = "\n".join(
+            f"  [ag.healthy]·[/ag.healthy] {c.replace('_', ' ').title()}"
+            for c in threat.actshield_controls
+        ) or "  [ag.violation]No controls mapped[/ag.violation]"
+
+        content = (
+            f"[ag.label]ID         [/ag.label] {threat.threat_id}\n"
+            f"[ag.label]Category   [/ag.label] {threat.category.value.replace('_', ' ')}\n"
+            f"[ag.label]Severity   [/ag.label] [{sev_style}]{threat.severity.value}[/{sev_style}]\n"
+            f"[ag.label]STRIDE     [/ag.label] {threat.stride_category or 'N/A'}\n"
+            f"[ag.label]MITRE Atlas[/ag.label] {threat.mitre_atlas_id or 'N/A'}\n\n"
+            f"[ag.header]Description[/ag.header]\n  {threat.description}\n\n"
+            f"[ag.header]ActShield Controls[/ag.header]\n{controls_text}\n\n"
+            f"[ag.header]Control Effectiveness[/ag.header]\n  [{eff_style}]{eff_label}[/{eff_style}]\n\n"
+            f"[ag.header]Residual Risk[/ag.header]\n  {threat.residual_risk}\n\n"
+            f"[ag.header]Evidence Generated[/ag.header]\n  "
+            + ", ".join(threat.evidence_generated)
+        )
+
+        console.print()
+        console.print(Panel(
+            content,
+            title=f"[ag.brand]{threat.name}[/ag.brand]",
+            border_style="rgb(59,130,246)",
+            expand=False,
+        ))
+        console.print()
+        console.print(path_tree)
+        console.print()
+
+    # ── Full analysis report ─────────────────────────────────────────────────
+
+    def render_analysis_report(self, result: AnalysisResult) -> None:
+        model = result.model
+        sev_counts = {s.value: 0 for s in ThreatSeverity}
+        for sev, threats in result.threats_by_severity.items():
+            sev_counts[sev] = len(threats)
+
+        console.print()
+        # Header panel
+        console.print(Panel(
+            f"[ag.label]System         [/ag.label]{model.system_name}\n"
+            f"[ag.label]Analysis Time  [/ag.label]{result.analysis_timestamp.strftime('%Y-%m-%d %H:%M:%S UTC')}\n"
+            f"[ag.label]Overall Risk   [/ag.label][bold]{result.overall_risk_score:.1f}[/bold] / 10.0\n",
+            title="[ag.brand]ACTSHIELD  THREAT ANALYSIS[/ag.brand]",
+            border_style="rgb(59,130,246)",
+            expand=False,
+        ))
+
+        # Counts row
+        console.print()
+        console.print("  [ag.header]Threat Inventory[/ag.header]")
+        counts_table = Table(box=box.SIMPLE, show_header=False, pad_edge=False)
+        counts_table.add_column("", style="ag.label", no_wrap=True)
+        counts_table.add_column("", style="bold", no_wrap=True)
+        counts_table.add_row("Assets", str(model.asset_count))
+        counts_table.add_row("Trust Boundaries", str(model.boundary_count))
+        counts_table.add_row("Threat Actors", str(model.actor_count))
+        counts_table.add_row("Identified Threats", str(model.threat_count))
+        counts_table.add_row("Attack Scenarios", str(model.scenario_count))
+        console.print(counts_table)
+
+        # Severity breakdown
+        console.print()
+        console.print("  [ag.header]Severity Breakdown[/ag.header]")
+        sev_table = Table(box=box.SIMPLE, show_header=False, pad_edge=False)
+        sev_table.add_column("", no_wrap=True)
+        sev_table.add_column("", no_wrap=True)
+        for sev, style in _SEV_STYLE.items():
+            count = sev_counts.get(sev, 0)
+            bar = "█" * count
+            sev_table.add_row(
+                Text(f"  {sev:<14}", style=style),
+                Text(f"{count:>3}  {bar}", style=style),
+            )
+        console.print(sev_table)
+
+        # Coverage map
+        console.print()
+        console.print("  [ag.header]Control Domain Coverage[/ag.header]")
+        cov_table = Table(box=box.SIMPLE, show_header=False, pad_edge=False)
+        cov_table.add_column("", style="ag.label", no_wrap=True)
+        cov_table.add_column("", no_wrap=True)
+        for domain, covered in result.control_coverage.items():
+            mark = Text("  ✓", style="ag.healthy") if covered else Text("  ✗", style="ag.violation")
+            cov_table.add_row(f"  {domain:<24}", mark)
+        console.print(cov_table)
+
+        # Attack paths
+        if result.attack_paths:
+            console.print()
+            console.print("  [ag.header]Attack Scenarios[/ag.header]")
+            for path in result.attack_paths:
+                sev_style = _SEV_STYLE.get(path["severity"], "")
+                enforcement = path["enforcement"]
+                enf_style = "ag.block" if enforcement == "BLOCK" else "ag.monitor"
+                console.print(
+                    f"  [{sev_style}]{path['severity']:<10}[/{sev_style}]"
+                    f"  {path['name']:<52}"
+                    f"  [{enf_style}]{enforcement}[/{enf_style}]"
+                )
+
+        # Residual risks
+        if result.residual_risks:
+            console.print()
+            console.print("  [ag.header]Residual Risks[/ag.header]")
+            for risk in result.residual_risks:
+                sev_style = _SEV_STYLE.get(risk["severity"], "")
+                console.print(
+                    f"  [{sev_style}]{risk['severity']:<10}[/{sev_style}]"
+                    f"  {risk['name']:<40}"
+                    f"  score={risk['residual_score']:.1f}"
+                )
+
+        console.print()
+
+    # ── Attack graph (Rich tree) ──────────────────────────────────────────────
+
+    def render_attack_graph(self, result: AnalysisResult) -> None:
+        from actshield.threatmodel.scenarios import get_builtin_scenarios
+        scenarios = get_builtin_scenarios()
+
+        console.print()
+        root = Tree("[ag.brand]ACTSHIELD  ATTACK GRAPH[/ag.brand]")
+        for scenario in scenarios:
+            sev_style = _SEV_STYLE.get(scenario.severity.value, "")
+            scenario_node = root.add(
+                f"[{sev_style}]{scenario.severity.value}[/{sev_style}]  {scenario.name}"
+            )
+            for step in scenario.steps:
+                outcome_style = (
+                    "ag.healthy" if step.outcome == "blocked"
+                    else "ag.warning" if step.outcome == "detected"
+                    else "ag.dim"
+                )
+                label = f"[{outcome_style}]{step.outcome.upper():>8}[/{outcome_style}]  Step {step.step_num}: {step.description[:60]}"
+                scenario_node.add(label)
+        console.print(root)
+        console.print()
+
+    # ── Markdown export ───────────────────────────────────────────────────────
+
+    def to_markdown(self, result: AnalysisResult) -> str:
+        model = result.model
+        lines = [
+            f"# ActShield Threat Model Report",
+            f"",
+            f"**System:** {model.system_name}  ",
+            f"**Date:** {result.analysis_timestamp.strftime('%Y-%m-%d %H:%M UTC')}  ",
+            f"**Overall Risk Score:** {result.overall_risk_score:.1f} / 10.0  ",
+            f"**Model ID:** `{model.model_id}`",
+            f"",
+            f"---",
+            f"",
+            f"## Inventory",
+            f"",
+            f"| Category | Count |",
+            f"|----------|-------|",
+            f"| Assets | {model.asset_count} |",
+            f"| Trust Boundaries | {model.boundary_count} |",
+            f"| Threat Actors | {model.actor_count} |",
+            f"| Identified Threats | {model.threat_count} |",
+            f"| Attack Scenarios | {model.scenario_count} |",
+            f"",
+            f"## Severity Breakdown",
+            f"",
+            f"| Severity | Count |",
+            f"|----------|-------|",
+        ]
+        for sev in ThreatSeverity:
+            count = len(result.threats_by_severity.get(sev.value, []))
+            lines.append(f"| {sev.value} | {count} |")
+
+        lines += [
+            f"",
+            f"## Control Domain Coverage",
+            f"",
+            f"| Domain | Covered |",
+            f"|--------|---------|",
+        ]
+        for domain, covered in result.control_coverage.items():
+            mark = "✓" if covered else "✗"
+            lines.append(f"| {domain} | {mark} |")
+
+        lines += [
+            f"",
+            f"## Threats",
+            f"",
+        ]
+        for sev in ThreatSeverity:
+            threats = result.threats_by_severity.get(sev.value, [])
+            if threats:
+                lines.append(f"### {sev.value}")
+                lines.append(f"")
+                for t in threats:
+                    lines.append(f"#### {t['name']}")
+                    lines.append(f"")
+                    lines.append(f"- **ID:** `{t['threat_id']}`")
+                    lines.append(f"- **Category:** {t['category']}")
+                    lines.append(f"- **Controls:** {', '.join(t.get('actshield_controls', []))}")
+                    lines.append(f"- **Effectiveness:** {t.get('control_effectiveness', 'N/A')}")
+                    lines.append(f"- **Residual Risk:** {t.get('residual_risk', 'N/A')}")
+                    lines.append(f"")
+
+        if result.residual_risks:
+            lines += [f"## Residual Risks", f""]
+            for risk in result.residual_risks:
+                lines.append(
+                    f"- **{risk['name']}** ({risk['severity']}) — "
+                    f"residual score: {risk['residual_score']:.1f} — {risk['residual_risk']}"
+                )
+            lines.append(f"")
+
+        lines += [
+            f"---",
+            f"",
+            f"*Generated by ActShield v0.9.0*",
+            f"",
+        ]
+        return "\n".join(lines)