sim_card_decoder.py

#!/usr/bin/env python3
"""
SIM Card Data Decoder - Professional Forensic Analysis Tool

This tool provides comprehensive analysis of ICCID and IMSI numbers for forensic purposes.
It includes format conversion utilities, professional reporting, and educational context.

Educational Disclaimer:
This tool is designed for educational and forensic analysis purposes only.
Users are responsible for ensuring compliance with all applicable laws and regulations.
"""

import os
import sys
import csv
import json
import time
import uuid
import logging
import argparse
from typing import Dict, List, Any, Optional, Tuple
from datetime import datetime
from pathlib import Path

class BatchProcessor:
    """
    Batch processor for handling multiple ICCID/IMSI analyses.
    
    Provides efficient processing of multiple identifiers with comprehensive
    error handling and professional reporting capabilities.
    """
    
    def __init__(self, decoder: 'SIMCardDecoder'):
        """Initialize batch processor with decoder instance."""
        self.decoder = decoder
        self.batch_stats = {
            'total_processed': 0,
            'successful_analyses': 0,
            'failed_analyses': 0,
            'iccid_count': 0,
            'imsi_count': 0,
            'start_time': time.time(),
            'end_time': None
        }
    
    def process_file(self, filepath: str) -> None:
        """Process a file containing multiple ICCIDs/IMSIs."""
        try:
            # Read and parse input file
            identifiers = self._parse_input_file(filepath)
            if not identifiers:
                print("❌ No valid identifiers found in batch file.")
                return
            
            # Process each identifier
            for identifier in identifiers:
                self._process_identifier(identifier)
            
            # Update batch stats
            self.batch_stats['end_time'] = time.time()
            
            # Generate reports
            self._generate_batch_reports()
            
            # Display summary
            self._display_batch_summary()
            
        except Exception as e:
            print(f"❌ Batch processing failed: {e}")
            if self.decoder.log_level == 'DEBUG':
                import traceback
                traceback.print_exc()
            raise
    
    def _parse_input_file(self, filepath: str) -> List[str]:
        """Parse input file and extract valid identifiers."""
        identifiers = []
        try:
            with open(filepath, 'r') as f:
                for line in f:
                    identifier = line.strip()
                    if identifier and not identifier.startswith('#'):
                        if (self.decoder.validate_iccid(identifier) or 
                            self.decoder.validate_imsi(identifier)):
                            identifiers.append(identifier)
        except Exception as e:
            print(f"❌ Error reading file: {e}")
            raise
        return identifiers
    
    def _process_identifier(self, identifier: str) -> None:
        """Process a single identifier and update stats."""
        self.batch_stats['total_processed'] += 1
        try:
            if self.decoder.validate_iccid(identifier):
                self.decoder.analyze_iccid(identifier)
                self.batch_stats['iccid_count'] += 1
                self.batch_stats['successful_analyses'] += 1
            elif self.decoder.validate_imsi(identifier):
                self.decoder.analyze_imsi(identifier)
                self.batch_stats['imsi_count'] += 1
                self.batch_stats['successful_analyses'] += 1
            else:
                self.batch_stats['failed_analyses'] += 1
        except Exception as e:
            self.batch_stats['failed_analyses'] += 1
            if self.decoder.log_level == 'DEBUG':
                print(f"❌ Error processing {identifier}: {e}")
    
    def _generate_batch_reports(self) -> None:
        """Generate professional reports for batch processing."""
        try:
            # Generate detailed report
            self.decoder.generate_professional_report(
                report_type="detailed",
                export_to_file=True
            )
            
            # Generate CSV report
            self.decoder.generate_professional_report(
                report_type="csv",
                export_to_file=True
            )
            
        except Exception as e:
            print(f"❌ Error generating reports: {e}")
            if self.decoder.log_level == 'DEBUG':
                import traceback
                traceback.print_exc()
    
    def _display_batch_summary(self) -> None:
        """Display batch processing summary."""
        duration = self.batch_stats['end_time'] - self.batch_stats['start_time']
        success_rate = (self.batch_stats['successful_analyses'] / 
                       self.batch_stats['total_processed'] * 100)
        
        print("\n📊 Batch Processing Summary:")
        print(f"   Total Processed: {self.batch_stats['total_processed']}")
        print(f"   ICCIDs: {self.batch_stats['iccid_count']}")
        print(f"   IMSIs: {self.batch_stats['imsi_count']}")
        print(f"   Success Rate: {success_rate:.1f}%")
        print(f"   Duration: {duration:.2f} seconds")
        print(f"   Reports Generated: 2 (Detailed + CSV)")

