Stakeholder Reporting

"""
Deception Operation ROI Metrics.
Calculates key performance indicators and return-on-investment
metrics for stakeholder reporting.
"""
import json
from dataclasses import dataclass
from typing import List

@dataclass
class EngagementMetrics:
    engagement_id: str
    adversaries_detected: int
    ttps_captured: int
    novel_ttps: int           # TTPs not covered by existing rules
    detection_rules_deployed: int
    iocs_extracted: int
    mean_time_to_detect_hours: float
    deception_assets_used: int
    cost_of_assets_usd: float

def calculate_roi(
    engagements: List[EngagementMetrics],
    total_investment_usd: float,
    estimated_breach_cost_usd: float = 4_450_000,
) -> dict:
    """Calculate ROI metrics for deception operations."""

    total_adversaries = sum(e.adversaries_detected for e in engagements)
    total_ttps = sum(e.ttps_captured for e in engagements)
    total_novel = sum(e.novel_ttps for e in engagements)
    total_rules = sum(e.detection_rules_deployed for e in engagements)
    total_iocs = sum(e.iocs_extracted for e in engagements)
    avg_mttd = (
        sum(e.mean_time_to_detect_hours for e in engagements)
        / len(engagements) if engagements else 0
    )

    # Estimated value of early detection
    # Industry average breach dwell time: 204 days (IBM 2024)
    # Each day of earlier detection saves ~$21,800
    days_saved_per_detection = 200  # Conservative estimate
    value_per_detection = days_saved_per_detection * 21800
    total_detection_value = total_adversaries * value_per_detection

    roi_percentage = (
        ((total_detection_value - total_investment_usd)
         / total_investment_usd) * 100
        if total_investment_usd > 0 else 0
    )

    return {
        "report_period": f"{len(engagements)} engagements",
        "investment": {
            "total_usd": total_investment_usd,
            "per_engagement_usd": round(
                total_investment_usd / max(len(engagements), 1), 2
            ),
        },
        "outcomes": {
            "adversaries_detected": total_adversaries,
            "ttps_captured": total_ttps,
            "novel_ttps_discovered": total_novel,
            "detection_rules_deployed": total_rules,
            "iocs_extracted": total_iocs,
            "mean_time_to_detect_hours": round(avg_mttd, 1),
        },
        "value": {
            "estimated_detection_value_usd": total_detection_value,
            "estimated_roi_percentage": round(roi_percentage, 1),
            "cost_per_adversary_detected": round(
                total_investment_usd / max(total_adversaries, 1), 2
            ),
            "cost_per_ttp_captured": round(
                total_investment_usd / max(total_ttps, 1), 2
            ),
        },
        "benchmarks": {
            "industry_avg_dwell_days": 204,
            "deception_detection_hours": round(avg_mttd, 1),
            "improvement_factor": round(
                (204 * 24) / max(avg_mttd, 1), 1
            ),
        },
    }

if __name__ == "__main__":
    engagements = [
        EngagementMetrics(
            engagement_id="SHD-2026-0042",
            adversaries_detected=1,
            ttps_captured=8,
            novel_ttps=3,
            detection_rules_deployed=3,
            iocs_extracted=5,
            mean_time_to_detect_hours=2.5,
            deception_assets_used=8,
            cost_of_assets_usd=2400,
        ),
    ]

    roi = calculate_roi(
        engagements,
        total_investment_usd=15000,
    )
    print(json.dumps(roi, indent=2))