android-persistence 1.0.0__py3-none-any.whl

android_persistence/report_generator.py

@@ -0,0 +1,326 @@
+"""
+Report Generator - Generate comprehensive analysis reports in multiple formats.
+
+Generates detailed findings reports in JSON, PDF, and HTML formats with
+visualizations, statistics, and executive summaries.
+
+Author: Security Research Team
+License: Apache-2.0
+"""
+
+import json
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+from datetime import datetime
+from dataclasses import asdict
+
+try:
+    from reportlab.lib import colors
+    from reportlab.lib.pagesizes import letter, A4
+    from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak, Table, TableStyle
+    from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+    from reportlab.lib.units import inch
+except ImportError:
+    SimpleDocTemplate = None
+
+
+class ReportGenerator:
+    """
+    Generate comprehensive analysis reports.
+    
+    Supports multiple output formats:
+    - JSON: Machine-readable findings
+    - HTML: Interactive web-based reports
+    - PDF: Professional printable reports
+    
+    Example:
+        >>> generator = ReportGenerator()
+        >>> generator.generate_report(findings, "report.json")
+    """
+
+    def __init__(self, title: str = "Android Persistence Analysis Report"):
+        """
+        Initialize report generator.
+        
+        Args:
+            title: Report title
+        """
+        self.title = title
+        self.timestamp = datetime.now()
+        self.findings: List[Dict[str, Any]] = []
+
+    def add_findings(self, findings: List[Any]) -> None:
+        """
+        Add findings to report.
+        
+        Args:
+            findings: List of finding objects
+        """
+        for finding in findings:
+            if hasattr(finding, 'to_dict'):
+                self.findings.append(finding.to_dict())
+            elif isinstance(finding, dict):
+                self.findings.append(finding)
+
+    def generate_json_report(self, output_path: str) -> bool:
+        """
+        Generate JSON format report.
+        
+        Args:
+            output_path: Output file path
+            
+        Returns:
+            True if generation succeeded
+        """
+        try:
+            report_data = {
+                "title": self.title,
+                "timestamp": self.timestamp.isoformat(),
+                "total_findings": len(self.findings),
+                "findings": self.findings,
+                "statistics": self._calculate_statistics(),
+            }
+
+            with open(output_path, 'w') as f:
+                json.dump(report_data, f, indent=2, default=str)
+
+            print(f"JSON report generated: {output_path}")
+            return True
+        except Exception as e:
+            print(f"Error generating JSON report: {str(e)}")
+            return False
+
+    def generate_html_report(self, output_path: str) -> bool:
+        """
+        Generate HTML format report.
+        
+        Args:
+            output_path: Output file path
+            
+        Returns:
+            True if generation succeeded
+        """
+        try:
+            html_content = self._generate_html_content()
+
+            with open(output_path, 'w', encoding='utf-8') as f:
+                f.write(html_content)
+
+            print(f"HTML report generated: {output_path}")
+            return True
+        except Exception as e:
+            print(f"Error generating HTML report: {str(e)}")
+            return False
+
+    def generate_pdf_report(self, output_path: str) -> bool:
+        """
+        Generate PDF format report.
+        
+        Args:
+            output_path: Output file path
+            
+        Returns:
+            True if generation succeeded
+        """
+        if SimpleDocTemplate is None:
+            print("Error: reportlab not installed. Install with: pip install reportlab")
+            return False
+
+        try:
+            doc = SimpleDocTemplate(output_path, pagesize=letter)
+            story = []
+            styles = getSampleStyleSheet()
+
+            # Title
+            title_style = ParagraphStyle(
+                'CustomTitle',
+                parent=styles['Heading1'],
+                fontSize=24,
+                textColor=colors.HexColor('#FF0000'),
+                spaceAfter=30,
+            )
+            story.append(Paragraph(self.title, title_style))
+            story.append(Spacer(1, 0.3*inch))
+
+            # Summary
+            stats = self._calculate_statistics()
+            summary_text = f"""
+            <b>Report Generated:</b> {self.timestamp.strftime('%Y-%m-%d %H:%M:%S')}<br/>
+            <b>Total Findings:</b> {stats['total_findings']}<br/>
+            <b>Critical:</b> {stats['critical']} | 
+            <b>High:</b> {stats['high']} | 
+            <b>Medium:</b> {stats['medium']} | 
+            <b>Low:</b> {stats['low']}
+            """
+            story.append(Paragraph(summary_text, styles['Normal']))
+            story.append(Spacer(1, 0.3*inch))
+
+            # Findings table
+            if self.findings:
+                table_data = [['Type', 'Component', 'Severity', 'Confidence']]
+                for finding in self.findings[:20]:  # Limit to 20 per page
+                    table_data.append([
+                        finding.get('persistence_type', 'Unknown'),
+                        finding.get('component_name', 'N/A')[:20],
+                        finding.get('severity', 'N/A'),
+                        f"{finding.get('confidence', 0)}%",
+                    ])
+
+                table = Table(table_data)
+                table.setStyle(TableStyle([
+                    ('BACKGROUND', (0, 0), (-1, 0), colors.HexColor('#FF0000')),
+                    ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
+                    ('ALIGN', (0, 0), (-1, -1), 'CENTER'),
+                    ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
+                    ('FONTSIZE', (0, 0), (-1, 0), 12),
+                    ('BOTTOMPADDING', (0, 0), (-1, 0), 12),
+                    ('GRID', (0, 0), (-1, -1), 1, colors.black),
+                ]))
+                story.append(table)
+
+            doc.build(story)
+            print(f"PDF report generated: {output_path}")
+            return True
+        except Exception as e:
+            print(f"Error generating PDF report: {str(e)}")
+            return False
+
+    def _generate_html_content(self) -> str:
+        """Generate HTML report content."""
+        stats = self._calculate_statistics()
+        
+        severity_colors = {
+            'CRITICAL': '#FF0000',
+            'HIGH': '#FF6600',
+            'MEDIUM': '#FFCC00',
+            'LOW': '#00CC00',
+            'INFO': '#0066FF',
+        }
+
+        html = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="UTF-8">
+            <title>{self.title}</title>
+            <style>
+                body {{ font-family: Arial, sans-serif; margin: 20px; background-color: #f5f5f5; }}
+                .header {{ background-color: #333; color: white; padding: 20px; border-radius: 5px; }}
+                .summary {{ background-color: white; padding: 20px; margin: 20px 0; border-radius: 5px; box-shadow: 0 2px 5px rgba(0,0,0,0.1); }}
+                .stats {{ display: grid; grid-template-columns: repeat(4, 1fr); gap: 10px; margin: 20px 0; }}
+                .stat-box {{ background-color: white; padding: 20px; border-radius: 5px; text-align: center; border-left: 5px solid #333; }}
+                .finding {{ background-color: white; padding: 15px; margin: 10px 0; border-radius: 5px; border-left: 5px solid #999; }}
+                .critical {{ border-left-color: {severity_colors['CRITICAL']}; }}
+                .high {{ border-left-color: {severity_colors['HIGH']}; }}
+                .medium {{ border-left-color: {severity_colors['MEDIUM']}; }}
+                .low {{ border-left-color: {severity_colors['LOW']}; }}
+                .severity {{ display: inline-block; padding: 5px 10px; border-radius: 3px; font-weight: bold; color: white; }}
+                table {{ width: 100%; border-collapse: collapse; background-color: white; margin: 20px 0; }}
+                th, td {{ padding: 12px; text-align: left; border-bottom: 1px solid #ddd; }}
+                th {{ background-color: #333; color: white; }}
+                tr:hover {{ background-color: #f5f5f5; }}
+            </style>
+        </head>
+        <body>
+            <div class="header">
+                <h1>{self.title}</h1>
+                <p>Generated: {self.timestamp.strftime('%Y-%m-%d %H:%M:%S')}</p>
+            </div>
+            
+            <div class="summary">
+                <h2>Executive Summary</h2>
+                <p>This report presents findings from comprehensive Android APK persistence analysis.</p>
+            </div>
+            
+            <div class="stats">
+                <div class="stat-box">
+                    <h3>{stats['total_findings']}</h3>
+                    <p>Total Findings</p>
+                </div>
+                <div class="stat-box">
+                    <h3 style="color: {severity_colors['CRITICAL']}">{stats['critical']}</h3>
+                    <p>Critical</p>
+                </div>
+                <div class="stat-box">
+                    <h3 style="color: {severity_colors['HIGH']}">{stats['high']}</h3>
+                    <p>High</p>
+                </div>
+                <div class="stat-box">
+                    <h3 style="color: {severity_colors['MEDIUM']}">{stats['medium']}</h3>
+                    <p>Medium</p>
+                </div>
+            </div>
+            
+            <h2>Findings</h2>
+            <table>
+                <tr>
+                    <th>Type</th>
+                    <th>Component</th>
+                    <th>Severity</th>
+                    <th>Confidence</th>
+                    <th>Description</th>
+                </tr>
+        """
+
+        for finding in self.findings:
+            severity = finding.get('severity', 'UNKNOWN')
+            severity_class = severity.lower()
+            color = severity_colors.get(severity, '#999999')
+            
+            html += f"""
+                <tr>
+                    <td>{finding.get('persistence_type', 'Unknown')}</td>
+                    <td>{finding.get('component_name', 'N/A')}</td>
+                    <td><span class="severity" style="background-color: {color}">{severity}</span></td>
+                    <td>{finding.get('confidence', 0)}%</td>
+                    <td>{finding.get('description', 'N/A')[:100]}...</td>
+                </tr>
+            """
+
+        html += """
+            </table>
+            
+            <div class="summary">
+                <h2>Disclaimer</h2>
+                <p><strong>RESEARCH ONLY:</strong> This tool is designed for legitimate security research 
+                and defensive analysis only. Unauthorized analysis of applications without permission may 
+                violate laws and ethical standards. Use only on systems where you have proper authorization.</p>
+            </div>
+        </body>
+        </html>
+        """
+
+        return html
+
+    def _calculate_statistics(self) -> Dict[str, Any]:
+        """Calculate report statistics."""
+        stats = {
+            'total_findings': len(self.findings),
+            'critical': 0,
+            'high': 0,
+            'medium': 0,
+            'low': 0,
+            'info': 0,
+        }
+
+        for finding in self.findings:
+            severity = finding.get('severity', '').upper()
+            if severity in stats:
+                stats[severity] += 1
+
+        return stats
+
+    def print_summary(self) -> None:
+        """Print summary to console."""
+        stats = self._calculate_statistics()
+        print("\n" + "="*70)
+        print("REPORT SUMMARY")
+        print("="*70)
+        print(f"Title: {self.title}")
+        print(f"Generated: {self.timestamp.strftime('%Y-%m-%d %H:%M:%S')}")
+        print(f"\nTotal Findings: {stats['total_findings']}")
+        print(f"  Critical: {stats['critical']}")
+        print(f"  High: {stats['high']}")
+        print(f"  Medium: {stats['medium']}")
+        print(f"  Low: {stats['low']}")
+        print("="*70 + "\n")

android_persistence/utils/__init__.py

@@ -0,0 +1,3 @@
+"""
+Utility modules for Android persistence analysis.
+"""

android_persistence/utils/hex_analyzer.py

@@ -0,0 +1,162 @@
+"""
+Hex and Binary Analysis utilities for examining binary data from APK files.
+
+Provides utilities for analyzing binary data, including hex dumps, pattern matching,
+and binary format identification.
+
+Author: Security Research Team
+License: Apache-2.0
+"""
+
+import struct
+from typing import List, Tuple, Optional
+import re
+
+
+class HexAnalyzer:
+    """Utility class for hex and binary data analysis."""
+
+    @staticmethod
+    def hex_dump(data: bytes, width: int = 16) -> str:
+        """
+        Generate hex dump of binary data.
+        
+        Args:
+            data: Binary data to dump
+            width: Number of bytes per line
+            
+        Returns:
+            Formatted hex dump string
+        """
+        lines = []
+        for i in range(0, len(data), width):
+            chunk = data[i:i+width]
+            hex_part = ' '.join(f'{b:02x}' for b in chunk)
+            ascii_part = ''.join(chr(b) if 32 <= b < 127 else '.' for b in chunk)
+            lines.append(f'{i:08x}  {hex_part:<{width*3}}  {ascii_part}')
+        return '\n'.join(lines)
+
+    @staticmethod
+    def find_pattern(data: bytes, pattern: bytes, all_matches: bool = False) -> List[int]:
+        """
+        Find pattern in binary data.
+        
+        Args:
+            data: Data to search
+            pattern: Pattern to find
+            all_matches: If True, return all matches; if False, return first
+            
+        Returns:
+            List of offsets where pattern is found
+        """
+        matches = []
+        offset = 0
+        while True:
+            offset = data.find(pattern, offset)
+            if offset == -1:
+                break
+            matches.append(offset)
+            if not all_matches:
+                return matches
+            offset += 1
+        return matches
+
+    @staticmethod
+    def find_magic_bytes(data: bytes) -> List[Tuple[int, str, bytes]]:
+        """
+        Identify common file format magic bytes in data.
+        
+        Args:
+            data: Data to analyze
+            
+        Returns:
+            List of (offset, type, bytes) tuples
+        """
+        MAGIC_SIGNATURES = {
+            b'\x50\x4b\x03\x04': 'ZIP Archive',
+            b'\x50\x4b\x05\x06': 'ZIP End of Central Directory',
+            b'\x64\x65\x78\x0a': 'DEX File',
+            b'\x7fELF': 'ELF Binary',
+            b'\xca\xfe\xba\xbe': 'Java Class File',
+            b'\xff\xd8\xff': 'JPEG Image',
+            b'\x89PNG': 'PNG Image',
+            b'\x42\x4d': 'BMP Image',
+        }
+        
+        matches = []
+        for sig, name in MAGIC_SIGNATURES.items():
+            offset = data.find(sig)
+            if offset != -1:
+                matches.append((offset, name, sig))
+        
+        return sorted(matches, key=lambda x: x[0])
+
+    @staticmethod
+    def extract_strings(data: bytes, min_length: int = 4) -> List[str]:
+        """
+        Extract ASCII strings from binary data.
+        
+        Args:
+            data: Binary data
+            min_length: Minimum string length
+            
+        Returns:
+            List of extracted strings
+        """
+        strings = []
+        current = []
+        
+        for byte in data:
+            if 32 <= byte < 127:  # Printable ASCII
+                current.append(chr(byte))
+            else:
+                if len(current) >= min_length:
+                    strings.append(''.join(current))
+                current = []
+        
+        if len(current) >= min_length:
+            strings.append(''.join(current))
+        
+        return strings
+
+    @staticmethod
+    def find_regex_pattern(data: bytes, pattern: str) -> List[Tuple[int, bytes]]:
+        """
+        Find data matching regex pattern.
+        
+        Args:
+            data: Binary data
+            pattern: Regex pattern (will be applied to string representation)
+            
+        Returns:
+            List of (offset, match) tuples
+        """
+        matches = []
+        regex = re.compile(pattern.encode() if isinstance(pattern, str) else pattern)
+        
+        for match in regex.finditer(data):
+            matches.append((match.start(), match.group()))
+        
+        return matches
+
+    @staticmethod
+    def xor_analysis(data: bytes, key_size: int = 1) -> List[Tuple[int, bytes]]:
+        """
+        Perform XOR analysis on data for potential encryption/obfuscation.
+        
+        Args:
+            data: Data to analyze
+            key_size: Size of XOR key to try
+            
+        Returns:
+            List of (key, decrypted_sample) tuples
+        """
+        results = []
+        
+        if key_size == 1:
+            for key in range(256):
+                decrypted = bytes(b ^ key for b in data[:min(100, len(data))])
+                if decrypted.count(0) < len(decrypted) // 4:  # Not too many nulls
+                    results.append((bytes([key]), decrypted))
+        
+        return results[:10]  # Return top 10 results

android_persistence/utils/logger.py

@@ -0,0 +1,74 @@
+"""
+Logging utility module for consistent logging across the framework.
+
+Provides configured loggers with standard formatting and multiple output handlers.
+
+Author: Security Research Team
+License: Apache-2.0
+"""
+
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+class LoggerConfig:
+    """Configure and manage application logging."""
+
+    LOG_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    DEBUG_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - [%(filename)s:%(lineno)d] - %(message)s'
+
+    def __init__(self, log_dir: Optional[str] = None):
+        """
+        Initialize logger configuration.
+        
+        Args:
+            log_dir: Optional directory to store log files
+        """
+        self.log_dir = Path(log_dir) if log_dir else None
+        if self.log_dir:
+            self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_logger(
+        self,
+        name: str,
+        level: str = "INFO",
+        log_file: bool = False
+    ) -> logging.Logger:
+        """
+        Get configured logger.
+        
+        Args:
+            name: Logger name
+            level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+            log_file: Whether to also log to file
+            
+        Returns:
+            Configured logger instance
+        """
+        logger = logging.getLogger(name)
+        logger.setLevel(getattr(logging, level))
+
+        # Remove existing handlers to avoid duplicates
+        logger.handlers.clear()
+
+        # Console handler
+        console_handler = logging.StreamHandler(sys.stdout)
+        console_handler.setLevel(getattr(logging, level))
+        
+        formatter = logging.Formatter(
+            self.DEBUG_FORMAT if level == "DEBUG" else self.LOG_FORMAT
+        )
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+
+        # File handler (optional)
+        if log_file and self.log_dir:
+            file_path = self.log_dir / f"{name}.log"
+            file_handler = logging.FileHandler(file_path)
+            file_handler.setLevel(getattr(logging, level))
+            file_handler.setFormatter(formatter)
+            logger.addHandler(file_handler)
+
+        return logger