class ForensicReportGenerator:
    """
    Professional report generator for forensic analysis results.
    
    Provides comprehensive reporting capabilities with multiple formats
    and professional formatting suitable for forensic documentation.
    """
    
    def __init__(self, session_id: str, logger: logging.Logger):
        """Initialize report generator with session ID and logger."""
        self.session_id = session_id
        self.logger = logger
        self.reports_dir = os.path.join(os.getcwd(), "reports")
        os.makedirs(self.reports_dir, exist_ok=True)
    
    def generate_console_report(self, results: List[Dict[str, Any]], 
                              cross_validation: Optional[Dict[str, Any]] = None) -> str:
        """Generate console-formatted report."""
        report = []
        report.append("\n" + "="*80)
        report.append("SIM CARD DATA DECODER - FORENSIC ANALYSIS REPORT")
        report.append("="*80)
        report.append(f"Session ID: {self.session_id}")
        report.append(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
        report.append("\n")
        
        for result in results:
            report.append("-"*80)
            if result['type'] == 'ICCID':
                self._add_iccid_section(report, result)
            else:
                self._add_imsi_section(report, result)
        
        if cross_validation:
            report.append("\n" + "="*80)
            report.append("CROSS-VALIDATION ANALYSIS")
            report.append("="*80)
            self._add_cross_validation_section(report, cross_validation)
        
        return "\n".join(report)
    
    def generate_detailed_report(self, results: List[Dict[str, Any]], 
                               cross_validation: Optional[Dict[str, Any]] = None) -> str:
        """Generate detailed forensic report."""
        report = []
        report.append("SIM CARD DATA DECODER - DETAILED FORENSIC ANALYSIS REPORT")
        report.append("="*80)
        report.append(f"Session ID: {self.session_id}")
        report.append(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
        report.append("\n")
        
        for result in results:
            report.append("\n" + "="*80)
            if result['type'] == 'ICCID':
                self._add_detailed_iccid_section(report, result)
            else:
                self._add_detailed_imsi_section(report, result)
        
        if cross_validation:
            report.append("\n" + "="*80)
            report.append("CROSS-VALIDATION ANALYSIS")
            report.append("="*80)
            self._add_detailed_cross_validation_section(report, cross_validation)
        
        return "\n".join(report)
    
    def generate_csv_report(self, results: List[Dict[str, Any]]) -> str:
        """Generate CSV-formatted report."""
        report = []
        headers = [
            "Type", "Identifier", "Country", "Operator", "Confidence",
            "Analysis Time", "Session ID"
        ]
        report.append(",".join(headers))
        
        for result in results:
            if result['type'] == 'ICCID':
                row = [
                    "ICCID",
                    result['input'],
                    result['components']['country_code']['country'],
                    result['components']['issuer_identifier']['operator'],
                    result['interpretation']['forensic_confidence'],
                    result['analysis_timestamp'],
                    self.session_id
                ]
            else:
                row = [
                    "IMSI",
                    result['input'],
                    result['components']['mcc']['country'],
                    result['components']['mnc']['operator'],
                    result['interpretation']['forensic_confidence'],
                    result['analysis_timestamp'],
                    self.session_id
                ]
            report.append(",".join(row))
        
        return "\n".join(report)
    
    def generate_session_report(self, summary: Dict[str, Any]) -> str:
        """Generate session summary report."""
        report = []
        report.append("SIM CARD DATA DECODER - SESSION SUMMARY REPORT")
        report.append("="*80)
        report.append(f"Session ID: {self.session_id}")
        report.append(f"Start Time: {summary['start_time']}")
        report.append(f"End Time: {summary['end_time']}")
        report.append(f"Duration: {summary['duration_seconds']:.2f} seconds")
        report.append(f"Analyses Performed: {summary['analyses_performed']}")
        report.append("\n")
        
        if 'batch_stats' in summary:
            report.append("Batch Processing Statistics:")
            report.append(f"  Total Processed: {summary['batch_stats']['total_processed']}")
            report.append(f"  Successful: {summary['batch_stats']['successful_analyses']}")
            report.append(f"  Failed: {summary['batch_stats']['failed_analyses']}")
            report.append(f"  ICCIDs: {summary['batch_stats']['iccid_count']}")
            report.append(f"  IMSIs: {summary['batch_stats']['imsi_count']}")
        
        return "\n".join(report)
    
    def export_to_file(self, content: str, filename: str) -> str:
        """Export report content to file."""
        filepath = os.path.join(self.reports_dir, filename)
        try:
            with open(filepath, 'w', encoding='utf-8') as f:
                f.write(content)
            self.logger.info(f"Report exported to: {filepath}")
            return filepath
        except Exception as e:
            self.logger.error(f"Error exporting report: {e}")
            raise
    
    def _add_iccid_section(self, report: List[str], result: Dict[str, Any]) -> None:
        """Add ICCID analysis section to report."""
        report.append(f"ICCID Analysis: {result['input']}")
        report.append(f"Country: {result['components']['country_code']['country']}")
        report.append(f"Operator: {result['components']['issuer_identifier']['operator']}")
        report.append(f"Confidence: {result['interpretation']['forensic_confidence']}")
    
    def _add_imsi_section(self, report: List[str], result: Dict[str, Any]) -> None:
        """Add IMSI analysis section to report."""
        report.append(f"IMSI Analysis: {result['input']}")
        report.append(f"Country: {result['components']['mcc']['country']}")
        report.append(f"Operator: {result['components']['mnc']['operator']}")
        report.append(f"Confidence: {result['interpretation']['forensic_confidence']}")
    
    def _add_cross_validation_section(self, report: List[str], 
                                    cross_validation: Dict[str, Any]) -> None:
        """Add cross-validation section to report."""
        report.append("Cross-Validation Results:")
        report.append(f"Match: {cross_validation['match']}")
        report.append(f"Confidence: {cross_validation['confidence']}")
        if cross_validation['notes']:
            report.append("\nNotes:")
            for note in cross_validation['notes']:
                report.append(f"• {note}")
    
    def _add_detailed_iccid_section(self, report: List[str], result: Dict[str, Any]) -> None:
        """Add detailed ICCID analysis section to report."""
        report.append(f"ICCID Analysis: {result['input']}")
        report.append("\nComponents:")
        report.append(f"  Country Code: {result['components']['country_code']['code']}")
        report.append(f"  Country: {result['components']['country_code']['country']}")
        report.append(f"  Issuer Identifier: {result['components']['issuer_identifier']['code']}")
        report.append(f"  Operator: {result['components']['issuer_identifier']['operator']}")
        report.append(f"  Individual Account: {result['components']['individual_account']}")
        report.append(f"  Checksum: {result['components']['checksum']}")
        
        report.append("\nInterpretation:")
        report.append(f"  Forensic Confidence: {result['interpretation']['forensic_confidence']}")
        report.append(f"  Validation Status: {result['interpretation']['validation_status']}")
        
        if result['interpretation']['notes']:
            report.append("\nNotes:")
            for note in result['interpretation']['notes']:
                report.append(f"• {note}")
    
    def _add_detailed_imsi_section(self, report: List[str], result: Dict[str, Any]) -> None:
        """Add detailed IMSI analysis section to report."""
        report.append(f"IMSI Analysis: {result['input']}")
        report.append("\nComponents:")
        report.append(f"  MCC: {result['components']['mcc']['code']}")
        report.append(f"  Country: {result['components']['mcc']['country']}")
        report.append(f"  MNC: {result['components']['mnc']['code']}")
        report.append(f"  Operator: {result['components']['mnc']['operator']}")
        report.append(f"  MSIN: {result['components']['msin']}")
        
        report.append("\nInterpretation:")
        report.append(f"  Forensic Confidence: {result['interpretation']['forensic_confidence']}")
        report.append(f"  Validation Status: {result['interpretation']['validation_status']}")
        
        if result['interpretation']['notes']:
            report.append("\nNotes:")
            for note in result['interpretation']['notes']:
                report.append(f"• {note}")
    
    def _add_detailed_cross_validation_section(self, report: List[str], 
                                             cross_validation: Dict[str, Any]) -> None:
        """Add detailed cross-validation section to report."""
        report.append("Cross-Validation Analysis")
        report.append("\nResults:")
        report.append(f"  Match: {cross_validation['match']}")
        report.append(f"  Confidence: {cross_validation['confidence']}")
        
        if cross_validation['details']:
            report.append("\nDetails:")
            for key, value in cross_validation['details'].items():
                report.append(f"  {key}: {value}")
        
        if cross_validation['notes']:
            report.append("\nNotes:")
            for note in cross_validation['notes']:
                report.append(f"• {note}")

class SIMCardDecoder:
    """
    Professional SIM Card Data Decoder for Digital Forensics
    
    This class provides comprehensive analysis of ICCID and IMSI numbers commonly
    encountered in mobile device forensic examinations. It breaks down these
    identifiers into their constituent components and provides educational
    interpretations of each part.
    
    The tool maintains audit logs and session tracking for forensic accountability
    and can operate in both interactive and batch processing modes.
    """
    
    def __init__(self, log_level: str = "INFO", quiet_mode: bool = False):
        """
        Initialize the SIM Card Decoder with logging and session management.
        
        Args:
            log_level (str): Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
            quiet_mode (bool): If True, suppress console output except errors
            
        Forensic Purpose:
            Establishes audit trail and session tracking for forensic accountability.
            Each decoder instance maintains its own session ID for correlation of
            analysis results with examination records.
        """
        self.session_id = str(uuid.uuid4())
        self.session_start = datetime.now()
        self.quiet_mode = quiet_mode
        self.analysis_count = 0
        self.analysis_results = []  # Store all analysis results for reporting
        
        # Initialize logging system
        self._setup_logging(log_level)
        
        # Initialize reporting system
        self.report_generator = ForensicReportGenerator(self.session_id, self.logger)
        
        # Log session initialization
        self.logger.info(f"SIM Card Decoder session initialized - Session ID: {self.session_id}")
        self.logger.info(f"Session start time: {self.session_start.isoformat()}")
        
        if not quiet_mode:
            self._display_disclaimer()
    
    def _setup_logging(self, log_level: str) -> None:
        """
        Configure comprehensive logging system for forensic audit trail.
        
        Args:
            log_level (str): Desired logging level
            
        Forensic Purpose:
            Creates timestamped log files for audit purposes. All operations,
            inputs, and results are logged to maintain chain of custody and
            enable review of analysis procedures.
        """
        # Create logs directory if it doesn't exist
        log_dir = "logs"
        if not os.path.exists(log_dir):
            os.makedirs(log_dir)
        
        # Create timestamped log file
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        log_filename = os.path.join(log_dir, f"sim_decoder_{timestamp}_{self.session_id[:8]}.log")
        
        # Configure logger
        self.logger = logging.getLogger(f"SIMDecoder_{self.session_id[:8]}")
        self.logger.setLevel(getattr(logging, log_level.upper()))
        
        # File handler for audit trail
        file_handler = logging.FileHandler(log_filename)
        file_handler.setLevel(logging.DEBUG)
        
        # Console handler for user feedback
        console_handler = logging.StreamHandler()
        console_handler.setLevel(logging.WARNING if self.quiet_mode else logging.INFO)
        
        # Detailed formatter for forensic logging
        formatter = logging.Formatter(
            '%(asctime)s - %(name)s - %(levelname)s - Session:%(session_id)s - %(message)s'
        )
        
        # Add session ID to log records
        file_handler.setFormatter(formatter)
        console_handler.setFormatter(formatter)
        
        # Add custom filter to inject session ID
        class SessionFilter(logging.Filter):
            def __init__(self, session_id):
                self.session_id = session_id
            
            def filter(self, record):
                record.session_id = self.session_id[:8]
                return True
        
        session_filter = SessionFilter(self.session_id)
        file_handler.addFilter(session_filter)
        console_handler.addFilter(session_filter)
        
        self.logger.addHandler(file_handler)
        self.logger.addHandler(console_handler)
        
        self.logger.info(f"Logging initialized - Log file: {log_filename}")
    
    def _display_disclaimer(self) -> None:
        """
        Display professional forensic disclaimer to user.
        
        Forensic Purpose:
            Ensures users understand the limitations and proper use of the tool
            in forensic contexts. Emphasizes the need for validation through
            official channels.
        """
        disclaimer = """
╔══════════════════════════════════════════════════════════════════════════════╗
║                          FORENSIC DISCLAIMER                                ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  This tool is provided for EDUCATIONAL and INVESTIGATIVE purposes only.     ║
║                                                                              ║
║  ⚠️  IMPORTANT VALIDATION REQUIREMENTS:                                      ║
║                                                                              ║
║  • All results MUST be validated through official carrier databases         ║
║  • Cross-reference findings with authoritative telecommunications sources    ║
║  • Verify interpretations before use in legal proceedings                   ║
║  • Document all validation steps in your forensic report                    ║
║                                                                              ║
║  This tool provides educational interpretations of SIM card data structures ║
║  but does not guarantee accuracy for evidential purposes.                   ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
        """
        print(disclaimer)
    
    def validate_iccid(self, iccid: str) -> bool:
        """
        Validate ICCID format and structure.
        
        Args:
            iccid (str): ICCID number to validate
            
        Returns:
            bool: True if ICCID appears valid, False otherwise
            
        Forensic Purpose:
            Ensures input data conforms to expected ICCID format standards
            before analysis. Invalid formats may indicate data corruption,
            extraction errors, or non-standard implementations.
        """
        if not iccid:
            self.logger.error("ICCID validation failed: Empty input")
            return False
        
        # Remove spaces and convert to string
        iccid_clean = str(iccid).replace(" ", "").replace("-", "")
        
        # ICCID should be 19-20 digits
        if not re.match(r'^[0-9]{19,20}$', iccid_clean):
            self.logger.error(f"ICCID validation failed: Invalid format - {iccid}")
            return False
        
        # ICCID typically starts with 89 (telecommunications identifier)
        if not iccid_clean.startswith('89'):
            self.logger.warning(f"ICCID format warning: Does not start with standard '89' prefix - {iccid}")
        
        self.logger.info(f"ICCID validation successful: {iccid}")
        return True
    
    def validate_imsi(self, imsi: str) -> bool:
        """
        Validate IMSI format and structure.
        
        Args:
            imsi (str): IMSI number to validate
            
        Returns:
            bool: True if IMSI appears valid, False otherwise
            
        Forensic Purpose:
            Ensures input data conforms to expected IMSI format standards.
            IMSI validation is critical for proper MCC/MNC extraction and
            subscriber identification in forensic investigations.
        """
        if not imsi:
            self.logger.error("IMSI validation failed: Empty input")
            return False
        
        # Remove spaces and convert to string
        imsi_clean = str(imsi).replace(" ", "").replace("-", "")
        
        # IMSI should be typically 15 digits (can be 14-15)
        if not re.match(r'^[0-9]{14,15}$', imsi_clean):
            self.logger.error(f"IMSI validation failed: Invalid format - {imsi}")
            return False
        
        self.logger.info(f"IMSI validation successful: {imsi}")
        return True
    
    def _get_country_database(self) -> Dict[str, Dict[str, str]]:
        """
        Get comprehensive country code database for ICCID analysis.
        
        Returns:
            Dict[str, Dict[str, str]]: Country code mappings
            
        Forensic Purpose:
            Provides authoritative country code mappings for geographic
            identification of SIM card origin. Critical for determining
            jurisdiction and carrier registration location.
        """
        return {
            # North America
            "1": {"country": "United States", "region": "North America"},
            "302": {"country": "Canada", "region": "North America"},
            
            # Europe
            "44": {"country": "United Kingdom", "region": "Europe"},
            "49": {"country": "Germany", "region": "Europe"},
            "33": {"country": "France", "region": "Europe"},
            "39": {"country": "Italy", "region": "Europe"},
            "34": {"country": "Spain", "region": "Europe"},
            "31": {"country": "Netherlands", "region": "Europe"},
            "46": {"country": "Sweden", "region": "Europe"},
            "47": {"country": "Norway", "region": "Europe"},
            "45": {"country": "Denmark", "region": "Europe"},
            "41": {"country": "Switzerland", "region": "Europe"},
            "43": {"country": "Austria", "region": "Europe"},
            "32": {"country": "Belgium", "region": "Europe"},
            
            # Asia Pacific
            "81": {"country": "Japan", "region": "Asia Pacific"},
            "86": {"country": "China", "region": "Asia Pacific"},
            "82": {"country": "South Korea", "region": "Asia Pacific"},
            "65": {"country": "Singapore", "region": "Asia Pacific"},
            "61": {"country": "Australia", "region": "Asia Pacific"},
            "505": {"country": "New Zealand", "region": "Asia Pacific"},
            "91": {"country": "India", "region": "Asia Pacific"},
            
            # Other regions
            "7": {"country": "Russia", "region": "Europe/Asia"},
            "55": {"country": "Brazil", "region": "South America"},
            "52": {"country": "Mexico", "region": "North America"},
            "27": {"country": "South Africa", "region": "Africa"},
            "20": {"country": "Egypt", "region": "Africa/Middle East"},
            "966": {"country": "Saudi Arabia", "region": "Middle East"},
        }
    
    def _get_uk_operator_database(self) -> Dict[str, Dict[str, str]]:
        """
        Get UK network operator database for detailed carrier identification.
        
        Returns:
            Dict[str, Dict[str, str]]: UK operator mappings
            
        Forensic Purpose:
            Enables precise identification of UK mobile network operators
            from ICCID issuer codes. Critical for UK-based investigations
            and carrier liaison requirements.
        """
        return {
            "01": {"operator": "Vodafone UK", "type": "MNO", "network_code": "15"},
            "02": {"operator": "O2 UK", "type": "MNO", "network_code": "10"},
            "11": {"operator": "O2 UK", "type": "MNO", "network_code": "11"},
            "20": {"operator": "Three UK", "type": "MNO", "network_code": "20"},
            "30": {"operator": "EE", "type": "MNO", "network_code": "30"},
            "31": {"operator": "EE", "type": "MNO", "network_code": "31"},
            "32": {"operator": "EE", "type": "MNO", "network_code": "32"},
            "33": {"operator": "EE", "type": "MNO", "network_code": "33"},
            "34": {"operator": "EE", "type": "MNO", "network_code": "34"},
            "50": {"operator": "JT (Jersey Telecom)", "type": "Regional", "network_code": "50"},
            "55": {"operator": "Sure (Guernsey)", "type": "Regional", "network_code": "55"},
            "58": {"operator": "Manx Telecom", "type": "Regional", "network_code": "58"},
            "91": {"operator": "Vodafone UK", "type": "MNO", "network_code": "91"},
            "94": {"operator": "Hutchison 3G UK", "type": "MNO", "network_code": "94"},
        }
    
    def _get_international_operator_database(self) -> Dict[str, Dict[str, str]]:
        """
        Get international operator database for global carrier identification.
        
        Returns:
            Dict[str, Dict[str, str]]: International operator mappings
            
        Forensic Purpose:
            Provides identification capabilities for major international
            mobile network operators. Essential for cross-border investigations
            and international carrier coordination.
        """
        return {
            # US Operators
            "015": {"operator": "AT&T", "country": "USA", "type": "MNO"},
            "016": {"operator": "T-Mobile USA", "country": "USA", "type": "MNO"},
            "012": {"operator": "Verizon", "country": "USA", "type": "MNO"},
            "120": {"operator": "Sprint", "country": "USA", "type": "MNO"},
            
            # German Operators
            "01": {"operator": "T-Mobile Germany", "country": "Germany", "type": "MNO"},
            "02": {"operator": "Vodafone Germany", "country": "Germany", "type": "MNO"},
            "03": {"operator": "E-Plus", "country": "Germany", "type": "MNO"},
            "07": {"operator": "O2 Germany", "country": "Germany", "type": "MNO"},
            
            # French Operators
            "01": {"operator": "Orange France", "country": "France", "type": "MNO"},
            "02": {"operator": "SFR", "country": "France", "type": "MNO"},
            "03": {"operator": "Bouygues Telecom", "country": "France", "type": "MNO"},
            "10": {"operator": "Free Mobile", "country": "France", "type": "MNO"},
            
            # Other major operators
            "001": {"operator": "NTT DoCoMo", "country": "Japan", "type": "MNO"},
            "003": {"operator": "KDDI", "country": "Japan", "type": "MNO"},
            "004": {"operator": "SoftBank", "country": "Japan", "type": "MNO"},
        }
    
    def _validate_luhn_checksum(self, number: str) -> bool:
        """
        Validate number using Luhn algorithm for checksum verification.
        
        Args:
            number (str): Number to validate
            
        Returns:
            bool: True if checksum is valid, False otherwise
            
        Forensic Purpose:
            Verifies mathematical integrity of ICCID using industry-standard
            Luhn algorithm. Invalid checksums may indicate data corruption,
            transcription errors, or potentially fraudulent identifiers.
        """
        try:
            # Remove any spaces or hyphens
            clean_number = number.replace(" ", "").replace("-", "")
            
            # Luhn algorithm implementation
            total = 0
            reverse_digits = clean_number[::-1]
            
            for i, digit in enumerate(reverse_digits):
                n = int(digit)
                if i % 2 == 1:  # Every second digit from the right
                    n = n * 2
                    if n > 9:
                        n = n // 10 + n % 10
                total += n
            
            is_valid = (total % 10) == 0
            self.logger.debug(f"Luhn validation for {number}: {'VALID' if is_valid else 'INVALID'}")
            return is_valid
            
        except (ValueError, TypeError) as e:
            self.logger.error(f"Luhn validation error for {number}: {e}")
            return False
    
    def _parse_iccid_components(self, iccid: str) -> Dict[str, Any]:
        """
        Parse ICCID into its component parts with forensic analysis.
        
        Args:
            iccid (str): Clean ICCID number to parse
            
        Returns:
            Dict[str, Any]: Detailed component breakdown
            
        Forensic Purpose:
            Systematically breaks down ICCID structure to extract
            investigatively relevant information including geographic
            origin, carrier identification, and account details.
        """
        clean_iccid = iccid.replace(" ", "").replace("-", "")
        components = {}
        
        # Major Industry Identifier (MII) - First 2 digits
        components["mii"] = {
            "value": clean_iccid[:2],
            "description": "Major Industry Identifier",
            "interpretation": "Telecommunications" if clean_iccid[:2] == "89" else "Non-standard MII"
        }
        
        # Variable length parsing for Country Code and Issuer
        remaining = clean_iccid[2:-1]  # Exclude MII and check digit
        
        # Try to identify country code (1-3 digits)
        country_info = None
        country_code = ""
        issuer_start_pos = 0
        
        country_db = self._get_country_database()
        
        # Try 3-digit country codes first, then 2-digit, then 1-digit
        for cc_length in [3, 2, 1]:
            if len(remaining) >= cc_length:
                test_cc = remaining[:cc_length]
                if test_cc in country_db:
                    country_code = test_cc
                    country_info = country_db[test_cc]
                    issuer_start_pos = cc_length
                    break
        
        components["country_code"] = {
            "value": country_code,
            "description": "Country Code",
            "country": country_info["country"] if country_info else "Unknown",
            "region": country_info["region"] if country_info else "Unknown"
        }
        
        # Issuer Identifier - remaining digits after country code
        issuer_digits = remaining[issuer_start_pos:]
        
        # For UK, try to match operator codes
        operator_info = None
        if country_code == "44" and len(issuer_digits) >= 2:
            uk_operators = self._get_uk_operator_database()
            issuer_code = issuer_digits[:2]
            if issuer_code in uk_operators:
                operator_info = uk_operators[issuer_code]
        
        components["issuer_identifier"] = {
            "value": issuer_digits[:4] if len(issuer_digits) >= 4 else issuer_digits,
            "description": "Issuer Identifier Number",
            "operator": operator_info["operator"] if operator_info else "Unknown",
            "operator_type": operator_info["type"] if operator_info else "Unknown"
        }
        
        # Individual Account Identification
        account_digits = issuer_digits[4:] if len(issuer_digits) > 4 else ""
        components["account_identification"] = {
            "value": account_digits,
            "description": "Individual Account Identification",
            "length": len(account_digits)
        }
        
        # Check Digit
        components["check_digit"] = {
            "value": clean_iccid[-1],
            "description": "Luhn Check Digit",
            "valid": self._validate_luhn_checksum(clean_iccid)
        }
        
        return components
    
    def analyze_iccid(self, iccid: str) -> Dict[str, Any]:
        """
        Analyze ICCID and break down into component parts.
        
        Args:
            iccid (str): ICCID number to analyze
            
        Returns:
            Dict[str, Any]: Analysis results with component breakdown
            
        Forensic Purpose:
            Breaks down ICCID into investigatively relevant components:
            - Major Industry Identifier (MII)
            - Country code for geographic origin
            - Issuer identifier for carrier identification
            - Individual account identification
            - Luhn checksum validation for integrity verification
            - Detects suspicious/test patterns and provides educational notes
        """
        self.analysis_count += 1
        self.logger.info(f"Starting ICCID analysis #{self.analysis_count}: {iccid}")
        
        if not self.validate_iccid(iccid):
            raise ValueError("Invalid ICCID format")
        
        # Parse ICCID components
        components = self._parse_iccid_components(iccid)
        
        # Generate validation notes
        validation_notes = []
        educational_notes = []
        references = [
            "ITU-T E.118: ICCID structure and allocation (https://www.itu.int/rec/T-REC-E.118/en)",
            "GSMA Official ICCID/IMSI Database (https://www.gsma.com/)",
        ]
        
        # Check MII
        if components["mii"]["value"] != "89":
            validation_notes.append("⚠️  Non-standard MII: Expected '89' for telecommunications")
            educational_notes.append("MII (Major Industry Identifier) should be '89' for telecom SIMs. Non-standard MII may indicate a test card, non-telecom card, or data entry error.")
        
        # Check country code recognition
        if components["country_code"]["country"] == "Unknown":
            validation_notes.append("⚠️  Unrecognized country code")
            educational_notes.append("Country code not found in ITU/GSMA databases. This may indicate a test SIM, a new allocation, or a data entry error. Cross-check with official sources.")
        
        # Check Luhn validation
        if not components["check_digit"]["valid"]:
            validation_notes.append("❌ Invalid Luhn checksum - possible data corruption")
            educational_notes.append("Luhn checksum failure may indicate a corrupted, incomplete, or non-genuine ICCID. Forensic best practice: verify with original SIM or carrier records.")
        else:
            validation_notes.append("✅ Valid Luhn checksum")
        
        # Check operator identification
        if components["issuer_identifier"]["operator"] == "Unknown":
            validation_notes.append("ℹ️  Operator not identified in database")
            educational_notes.append("Operator code not found in GSMA/ITU databases. For further research, consult the GSMA online lookup or contact the suspected carrier. See: https://www.gsma.com/ for operator lists.")
        else:
            validation_notes.append(f"✅ Operator identified: {components['issuer_identifier']['operator']}")
        
        # Suspicious/test ICCID patterns (e.g., all zeros, sequential, known test ranges)
        suspicious_patterns = []
        if iccid == "00000000000000000000":
            suspicious_patterns.append("All zeros - likely test or placeholder")
        if iccid == "12345678901234567890":
            suspicious_patterns.append("Sequential digits - likely test or demo")
        if len(set(iccid)) <= 3:
            suspicious_patterns.append("Limited digit variety - potentially artificial/test ICCID")
        if iccid.startswith("898600"):  # Example: China test SIMs
            suspicious_patterns.append("Prefix 898600 - known test SIM range (China)")
        # Add more as needed
        for pattern in suspicious_patterns:
            validation_notes.append(f"⚠️  Suspicious pattern: {pattern}")
            educational_notes.append(f"Pattern detected: {pattern}. Test/placeholder ICCIDs are common in device manufacturing, QA, and training environments.")
        
        # Educational context
        educational_notes.append("ICCID uniquely identifies a SIM card globally. It is critical for SIM provisioning, activation, and forensic chain-of-custody.")
        educational_notes.append("Forensic best practice: Always cross-reference ICCID with carrier records and device IMEI for evidence integrity.")
        
        # Generate interpretation
        interpretation = {
            "summary": f"ICCID from {components['country_code']['country']} issued by {components['issuer_identifier']['operator']}",
            "geographic_origin": components["country_code"]["country"],
            "region": components["country_code"]["region"],
            "suspected_operator": components["issuer_identifier"]["operator"],
            "integrity_status": "VALID" if components["check_digit"]["valid"] else "INVALID",
            "forensic_confidence": "HIGH" if (
                components["mii"]["value"] == "89" and 
                components["country_code"]["country"] != "Unknown" and
                components["check_digit"]["valid"]
            ) else "MEDIUM" if components["check_digit"]["valid"] else "LOW",
            "educational_notes": educational_notes,
            "references": references
        }
        
        analysis_result = {
            "input": iccid,
            "type": "ICCID",
            "session_id": self.session_id,
            "analysis_timestamp": datetime.now().isoformat(),
            "components": components,
            "interpretation": interpretation,
            "validation_notes": validation_notes
        }
        
        self.logger.info(f"ICCID analysis completed: {iccid} - Confidence: {interpretation['forensic_confidence']}")
        
        # Store result for reporting
        self.analysis_results.append(analysis_result)
        
        return analysis_result
    
    def _get_mcc_database(self) -> Dict[str, Dict[str, str]]:
        """
        Get comprehensive Mobile Country Code database (ITU-T E.212 based).
        
        Returns:
            Dict[str, Dict[str, str]]: MCC mappings with country information
            
        Forensic Purpose:
            Provides authoritative Mobile Country Code mappings for identifying
            subscriber's home country. Critical for determining jurisdiction,
            roaming patterns, and cross-border investigations.
        """
        return {
            # Europe
            "234": {"country": "United Kingdom", "region": "Europe", "iso": "GB"},
            "235": {"country": "United Kingdom", "region": "Europe", "iso": "GB"},
            "262": {"country": "Germany", "region": "Europe", "iso": "DE"},
            "208": {"country": "France", "region": "Europe", "iso": "FR"},
            "222": {"country": "Italy", "region": "Europe", "iso": "IT"},
            "214": {"country": "Spain", "region": "Europe", "iso": "ES"},
            "204": {"country": "Netherlands", "region": "Europe", "iso": "NL"},
            "240": {"country": "Sweden", "region": "Europe", "iso": "SE"},
            "242": {"country": "Norway", "region": "Europe", "iso": "NO"},
            "238": {"country": "Denmark", "region": "Europe", "iso": "DK"},
            "228": {"country": "Switzerland", "region": "Europe", "iso": "CH"},
            "232": {"country": "Austria", "region": "Europe", "iso": "AT"},
            "206": {"country": "Belgium", "region": "Europe", "iso": "BE"},
            "244": {"country": "Finland", "region": "Europe", "iso": "FI"},
            "272": {"country": "Ireland", "region": "Europe", "iso": "IE"},
            "202": {"country": "Greece", "region": "Europe", "iso": "GR"},
            "268": {"country": "Portugal", "region": "Europe", "iso": "PT"},
            
            # North America
            "310": {"country": "United States", "region": "North America", "iso": "US"},
            "311": {"country": "United States", "region": "North America", "iso": "US"},
            "312": {"country": "United States", "region": "North America", "iso": "US"},
            "313": {"country": "United States", "region": "North America", "iso": "US"},
            "314": {"country": "United States", "region": "North America", "iso": "US"},
            "315": {"country": "United States", "region": "North America", "iso": "US"},
            "316": {"country": "United States", "region": "North America", "iso": "US"},
            "302": {"country": "Canada", "region": "North America", "iso": "CA"},
            "334": {"country": "Mexico", "region": "North America", "iso": "MX"},
            
            # Asia Pacific
            "440": {"country": "Japan", "region": "Asia Pacific", "iso": "JP"},
            "441": {"country": "Japan", "region": "Asia Pacific", "iso": "JP"},
            "460": {"country": "China", "region": "Asia Pacific", "iso": "CN"},
            "461": {"country": "China", "region": "Asia Pacific", "iso": "CN"},
            "450": {"country": "South Korea", "region": "Asia Pacific", "iso": "KR"},
            "525": {"country": "Singapore", "region": "Asia Pacific", "iso": "SG"},
            "505": {"country": "Australia", "region": "Asia Pacific", "iso": "AU"},
            "530": {"country": "New Zealand", "region": "Asia Pacific", "iso": "NZ"},
            "404": {"country": "India", "region": "Asia Pacific", "iso": "IN"},
            "405": {"country": "India", "region": "Asia Pacific", "iso": "IN"},
            "520": {"country": "Thailand", "region": "Asia Pacific", "iso": "TH"},
            "510": {"country": "Indonesia", "region": "Asia Pacific", "iso": "ID"},
            "502": {"country": "Malaysia", "region": "Asia Pacific", "iso": "MY"},
            
            # Other regions
            "250": {"country": "Russia", "region": "Europe/Asia", "iso": "RU"},
            "724": {"country": "Brazil", "region": "South America", "iso": "BR"},
            "655": {"country": "South Africa", "region": "Africa", "iso": "ZA"},
            "602": {"country": "Egypt", "region": "Africa/Middle East", "iso": "EG"},
            "420": {"country": "Saudi Arabia", "region": "Middle East", "iso": "SA"},
            "424": {"country": "United Arab Emirates", "region": "Middle East", "iso": "AE"},
            
            # Test networks (important for forensic analysis)
            "001": {"country": "Test Network", "region": "Test", "iso": "TEST"},
        }
    
    def _get_mnc_database(self) -> Dict[str, Dict[str, Dict[str, str]]]:
        """
        Get comprehensive Mobile Network Code database for operator identification.
        
        Returns:
            Dict[str, Dict[str, Dict[str, str]]]: MNC mappings by country code
            
        Forensic Purpose:
            Enables precise identification of mobile network operators within
            each country. Critical for determining carrier relationships,
            roaming agreements, and network-specific investigation procedures.
        """
        return {
            # United Kingdom (234)
            "234": {
                "10": {"operator": "O2 UK", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "11": {"operator": "O2 UK", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "30": {"operator": "EE", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "31": {"operator": "EE", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "32": {"operator": "EE", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "33": {"operator": "EE", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "34": {"operator": "EE", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "15": {"operator": "Vodafone UK", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "91": {"operator": "Vodafone UK", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "20": {"operator": "Three UK", "type": "MNO", "network": "UMTS/LTE"},
                "50": {"operator": "JT (Jersey)", "type": "Regional", "network": "GSM/UMTS/LTE"},
                "55": {"operator": "Sure (Guernsey)", "type": "Regional", "network": "GSM/UMTS/LTE"},
                "58": {"operator": "Manx Telecom", "type": "Regional", "network": "GSM/UMTS/LTE"},
                "03": {"operator": "Airtel-Vodafone", "type": "MVNO", "network": "GSM/UMTS/LTE"},
                "07": {"operator": "Truphone", "type": "MVNO", "network": "GSM/UMTS/LTE"},
                "76": {"operator": "BT Mobile", "type": "MVNO", "network": "GSM/UMTS/LTE"},
                "78": {"operator": "Airwave (Emergency Services)", "type": "PMR", "network": "TETRA"},
            },
            
            # United Kingdom (235) - Additional allocations
            "235": {
                "00": {"operator": "BT", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "01": {"operator": "EE", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "02": {"operator": "EE", "type": "MNO", "network": "GSM/UMTS/LTE"},
            },
            
            # United States (310)
            "310": {
                "030": {"operator": "AT&T", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "070": {"operator": "AT&T", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "150": {"operator": "AT&T", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "260": {"operator": "T-Mobile USA", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "410": {"operator": "T-Mobile USA", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "004": {"operator": "Verizon", "type": "MNO", "network": "CDMA/LTE"},
                "012": {"operator": "Verizon", "type": "MNO", "network": "CDMA/LTE"},
                "120": {"operator": "Sprint", "type": "MNO", "network": "CDMA/LTE"},
                "000": {"operator": "Dish Network", "type": "MNO", "network": "LTE"},
            },
            
            # Germany (262)
            "262": {
                "01": {"operator": "T-Mobile Germany", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "02": {"operator": "Vodafone Germany", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "03": {"operator": "E-Plus", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "07": {"operator": "O2 Germany", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "08": {"operator": "O2 Germany", "type": "MNO", "network": "GSM/UMTS/LTE"},
            },
            
            # France (208)
            "208": {
                "01": {"operator": "Orange France", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "02": {"operator": "Orange France", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "10": {"operator": "SFR", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "20": {"operator": "Bouygues Telecom", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "15": {"operator": "Free Mobile", "type": "MNO", "network": "UMTS/LTE"},
            },
            
            # Japan (440)
            "440": {
                "10": {"operator": "NTT DoCoMo", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "20": {"operator": "SoftBank", "type": "MNO", "network": "GSM/UMTS/LTE"},
                "50": {"operator": "KDDI", "type": "MNO", "network": "CDMA/LTE"},
            },
            
            # Test Network (001)
            "001": {
                "01": {"operator": "Test Network 1", "type": "Test", "network": "Test"},
                "02": {"operator": "Test Network 2", "type": "Test", "network": "Test"},
            }
        }
    
    def _identify_mvno_patterns(self, mcc: str, mnc: str, operator: str) -> Dict[str, Any]:
        """
        Identify MVNO patterns and relationships with parent networks.
        
        Args:
            mcc (str): Mobile Country Code
            mnc (str): Mobile Network Code
            operator (str): Identified operator name
            
        Returns:
            Dict[str, Any]: MVNO analysis results
            
        Forensic Purpose:
            Distinguishes between Mobile Virtual Network Operators (MVNOs)
            and primary network operators. Critical for understanding actual
            network infrastructure and carrier relationships in investigations.
        """
        mvno_info = {
            "is_mvno": False,
            "parent_network": None,
            "mvno_type": None,
            "investigation_notes": []
        }
        
        # UK MVNO patterns
        if mcc == "234":
            mvno_patterns = {
                "03": {"parent": "Vodafone UK", "type": "Full MVNO"},
                "07": {"parent": "O2 UK/EE", "type": "Global MVNO"},
                "76": {"parent": "EE", "type": "Corporate MVNO"},
            }
            
            if mnc in mvno_patterns:
                mvno_info["is_mvno"] = True
                mvno_info["parent_network"] = mvno_patterns[mnc]["parent"]
                mvno_info["mvno_type"] = mvno_patterns[mnc]["type"]
                mvno_info["investigation_notes"].append(
                    f"MVNO using {mvno_patterns[mnc]['parent']} infrastructure"
                )
        
        # Common MVNO indicators by operator name patterns
        mvno_indicators = ["virtual", "mobile virtual", "mvno", "reseller"]
        if any(indicator in operator.lower() for indicator in mvno_indicators):
            mvno_info["is_mvno"] = True
            mvno_info["investigation_notes"].append("Operator name suggests MVNO")
        
        return mvno_info
    
    def _check_test_imsi_patterns(self, imsi: str) -> Dict[str, Any]:
        """
        Check for test IMSI patterns and special ranges.
        
        Args:
            imsi (str): Clean IMSI to check
            
        Returns:
            Dict[str, Any]: Test pattern analysis
            
        Forensic Purpose:
            Identifies test IMSIs, special ranges, and potentially
            suspicious patterns. Critical for distinguishing legitimate
            subscriber identities from test/development identifiers.
        """
        test_info = {
            "is_test_imsi": False,
            "test_type": None,
            "suspicious_patterns": [],
            "forensic_flags": []
        }
        
        # Test network MCC
        if imsi.startswith("001"):
            test_info["is_test_imsi"] = True
            test_info["test_type"] = "ITU-T Test Network"
            test_info["forensic_flags"].append("Official test network - not a real subscriber")
        
        # Common test patterns
        test_patterns = [
            ("000000000000000", "All zeros - likely test"),
            ("111111111111111", "All ones - likely test"),
            ("123456789012345", "Sequential digits - likely test"),
            ("999999999999999", "All nines - likely test")
        ]
        
        for pattern, description in test_patterns:
            if pattern in imsi:
                test_info["suspicious_patterns"].append(description)
        
        # Check for repeated patterns
        if len(set(imsi)) <= 3:  # Only 3 or fewer unique digits
            test_info["suspicious_patterns"].append("Limited digit variety - potentially artificial")
        
        # Check for impossible or reserved ranges
        mcc = imsi[:3]
        if mcc in ["000", "999"]:
            test_info["forensic_flags"].append(f"Reserved/invalid MCC: {mcc}")
        
        return test_info
    
    def _parse_imsi_components(self, imsi: str) -> Dict[str, Any]:
        """
        Parse IMSI into its component parts with comprehensive analysis.
        
        Args:
            imsi (str): Clean IMSI number to parse
            
        Returns:
            Dict[str, Any]: Detailed component breakdown
            
        Forensic Purpose:
            Systematically breaks down IMSI structure to extract all
            investigatively relevant information including geographic origin,
            network operator, and subscriber identification.
        """
        clean_imsi = imsi.replace(" ", "").replace("-", "")
        components = {}
        
        # Mobile Country Code (MCC) - First 3 digits
        mcc = clean_imsi[:3]
        mcc_db = self._get_mcc_database()
        mcc_info = mcc_db.get(mcc, {"country": "Unknown", "region": "Unknown", "iso": "UNK"})
        
        components["mcc"] = {
            "value": mcc,
            "description": "Mobile Country Code",
            "country": mcc_info["country"],
            "region": mcc_info["region"],
            "iso_code": mcc_info["iso"]
        }
        
        # Mobile Network Code (MNC) - Next 2-3 digits (variable length)
        mnc_db = self._get_mnc_database()
        country_mncs = mnc_db.get(mcc, {})
        
        # Try 3-digit MNC first, then 2-digit
        mnc = ""
        mnc_info = {"operator": "Unknown", "type": "Unknown", "network": "Unknown"}
        
        if len(clean_imsi) >= 6:  # Try 3-digit MNC
            test_mnc = clean_imsi[3:6]
            if test_mnc in country_mncs:
                mnc = test_mnc
                mnc_info = country_mncs[test_mnc]
        
        if not mnc and len(clean_imsi) >= 5:  # Try 2-digit MNC
            test_mnc = clean_imsi[3:5]
            if test_mnc in country_mncs:
                mnc = test_mnc
                mnc_info = country_mncs[test_mnc]
        
        # If still no match, assume 2-digit MNC as default
        if not mnc:
            mnc = clean_imsi[3:5] if len(clean_imsi) >= 5 else ""
        
        components["mnc"] = {
            "value": mnc,
            "description": "Mobile Network Code",
            "operator": mnc_info["operator"],
            "operator_type": mnc_info["type"],
            "network_technology": mnc_info["network"]
        }
        
        # Mobile Subscriber Identification Number (MSIN) - Remaining digits
        msin_start = 3 + len(mnc)
        msin = clean_imsi[msin_start:] if len(clean_imsi) > msin_start else ""
        
        components["msin"] = {
            "value": msin,
            "description": "Mobile Subscriber Identification Number",
            "length": len(msin),
            "purpose": "Unique subscriber identifier within the network"
        }
        
        # MVNO Analysis
        components["mvno_analysis"] = self._identify_mvno_patterns(
            mcc, mnc, mnc_info["operator"]
        )
        
        # Test pattern analysis
        components["test_analysis"] = self._check_test_imsi_patterns(clean_imsi)
        
        return components
    
    def analyze_imsi(self, imsi: str) -> Dict[str, Any]:
        """
        Analyze IMSI and break down into component parts with comprehensive forensic analysis.
        
        Args:
            imsi (str): IMSI number to analyze
            
        Returns:
            Dict[str, Any]: Analysis results with component breakdown
            
        Forensic Purpose:
            Breaks down IMSI into forensically relevant components:
            - Mobile Country Code (MCC) for geographic origin
            - Mobile Network Code (MNC) for operator identification
            - Mobile Subscriber Identification Number (MSIN) for subscriber ID
            - MVNO analysis for network infrastructure understanding
            - Test pattern detection for authenticity assessment
            - Detects suspicious/test patterns and provides educational notes
        """
        self.analysis_count += 1
        self.logger.info(f"Starting IMSI analysis #{self.analysis_count}: {imsi}")
        
        if not self.validate_imsi(imsi):
            raise ValueError("Invalid IMSI format")
        
        # Parse IMSI components
        components = self._parse_imsi_components(imsi)
        
        # Generate validation notes
        validation_notes = []
        educational_notes = []
        references = [
            "ITU-T E.212: IMSI structure and allocation (https://www.itu.int/rec/T-REC-E.212/en)",
            "GSMA Official MCC/MNC Database (https://www.gsma.com/)",
        ]
        
        # Check MCC recognition
        if components["mcc"]["country"] == "Unknown":
            validation_notes.append("⚠️  Unrecognized Mobile Country Code")
            educational_notes.append("MCC not found in ITU/GSMA databases. This may indicate a test IMSI, a new allocation, or a data entry error. Cross-check with official sources.")
        else:
            validation_notes.append(f"✅ Valid MCC: {components['mcc']['country']}")
        
        # Check operator identification
        if components["mnc"]["operator"] == "Unknown":
            validation_notes.append("ℹ️  Operator not identified in database")
            educational_notes.append("Operator code not found in GSMA/ITU databases. For further research, consult the GSMA online lookup or contact the suspected carrier. See: https://www.gsma.com/ for operator lists.")
        else:
            validation_notes.append(f"✅ Operator identified: {components['mnc']['operator']}")
        
        # MVNO analysis notes
        mvno = components["mvno_analysis"]
        if mvno["is_mvno"]:
            validation_notes.append(f"📡 MVNO detected: {mvno['mvno_type']}")
            if mvno["parent_network"]:
                validation_notes.append(f"🔗 Parent network: {mvno['parent_network']}")
            educational_notes.append("MVNOs (Mobile Virtual Network Operators) lease infrastructure from main carriers. For forensics, always determine the actual network provider.")
        
        # Test IMSI warnings
        test_analysis = components["test_analysis"]
        if test_analysis["is_test_imsi"]:
            validation_notes.append(f"⚠️  Test IMSI Detected: {test_analysis['test_type']}")
            educational_notes.append("Test IMSIs are used in device manufacturing, QA, and network testing. They do not represent real subscribers and should not be used as evidence of user activity.")
        for flag in test_analysis["forensic_flags"]:
            validation_notes.append(f"🚩 {flag}")
            educational_notes.append(f"Forensic flag: {flag}. Reserved or invalid MCCs are not assigned to real networks.")
        for pattern in test_analysis["suspicious_patterns"]:
            validation_notes.append(f"⚠️  Suspicious pattern: {pattern}")
            educational_notes.append(f"Pattern detected: {pattern}. Test/placeholder IMSIs are common in device manufacturing, QA, and training environments.")
        
        # Check MSIN length
        msin_length = components["msin"]["length"]
        if msin_length < 9:
            validation_notes.append(f"⚠️  Short MSIN length: {msin_length} digits")
            educational_notes.append("Short MSINs are rare and may indicate a test or non-standard IMSI.")
        elif msin_length > 10:
            validation_notes.append(f"⚠️  Long MSIN length: {msin_length} digits")
            educational_notes.append("Long MSINs are rare and may indicate a test or non-standard IMSI.")
        
        # Educational context
        educational_notes.append("IMSI uniquely identifies a mobile subscriber globally. It is critical for subscriber authentication, network access, and forensic attribution.")
        educational_notes.append("Forensic best practice: Always cross-reference IMSI with carrier records and device IMEI for evidence integrity.")
        
        # Generate interpretation
        interpretation = {
            "summary": f"IMSI from {components['mcc']['country']} on {components['mnc']['operator']} network",
            "geographic_origin": components["mcc"]["country"],
            "region": components["mcc"]["region"],
            "home_network": components["mnc"]["operator"],
            "network_type": components["mnc"]["network_technology"],
            "subscriber_category": "MVNO Subscriber" if mvno["is_mvno"] else "Direct Network Subscriber",
            "forensic_confidence": self._calculate_imsi_confidence(components),
            "investigation_significance": self._generate_investigation_notes(components),
            "educational_notes": educational_notes,
            "references": references
        }
        
        analysis_result = {
            "input": imsi,
            "type": "IMSI",
            "session_id": self.session_id,
            "analysis_timestamp": datetime.now().isoformat(),
            "components": components,
            "interpretation": interpretation,
            "validation_notes": validation_notes
        }
        
        self.logger.info(f"IMSI analysis completed: {imsi} - Confidence: {interpretation['forensic_confidence']}")
        
        # Store result for reporting
        self.analysis_results.append(analysis_result)
        
        return analysis_result
    
    def _calculate_imsi_confidence(self, components: Dict[str, Any]) -> str:
        """Calculate forensic confidence level for IMSI analysis."""
        confidence_score = 0
        
        # MCC recognition
        if components["mcc"]["country"] != "Unknown":
            confidence_score += 3
        
        # MNC recognition  
        if components["mnc"]["operator"] != "Unknown":
            confidence_score += 3
        
        # Valid MSIN length
        msin_len = components["msin"]["length"]
        if 9 <= msin_len <= 10:
            confidence_score += 2
        
        # No test patterns
        if not components["test_analysis"]["is_test_imsi"] and not components["test_analysis"]["suspicious_patterns"]:
            confidence_score += 2
        
        if confidence_score >= 8:
            return "HIGH"
        elif confidence_score >= 5:
            return "MEDIUM"
        else:
            return "LOW"
    
    def _generate_investigation_notes(self, components: Dict[str, Any]) -> List[str]:
        """Generate investigative significance notes for IMSI analysis."""
        notes = []
        
        # Geographic significance
        country = components["mcc"]["country"]
        if country != "Unknown":
            notes.append(f"Subscriber registered in {country}")
        
        # Network significance
        operator = components["mnc"]["operator"]
        if operator != "Unknown":
            notes.append(f"Home network operator: {operator}")
        
        # MVNO implications
        if components["mvno_analysis"]["is_mvno"]:
            notes.append("Virtual operator - actual network infrastructure may differ")
        
        # Technology implications
        network_tech = components["mnc"]["network_technology"]
        if "LTE" in network_tech:
            notes.append("Modern network technology - supports advanced data services")
        elif "GSM" in network_tech and "UMTS" not in network_tech:
            notes.append("Older network technology - limited data capabilities")
        
        return notes
    
    def get_session_summary(self) -> Dict[str, Any]:
        """
        Generate comprehensive session summary for forensic reporting.
        
        Returns:
            Dict[str, Any]: Session statistics and summary information
            
        Forensic Purpose:
            Provides audit trail summary including session duration,
            number of analyses performed, and other metadata useful
            for forensic documentation and case reporting.
        """
        session_duration = datetime.now() - self.session_start
        
        summary = {
            "session_id": self.session_id,
            "start_time": self.session_start.isoformat(),
            "end_time": datetime.now().isoformat(),
            "duration_seconds": session_duration.total_seconds(),
            "analyses_performed": self.analysis_count,
            "tool_version": "1.0.0"
        }
        
        self.logger.info(f"Session summary generated: {summary}")
        return summary
    
    def generate_professional_report(self, report_type: str = "console", 
                                   export_to_file: bool = False,
                                   cross_validate: bool = False) -> Optional[str]:
        """
        Generate professional forensic reports using the integrated reporting system.
        
        Args:
            report_type (str): Type of report ("console", "detailed", "csv", "all")
            export_to_file (bool): Whether to export reports to files
            cross_validate (bool): Whether to perform cross-validation
            
        Returns:
            Optional[str]: Report content or file path if exported
            
        Forensic Purpose:
            Provides comprehensive reporting capabilities for forensic documentation.
            Supports multiple formats and cross-validation for thorough analysis.
        """
        if not self.analysis_results:
            self.logger.warning("No analysis results available for reporting")
            return None
        
        cross_validation = None
        if cross_validate and len(self.analysis_results) >= 2:
            # Find ICCID and IMSI results for cross-validation
            iccid_result = next((r for r in self.analysis_results if r['type'] == 'ICCID'), None)
            imsi_result = next((r for r in self.analysis_results if r['type'] == 'IMSI'), None)
            
            if iccid_result and imsi_result:
                cross_validation = self.report_generator.cross_validate_identifiers(
                    iccid_result, imsi_result
                )
                self.logger.info("Cross-validation performed between ICCID and IMSI")
        
        if report_type == "console":
            report_content = self.report_generator.generate_console_summary(
                self.analysis_results, cross_validation
            )
            if not self.quiet_mode:
                print(report_content)
            return report_content
        
        elif report_type == "detailed":
            report_content = self.report_generator.generate_detailed_report(
                self.analysis_results, cross_validation
            )
            
            if export_to_file:
                timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
                filename = f"forensic_analysis_{timestamp}_{self.session_id[:8]}.txt"
                filepath = self.report_generator.export_to_file(
                    report_content, filename, "Detailed Analysis"
                )
                if not self.quiet_mode:
                    print(f"Detailed report exported to: {filepath}")
                return filepath
            else:
                if not self.quiet_mode:
                    print(report_content)
                return report_content
        
        elif report_type == "csv":
            filepath = self.report_generator.export_to_csv(
                self.analysis_results, cross_validation
            )
            if not self.quiet_mode:
                print(f"CSV report exported to: {filepath}")
            return filepath
        
        elif report_type == "all":
            # Generate all report types
            results = {}
            
            # Console summary
            console_content = self.report_generator.generate_console_summary(
                self.analysis_results, cross_validation
            )
            if not self.quiet_mode:
                print(console_content)
            results["console"] = console_content
            
            # Detailed report
            detailed_content = self.report_generator.generate_detailed_report(
                self.analysis_results, cross_validation
            )
            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
            detailed_filename = f"forensic_analysis_{timestamp}_{self.session_id[:8]}.txt"
            detailed_filepath = self.report_generator.export_to_file(
                detailed_content, detailed_filename, "Detailed Analysis"
            )
            results["detailed"] = detailed_filepath
            
            # CSV export
            csv_filepath = self.report_generator.export_to_csv(
                self.analysis_results, cross_validation
            )
            results["csv"] = csv_filepath
            
            if not self.quiet_mode:
                print(f"\n📊 ALL REPORTS GENERATED:")
                print(f"   Detailed Report: {detailed_filepath}")
                print(f"   CSV Export: {csv_filepath}")
            
            return results
        
        else:
            self.logger.error(f"Unknown report type: {report_type}")
            return None
    
    def generate_session_report(self) -> str:
        """
        Generate comprehensive session summary report.
        
        Returns:
            str: Session summary report content or file path
            
        Forensic Purpose:
            Provides end-of-session summary suitable for case documentation
            and audit purposes. Includes statistics and file locations.
        """
        session_data = self.get_session_summary()
        session_report = self.report_generator.generate_session_summary(
            session_data, self.analysis_results
        )
        
        # Export to file
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        filename = f"session_summary_{timestamp}_{self.session_id[:8]}.txt"
        filepath = self.report_generator.export_to_file(
            session_report, filename, "Session Summary"
        )
        
        if not self.quiet_mode:
            print(session_report)
            print(f"\nSession summary exported to: {filepath}")
        
        return filepath
    
    def convert_iccid_formats(self, iccid: str) -> Dict[str, str]:
        """
        Convert ICCID to various formats used in forensic analysis.
        
        Args:
            iccid (str): ICCID number to convert
            
        Returns:
            Dict[str, str]: Dictionary of different ICCID formats
            
        Forensic Purpose:
            Provides multiple ICCID representations for cross-validation
            and forensic analysis. Different formats may be encountered
            in various systems, logs, or forensic artifacts.
        """
        if not self.validate_iccid(iccid):
            raise ValueError("Invalid ICCID format")
            
        clean_iccid = iccid.replace(" ", "").replace("-", "")
        
        # Convert to integer for hex conversion
        iccid_int = int(clean_iccid)
        
        # Decimal to hexadecimal
        hex_format = f"0x{iccid_int:X}"
        
        # BCD format (Binary Coded Decimal)
        bcd_format = " ".join(clean_iccid[i:i+2] for i in range(0, len(clean_iccid), 2))
        
        # Reversed nibble format (as stored on SIM cards)
        reversed_nibbles = []
        for i in range(0, len(clean_iccid), 2):
            if i + 1 < len(clean_iccid):
                reversed_nibbles.append(clean_iccid[i+1] + clean_iccid[i])
            else:
                reversed_nibbles.append("F" + clean_iccid[i])  # Pad with F if odd length
        sim_storage_format = " ".join(reversed_nibbles)
        
        # Raw bytes representation
        raw_bytes = []
        for i in range(0, len(clean_iccid), 2):
            if i + 1 < len(clean_iccid):
                byte = int(clean_iccid[i:i+2], 16)
                raw_bytes.append(f"{byte:02X}")
            else:
                byte = int(clean_iccid[i] + "F", 16)  # Pad with F if odd length
                raw_bytes.append(f"{byte:02X}")
        raw_bytes_format = " ".join(raw_bytes)
        
        return {
            "original_decimal": clean_iccid,
            "hexadecimal": hex_format,
            "bcd_format": bcd_format,
            "sim_storage": sim_storage_format,
            "raw_bytes": raw_bytes_format
        }
    
    def convert_imsi_formats(self, imsi: str) -> Dict[str, str]:
        """
        Convert IMSI to various formats used in forensic analysis.
        
        Args:
            imsi (str): IMSI number to convert
            
        Returns:
            Dict[str, str]: Dictionary of different IMSI formats
            
        Forensic Purpose:
            Provides multiple IMSI representations for cross-validation
            and forensic analysis. Different formats may be encountered
            in various systems, logs, or forensic artifacts.
        """
        if not self.validate_imsi(imsi):
            raise ValueError("Invalid IMSI format")
            
        clean_imsi = imsi.replace(" ", "").replace("-", "")
        
        # Convert to integer for hex conversion
        imsi_int = int(clean_imsi)
        
        # Decimal to hexadecimal
        hex_format = f"0x{imsi_int:X}"
        
        # BCD format (3GPP TS 23.003 standard)
        bcd_format = " ".join(clean_imsi[i:i+2] for i in range(0, len(clean_imsi), 2))
        
        # Network byte order representation
        network_bytes = []
        for i in range(0, len(clean_imsi), 2):
            if i + 1 < len(clean_imsi):
                byte = int(clean_imsi[i:i+2], 16)
                network_bytes.append(f"{byte:02X}")
            else:
                byte = int(clean_imsi[i] + "F", 16)  # Pad with F if odd length
                network_bytes.append(f"{byte:02X}")
        network_byte_order = " ".join(network_bytes)
        
        return {
            "original_decimal": clean_imsi,
            "hexadecimal": hex_format,
            "bcd_format": bcd_format,
            "network_byte_order": network_byte_order
        }
    
    def display_format_conversions(self, identifier: str, identifier_type: str = "auto") -> None:
        """
        Display format conversions for ICCID or IMSI in a professional format.
        
        Args:
            identifier (str): ICCID or IMSI to convert
            identifier_type (str): Type of identifier ("iccid", "imsi", or "auto")
            
        Forensic Purpose:
            Provides a clear, professional display of different format
            representations for forensic documentation and analysis.
        """
        if identifier_type == "auto":
            if self.validate_iccid(identifier):
                identifier_type = "iccid"
            elif self.validate_imsi(identifier):
                identifier_type = "imsi"
            else:
                raise ValueError("Invalid identifier format")
        
        print("\n" + "="*80)
        print(f"FORMAT CONVERSION UTILITIES - {identifier_type.upper()}")
        print("="*80)
        
        if identifier_type == "iccid":
            formats = self.convert_iccid_formats(identifier)
            print(f"\nICCID Format Conversions:")
            print(f"Original (Decimal): {formats['original_decimal']}")
            print(f"Hexadecimal: {formats['hexadecimal']}")
            print(f"BCD Encoding: {formats['bcd_format']}")
            print(f"SIM Storage (Swapped): {formats['sim_storage']}")
            print(f"Raw Bytes: {formats['raw_bytes']}")
            
            print("\nForensic Notes:")
            print("• BCD format is commonly used in SIM card storage")
            print("• Swapped nibbles are the actual format stored on SIM cards")
            print("• Raw bytes representation shows the actual binary data")
            print("• All formats should be cross-validated for consistency")
            
        else:  # IMSI
            formats = self.convert_imsi_formats(identifier)
            print(f"\nIMSI Format Conversions:")
            print(f"Original (Decimal): {formats['original_decimal']}")
            print(f"Hexadecimal: {formats['hexadecimal']}")
            print(f"BCD Format: {formats['bcd_format']}")
            print(f"Network Byte Order: {formats['network_byte_order']}")
            
            print("\nForensic Notes:")
            print("• BCD format follows 3GPP TS 23.003 standard")
            print("• Network byte order is used in signaling messages")
            print("• All formats should be cross-validated for consistency")
            print("• Format variations may indicate different system origins")
        
        print("\n" + "="*80)


class InteractiveInterface:
    """
    Interactive interface for SIM Card Data Decoder.
    
    Provides a user-friendly menu-driven interface for analyzing ICCIDs and IMSIs,
    with support for format conversion utilities and professional reporting.
    """
    
    def __init__(self, decoder: SIMCardDecoder):
        """Initialize the interactive interface with a decoder instance."""
        self.decoder = decoder
        self.session_stats = {
            'total_analyses': 0,
            'successful_analyses': 0,
            'failed_analyses': 0,
            'iccid_analyses': 0,
            'imsi_analyses': 0,
            'reports_generated': 0
        }
    
    def display_menu(self) -> None:
        """Display the main menu options."""
        print("\n" + "="*60)
        print("SIM CARD DATA DECODER - MAIN MENU")
        print("="*60)
        print("\n1. Analyze Single ICCID")
        print("2. Analyze Single IMSI")
        print("3. Batch Process File")
        print("4. Format Conversion Utilities")
        print("5. Generate Console Summary")
        print("6. Generate Detailed Report")
        print("7. Export CSV Report")
        print("8. Generate All Reports")
        print("9. Generate Session Summary")
        print("0. Exit")
        print("\n" + "="*60)
    
    def get_user_choice(self) -> int:
        """Get user's menu choice."""
        while True:
            try:
                choice = int(input("\nEnter your choice (0-9): "))
                if 0 <= choice <= 9:
                    return choice
                print("⚠️  Please enter a number between 0 and 9.")
            except ValueError:
                print("⚠️  Please enter a valid number.")
    
    def get_iccid_input(self) -> Optional[str]:
        """Get ICCID input from user."""
        while True:
            iccid = input("\nEnter ICCID (or press Enter to cancel): ").strip()
            if not iccid:
                return None
            if self.decoder.validate_iccid(iccid):
                return iccid
            print("⚠️  Invalid ICCID format. Please try again.")
    
    def get_imsi_input(self) -> Optional[str]:
        """Get IMSI input from user."""
        while True:
            imsi = input("\nEnter IMSI (or press Enter to cancel): ").strip()
            if not imsi:
                return None
            if self.decoder.validate_imsi(imsi):
                return imsi
            print("⚠️  Invalid IMSI format. Please try again.")
    
    def get_file_input(self) -> Optional[str]:
        """Get input file path from user."""
        while True:
            filepath = input("\nEnter file path (or press Enter to cancel): ").strip()
            if not filepath:
                return None
            if os.path.exists(filepath):
                return filepath
            print("⚠️  File not found. Please try again.")
    
    def display_analysis_options(self, result: Dict[str, Any]) -> None:
        """Display options for analyzing results."""
        print("\nAnalysis Options:")
        print("1. View Detailed Analysis")
        print("2. Convert Formats")
        print("3. Generate Report")
        print("0. Back to Main Menu")
        
        choice = self.get_user_choice()
        
        if choice == 1:
            if result['type'] == 'ICCID':
                _display_iccid_analysis(result)
            else:
                _display_imsi_analysis(result)
        
        elif choice == 2:
            self.decoder.display_format_conversions(result['input'], result['type'].lower())
        
        elif choice == 3:
            try:
                filepath = self.decoder.generate_professional_report(
                    report_type="detailed",
                    export_to_file=True
                )
                if filepath:
                    print(f"✅ Report generated: {filepath}")
                    self.session_stats['reports_generated'] += 1
            except Exception as e:
                print(f"❌ Error generating report: {e}")
    
    def run(self) -> None:
        """Run the interactive interface."""
        while True:
            self.display_menu()
            choice = self.get_user_choice()
            
            if choice == 0:
                print("\n👋 Thank you for using SIM Card Data Decoder!")
                break
            
            elif choice == 1:  # Analyze Single ICCID
                iccid = self.get_iccid_input()
                if iccid:
                    try:
                        print(f"\n🔄 Analyzing ICCID: {iccid}")
                        result = self.decoder.analyze_iccid(iccid)
                        self.session_stats['total_analyses'] += 1
                        self.session_stats['iccid_analyses'] += 1
                        self.session_stats['successful_analyses'] += 1
                        
                        # Display basic results
                        print(f"✅ Analysis complete!")
                        print(f"   Country: {result['components']['country_code']['country']}")
                        print(f"   Operator: {result['components']['issuer_identifier']['operator']}")
                        print(f"   Confidence: {result['interpretation']['forensic_confidence']}")
                        
                        self.display_analysis_options(result)
                        
                    except Exception as e:
                        print(f"❌ Analysis failed: {e}")
                        self.session_stats['total_analyses'] += 1
                        self.session_stats['failed_analyses'] += 1
            
            elif choice == 2:  # Analyze Single IMSI
                imsi = self.get_imsi_input()
                if imsi:
                    try:
                        print(f"\n🔄 Analyzing IMSI: {imsi}")
                        result = self.decoder.analyze_imsi(imsi)
                        self.session_stats['total_analyses'] += 1
                        self.session_stats['imsi_analyses'] += 1
                        self.session_stats['successful_analyses'] += 1
                        
                        # Display basic results
                        print(f"✅ Analysis complete!")
                        print(f"   Country: {result['components']['mcc']['country']}")
                        print(f"   Operator: {result['components']['mnc']['operator']}")
                        print(f"   Confidence: {result['interpretation']['forensic_confidence']}")
                        
                        self.display_analysis_options(result)
                        
                    except Exception as e:
                        print(f"❌ Analysis failed: {e}")
                        self.session_stats['total_analyses'] += 1
                        self.session_stats['failed_analyses'] += 1
            
            elif choice == 3:  # Batch Process File
                filepath = self.get_file_input()
                if filepath:
                    try:
                        print(f"\n🔄 Starting batch processing: {filepath}")
                        batch_processor = BatchProcessor(self.decoder)
                        batch_processor.process_file(filepath)
                        
                        # Update session stats
                        self.session_stats['total_analyses'] += batch_processor.batch_stats['total_processed']
                        self.session_stats['successful_analyses'] += batch_processor.batch_stats['successful_analyses']
                        self.session_stats['iccid_analyses'] += batch_processor.batch_stats['iccid_count']
                        self.session_stats['imsi_analyses'] += batch_processor.batch_stats['imsi_count']
                        self.session_stats['reports_generated'] += 2  # CSV and detailed report
                        
                    except Exception as e:
                        print(f"❌ Batch processing failed: {e}")
            
            elif choice == 4:  # Format Conversion Utilities
                print("\n📝 Format Conversion Utilities")
                print("1. Convert ICCID")
                print("2. Convert IMSI")
                print("0. Back to Main Menu")
                
                sub_choice = self.get_user_choice()
                
                if sub_choice == 1:  # Convert ICCID
                    iccid = self.get_iccid_input()
                    if iccid:
                        try:
                            self.decoder.display_format_conversions(iccid, "iccid")
                        except Exception as e:
                            print(f"❌ Conversion failed: {e}")
                
                elif sub_choice == 2:  # Convert IMSI
                    imsi = self.get_imsi_input()
                    if imsi:
                        try:
                            self.decoder.display_format_conversions(imsi, "imsi")
                        except Exception as e:
                            print(f"❌ Conversion failed: {e}")
            
            elif choice == 5:  # Generate Console Summary
                try:
                    summary = self.decoder.generate_professional_report(
                        report_type="console"
                    )
                    print(summary)
                except Exception as e:
                    print(f"❌ Error generating console summary: {e}")
            
            elif choice == 6:  # Generate Detailed Report
                try:
                    filepath = self.decoder.generate_professional_report(
                        report_type="detailed",
                        export_to_file=True
                    )
                    if filepath:
                        print(f"✅ Detailed report generated: {filepath}")
                        self.session_stats['reports_generated'] += 1
                except Exception as e:
                    print(f"❌ Error generating detailed report: {e}")
            
            elif choice == 7:  # Export CSV Report
                try:
                    filepath = self.decoder.generate_professional_report(
                        report_type="csv",
                        export_to_file=True
                    )
                    if filepath:
                        print(f"✅ CSV report generated: {filepath}")
                        self.session_stats['reports_generated'] += 1
                except Exception as e:
                    print(f"❌ Error generating CSV report: {e}")
            
            elif choice == 8:  # Generate All Reports
                try:
                    results = self.decoder.generate_professional_report(
                        report_type="all",
                        export_to_file=True
                    )
                    if results:
                        print(f"✅ All reports generated:")
                        for report_type, filepath in results.items():
                            print(f"   • {report_type}: {filepath}")
                        self.session_stats['reports_generated'] += len(results)
                except Exception as e:
                    print(f"❌ Error generating reports: {e}")
            
            elif choice == 9:  # Generate Session Summary
                try:
                    filepath = self.decoder.generate_professional_report(
                        report_type="session",
                        export_to_file=True
                    )
                    if filepath:
                        print(f"✅ Session summary generated: {filepath}")
                        self.session_stats['reports_generated'] += 1
                except Exception as e:
                    print(f"❌ Error generating session summary: {e}")


def create_argument_parser() -> argparse.ArgumentParser:
    """
    Create command-line argument parser for professional CLI interface.
    
    Returns:
        argparse.ArgumentParser: Configured argument parser
        
    Forensic Purpose:
        Provides standardized command-line interface for consistent operation
        in forensic workflows. Supports both interactive and batch processing
        modes for different investigation scenarios.
    """
    parser = argparse.ArgumentParser(
        description="Professional SIM Card Data Decoder for Digital Forensics",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  Basic Analysis:
    %(prog)s --iccid 89014103211118510720
    %(prog)s --imsi 310260123456789
    %(prog)s --batch input_file.txt

  Professional Reporting:
    %(prog)s --iccid 89014103211118510720 --report detailed --export
    %(prog)s --imsi 310260123456789 --report csv
    %(prog)s --iccid 89014103211118510720 --imsi 310260123456789 --cross-validate
    %(prog)s --iccid 89014103211118510720 --report all --export --session-summary

  Quiet Operations:
    %(prog)s --iccid 89014103211118510720 --quiet --report csv
    %(prog)s --imsi 310260123456789 --quiet --log-level ERROR --export

Forensic Note:
  All operations are logged for audit purposes. Log files are created in the
  'logs' directory and reports in the 'reports' directory with timestamps and
  session IDs for tracking. Professional reports include cross-validation,
  forensic recommendations, and detailed technical analysis.
        """
    )
    
    # Input options
    input_group = parser.add_mutually_exclusive_group(required=False)
    input_group.add_argument(
        '--iccid',
        type=str,
        help='Analyze a single ICCID number'
    )
    input_group.add_argument(
        '--imsi',
        type=str,
        help='Analyze a single IMSI number'
    )
    input_group.add_argument(
        '--batch',
        type=str,
        help='Process batch file containing multiple ICCIDs/IMSIs'
    )
    
    # Operational options
    parser.add_argument(
        '--quiet',
        action='store_true',
        help='Suppress non-essential output (errors still shown)'
    )
    parser.add_argument(
        '--log-level',
        choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
        default='INFO',
        help='Set logging level (default: INFO)'
    )
    parser.add_argument(
        '--interactive',
        action='store_true',
        help='Start interactive mode for multiple analyses'
    )
    
    # Professional reporting options
    parser.add_argument(
        '--report',
        choices=['console', 'detailed', 'csv', 'all'],
        default='console',
        help='Report type to generate (default: console)'
    )
    parser.add_argument(
        '--export',
        action='store_true',
        help='Export detailed reports to files'
    )
    parser.add_argument(
        '--cross-validate',
        action='store_true',
        help='Perform cross-validation between ICCID and IMSI (when both provided)'
    )
    parser.add_argument(
        '--session-summary',
        action='store_true',
        help='Generate session summary report at completion'
    )
    
    return parser


def main():
    """
    Main function for SIM Card Data Decoder tool with Professional Reporting.
    
    Forensic Purpose:
        Entry point for forensic tool operation with comprehensive reporting
        capabilities. Handles command-line arguments, initializes decoder with
        proper logging, manages analysis modes, and generates professional
        reports suitable for forensic documentation.
    """
    parser = create_argument_parser()
    args = parser.parse_args()
    
    # Initialize decoder with proper logging
    decoder = SIMCardDecoder(log_level=args.log_level, quiet_mode=args.quiet)
    
    # Display educational disclaimer
    decoder._display_disclaimer()
    
    try:
        if args.interactive:
            # Start interactive mode
            interface = InteractiveInterface(decoder)
            interface.run()
            return
        
        # Handle single ICCID analysis
        if args.iccid:
            result = decoder.analyze_iccid(args.iccid)
            if not args.quiet:
                print(f"\n✅ ICCID Analysis Complete:")
                print(f"   Country: {result['components']['country_code']['country']}")
                print(f"   Operator: {result['components']['issuer_identifier']['operator']}")
                print(f"   Confidence: {result['interpretation']['forensic_confidence']}")
        
        # Handle single IMSI analysis
        if args.imsi:
            result = decoder.analyze_imsi(args.imsi)
            if not args.quiet:
                print(f"\n✅ IMSI Analysis Complete:")
                print(f"   Country: {result['components']['mcc']['country']}")
                print(f"   Operator: {result['components']['mnc']['operator']}")
                print(f"   Confidence: {result['interpretation']['forensic_confidence']}")
        
        # Handle batch processing
        if args.batch:
            batch_processor = BatchProcessor(decoder)
            batch_processor.process_file(args.batch)
        
        # Generate reports if requested
        if args.report:
            report = decoder.generate_professional_report(
                report_type=args.report,
                export_to_file=args.export,
                cross_validate=args.cross_validate
            )
            if not args.quiet and report:
                print(report)
        
        # Generate session summary if requested
        if args.session_summary:
            summary = decoder.generate_session_report()
            if not args.quiet and summary:
                print(summary)
    
    except Exception as e:
        print(f"\n❌ Error: {str(e)}")
        sys.exit(1)

if __name__ == "__main__":
    main()