Add symbolication tools (thanks Claude)

Author: mszoek

tools/SYMBOLICATION.md

@@ -0,0 +1,381 @@
+# Symbolication and Crash Analysis Tools
+
+A comprehensive toolkit for analyzing and symbolicting crashes in ravynOS binaries.
+
+## Tools Overview
+
+### 1. `symbolicate.py` - Address to Symbol Mapping
+
+Maps crash addresses to symbols in compiled binaries.
+
+**Usage:**
+```bash
+# Single address
+./symbolicate.py /path/to/binary 0x1d9660
+
+# Multiple addresses
+./symbolicate.py /path/to/binary 0x1d9660 0x1d9700 0x1d9750
+
+# With register context
+./symbolicate.py /path/to/binary --rip 0x1d9660 --rax 0x8010000000000007
+
+# Stack trace
+./symbolicate.py /path/to/binary --stack-trace 0x1d9660,0x1d9700,0x1d9750
+
+# Search for symbols
+./symbolicate.py /path/to/binary --search syscall
+
+# JSON output
+./symbolicate.py /path/to/binary 0x1d9660 --json
+```
+
+**Features:**
+- Binary search through symbol table for fast lookup
+- Shows symbol name, section, and offset
+- Displays nearby symbols for context
+- Supports both exact and substring symbol search
+- JSON output for automation
+- Handles both global and local symbols
+
+**Example Output:**
+```
+=== Symbolication Results ===
+
+1. 0x1d9660 -> _exit (TEXT) +0x0 (entry point)
+   Size: 0x20 bytes
+   Offset: 0x0
+   Context: entry point
+   Nearby symbols:
+     0x1d9640 syscall_wrapper
+     0x1d9660 _exit <--
+     0x1d9680 exit_trampoline
+```
+
+### 2. `crash-analyzer.py` - Comprehensive Crash Analysis
+
+Analyzes crash dumps and classifies crash types with recommendations.
+
+**Usage:**
+```bash
+# Basic crash analysis with register state
+./crash-analyzer.py \
+  --binary /path/to/binary \
+  --rip 0x1d9660 \
+  --rax 0x8010000000000007
+
+# With full register context
+./crash-analyzer.py \
+  --binary /path/to/binary \
+  --rip 0x1d9660 \
+  --rax 0x8010000000000007 \
+  --rdi 0x000000010ffd0000 \
+  --rsi 0x0000000115337c7e \
+  --rdx 0x000000011534d833
+
+# With stack trace
+./crash-analyzer.py \
+  --binary /path/to/binary \
+  --rip 0x1d9660 \
+  --rax 0x8010000000000007 \
+  --stack-trace 0x1d9660,0x1d9700,0x1d9750
+
+# JSON output
+./crash-analyzer.py \
+  --binary /path/to/binary \
+  --rip 0x1d9660 \
+  --rax 0x8010000000000007 \
+  --json
+```
+
+**Crash Types Detected:**
+- **Invalid Pointer Dereference** - Bit 63 set or known error patterns
+- **Null Pointer Dereference** - RAX = 0x0
+- **Syscall Failure** - At syscall instruction
+- **Segmentation Fault** - Unaligned or invalid memory access
+- **Buffer Overflow** - Stack corruption patterns
+- **Use After Free** - Freed memory markers
+- **Unknown** - Insufficient information
+
+**Example Output:**
+```
+======================================================================
+  CRASH ANALYSIS REPORT
+======================================================================
+
+Crash Type: invalid_pointer_dereference
+Confidence: 95%
+
+Description:
+  RAX contains invalid pointer: 0x8010000000000007. Bit 63 set indicates 
+  kernel space or error marker.
+
+Affected Symbol: dyld::recursiveBind+0x45
+Crash Address (RIP): 0x1d9660
+
+RAX: 0x8010000000000007
+RDI: 0x000000010ffd0000
+
+Stack Trace (3 frames):
+  [0] 0x1d9660
+  [1] 0x1d9700
+  [2] 0x1d9750
+
+Recommendations:
+  1. Check dyld's binding/interposing state at this instruction
+  2. Verify no corrupted mach-o load commands
+  3. Review recursive dependency loading logic
+  4. Check for malformed or misinterpreted bind/lazy-bind records
+
+======================================================================
+```
+
+### 3. `analyze-launchd-crash.py` - launchd-Specific Analysis
+
+Specialized analyzer for launchd stub crashes, focusing on syscall entry points and exit paths.
+
+**Usage:**
+```bash
+# Analyze launchd crash
+./analyze-launchd-crash.py /path/to/launchd 0x1d9660
+
+# Analyze exit-related code paths
+./analyze-launchd-crash.py /path/to/launchd 0x1d9660 --analyze-exit
+
+# Verbose output
+./analyze-launchd-crash.py /path/to/launchd 0x1d9660 -v
+```
+
+**Features:**
+- Detects syscall instructions at crash location
+- Analyzes exit-related code paths
+- Shows disassembly context around crash
+- Identifies if crash is at binary entry point
+- Lists known syscall constants
+
+**Example Output:**
+```
+=== Launchd Crash Analysis ===
+
+RIP: 0x1d9660
+Entry Point: 0x1d9660
+  ⚠️  Crash at entry point (very early in execution)
+
+Syscall Entry: YES - syscall
+  This suggests a syscall instruction is at the crash location
+
+Disassembly around crash:
+
+0000000000001d50 <_start>:
+    1d50: 55                    push   %rbp
+    1d51: 48 89 e5              mov    %rsp,%rbp
+    ...
+    1d60: 0f 05                 syscall
+    1d62: ...
+```
+
+## Practical Examples
+
+### Example 1: Analyzing the launchd stub issue
+
+Given the crash at `0x1d9660` in the launchd stub which is the `syscall` instruction in `_exit`:
+
+```bash
+# First, symbolicate the address
+./symbolicate.py /nest/ravynos/BSD/sbin/launchd 0x1d9660
+
+# Then analyze the crash with register state
+./crash-analyzer.py \
+  --binary /nest/ravynos/BSD/sbin/launchd \
+  --rip 0x1d9660 \
+  --rax 0x2000001  # SYS_exit
+
+# Get detailed launchd-specific analysis
+./analyze-launchd-crash.py /nest/ravynos/BSD/sbin/launchd 0x1d9660 --analyze-exit
+```
+
+### Example 2: Analyzing dyld crash with full register state
+
+From CRASH_FIX_ANALYSIS.md:
+
+```bash
+./crash-analyzer.py \
+  --binary /nest/ravynos/Libraries/dyld/src/dyld \
+  --rip 0x00000001154ad2eb \
+  --rax 0x8010000000000007 \
+  --rdi 0x000000010ffd0000 \
+  --stack-trace 0x00000001154ad2eb,0x0000000115337c7e,0x000000011534d833,0x000000011534ac51
+```
+
+### Example 3: Searching for symbols
+
+Find all syscall-related symbols:
+
+```bash
+./symbolicate.py /path/to/binary --search syscall
+```
+
+Find all exit-related symbols:
+
+```bash
+./symbolicate.py /path/to/binary --search exit
+```
+
+## Building and Testing
+
+### Prerequisites
+
+The tools require standard Unix utilities:
+- `nm` - For symbol table extraction
+- `objdump` - For disassembly
+- `readelf` or `otool` - For binary headers
+- Python 3.6+
+
+Install on macOS:
+```bash
+brew install binutils
+```
+
+Install on Linux:
+```bash
+sudo apt-get install binutils
+```
+
+### Quick Test
+
+```bash
+# Test symbolicate on a system binary
+./symbolicate.py /bin/ls 0x100001000
+
+# Test on ravynOS launchd
+./symbolicate.py /nest/ravynos/BSD/sbin/launchd 0x1d9660
+```
+
+## Integration with Crash Analysis Workflow
+
+1. **Capture crash** - Kernel or crash reporter provides RIP, RAX, and stack trace
+2. **Locate binary** - Find the binary that crashed (often in /nest/ravynos/BSD/sbin/launchd or /nest/ravynos/Libraries/dyld/src/dyld)
+3. **Symbolicate** - Use `symbolicate.py` to map addresses to function names
+4. **Analyze** - Use `crash-analyzer.py` to classify the crash type
+5. **Investigate** - Use `analyze-launchd-crash.py` for launchd-specific patterns
+
+Example workflow script:
+
+```bash
+#!/bin/bash
+
+BINARY="$1"
+RIP="$2"
+RAX="$3"
+
+echo "=== Quick Crash Analysis ==="
+echo ""
+
+echo "Step 1: Symbolicate addresses"
+./symbolicate.py "$BINARY" "$RIP" --context 3
+echo ""
+
+echo "Step 2: Analyze crash"
+./crash-analyzer.py --binary "$BINARY" --rip "$RIP" --rax "$RAX"
+```
+
+## Output Formats
+
+### Human-Readable (Default)
+
+Formatted for terminal viewing with colors and indentation.
+
+### JSON Output
+
+All tools support `--json` for machine-readable output:
+
+```bash
+./symbolicate.py /path/to/binary 0x1d9660 --json
+./crash-analyzer.py --binary /path/to/binary --rip 0x1d9660 --json
+```
+
+JSON structure:
+```json
+{
+  "address": "0x1d9660",
+  "symbol": "_exit",
+  "section": "TEXT",
+  "offset": "0x0",
+  "context": "entry point"
+}
+```
+
+## Troubleshooting
+
+### "nm command not found"
+Install binutils:
+- macOS: `brew install binutils`
+- Linux: `sudo apt-get install binutils`
+
+### "No symbols found"
+Binary may be stripped. Use debug symbols if available:
+```bash
+./symbolicate.py /path/to/binary.dSYM/Contents/Resources/DWARF/binary 0x1d9660
+```
+
+### "Could not get disassembly"
+Ensure objdump is installed and binary is accessible.
+
+### Very slow on large binaries
+The tools cache symbols after first load. Subsequent queries are fast.
+
+## Advanced Usage
+
+### Analyzing multiple crashes
+
+Create a file `crashes.txt`:
+```
+0x1d9660 0x8010000000000007
+0x1d9700 0xdeadbeef
+0x1d9750 0x0000000115337c7e
+```
+
+Process all:
+```bash
+while read rip rax; do
+  ./crash-analyzer.py --binary /path/to/binary --rip "$rip" --rax "$rax"
+done < crashes.txt
+```
+
+### Integration with CI/CD
+
+Export as JSON for processing:
+```bash
+./crash-analyzer.py \
+  --binary /path/to/binary \
+  --rip "$RIP" \
+  --rax "$RAX" \
+  --json > crash_report.json
+```
+
+Parse the JSON in your CI pipeline to trigger alerts or create issues.
+
+## Known Limitations
+
+1. **Stripped binaries** - Requires debug symbols
+2. **ASLR** - Addresses must be relative to binary's load address
+3. **Indirect calls** - Can't determine exact target of indirect calls
+4. **Cross-binary analysis** - Each binary requires separate analysis
+
+## Contributing
+
+To add new crash pattern detection:
+
+1. Add pattern to `CrashAnalyzer.INVALID_POINTER_MARKERS` or implement new check
+2. Add test case in analysis
+3. Update this README with example
+
+## License
+
+Part of ravynOS project. See main LICENSE file.
+
+## See Also
+
+- CRASH_FIX_ANALYSIS.md - Detailed crash analysis from development
+- Kernel/xnu/bsd/kern/mach_loader.c - Binary loader implementation
+- Libraries/dyld/src/ - Dynamic linker source
+

tools/crash-analyzer.py

@@ -0,0 +1,481 @@
+#!/usr/bin/env python3
+"""
+Comprehensive Crash Analysis Toolkit for ravynOS
+
+Provides integrated analysis of crash dumps, including symbolication,
+register state analysis, and pattern matching against known issues.
+
+Usage:
+    ./crash-analyzer.py --rip 0x1d9660 --rax 0x8010000000000007 --binary /path/to/binary
+    ./crash-analyzer.py --crash-file crash.txt --binary /path/to/binary
+    ./crash-analyzer.py --dyld-crash --rip 0x1d9660 --stack-trace 0x...,0x...,0x...
+"""
+
+import sys
+import os
+import subprocess
+import re
+import argparse
+import json
+from dataclasses import dataclass, asdict
+from typing import List, Optional, Dict, Tuple
+from enum import Enum
+
+
+class CrashType(Enum):
+    """Classification of crash types"""
+    INVALID_POINTER = "invalid_pointer_dereference"
+    SYSCALL_FAILURE = "syscall_failure"
+    SEGMENT_VIOLATION = "segmentation_fault"
+    ALIGNMENT_FAULT = "alignment_fault"
+    NULL_POINTER = "null_pointer_dereference"
+    BUFFER_OVERFLOW = "buffer_overflow"
+    USE_AFTER_FREE = "use_after_free"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class CrashContext:
+    """Context information about a crash"""
+    rip: int
+    rax: Optional[int] = None
+    rdi: Optional[int] = None
+    rsi: Optional[int] = None
+    rdx: Optional[int] = None
+    stack_trace: List[int] = None
+
+    def __post_init__(self):
+        if self.stack_trace is None:
+            self.stack_trace = []
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        return {
+            'rip': hex(self.rip),
+            'rax': hex(self.rax) if self.rax else None,
+            'rdi': hex(self.rdi) if self.rdi else None,
+            'rsi': hex(self.rsi) if self.rsi else None,
+            'rdx': hex(self.rdx) if self.rdx else None,
+            'stack_trace': [hex(addr) for addr in self.stack_trace],
+        }
+
+
+@dataclass
+class CrashAnalysisResult:
+    """Result of crash analysis"""
+    crash_type: CrashType
+    confidence: float  # 0.0 to 1.0
+    description: str
+    affected_symbol: Optional[str]
+    affected_address: int
+    recommendations: List[str]
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        return {
+            'crash_type': self.crash_type.value,
+            'confidence': self.confidence,
+            'description': self.description,
+            'affected_symbol': self.affected_symbol,
+            'affected_address': hex(self.affected_address),
+            'recommendations': self.recommendations,
+        }
+
+
+class CrashAnalyzer:
+    """Main crash analysis engine"""
+
+    # Known invalid pointer patterns (bit 63 typically indicates kernel/error space)
+    INVALID_POINTER_MARKERS = [
+        0x8010000000000000,  # Bit 63 set
+        0xffff800000000000,  # Kernel space marker
+        0xdeadbeef,          # Debug pattern
+        0xdeaddeaddeaddead,  # Debug pattern
+        0xcccccccccccccccc,  # Debug pattern
+    ]
+
+    def __init__(self, binary_path: str, verbose: bool = False):
+        self.binary_path = binary_path
+        self.verbose = verbose
+        self.symbols: Dict[int, str] = {}
+        self.otool_path = self._find_otool()
+        self._load_symbols()
+
+    def _find_otool(self) -> Optional[str]:
+        """Find otool in common locations"""
+        possible_paths = [
+            'otool',
+            '/usr/bin/otool',
+            '/usr/local/bin/otool',
+            '/nest/build/Developer/Toolchains/Default.xctoolchain/usr/bin/otool',
+        ]
+
+        for path in possible_paths:
+            try:
+                result = subprocess.run([path, '-h', '--version'],
+                                      capture_output=True, timeout=2)
+                if result.returncode == 0:
+                    return path
+            except:
+                pass
+
+        return None
+
+    def _load_symbols(self):
+        """Load symbols from binary"""
+        # Try Mach-O first
+        if self._is_macho_binary() and self.otool_path:
+            self._load_symbols_from_macho()
+        else:
+            # Fall back to ELF
+            self._load_symbols_from_elf()
+
+    def _is_macho_binary(self) -> bool:
+        """Check if binary is Mach-O format"""
+        try:
+            result = subprocess.run(
+                ['file', self.binary_path],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            return 'Mach-O' in result.stdout
+        except:
+            return False
+
+    def _load_symbols_from_elf(self):
+        """Load symbols from ELF binary using nm"""
+        try:
+            result = subprocess.run(
+                ['nm', '-n', self.binary_path],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+
+            for line in result.stdout.strip().split('\n'):
+                parts = line.split()
+                if len(parts) >= 3:
+                    try:
+                        addr = int(parts[0], 16)
+                        name = ' '.join(parts[2:])
+                        self.symbols[addr] = name
+                    except (ValueError, IndexError):
+                        pass
+        except Exception as e:
+            if self.verbose:
+                print(f"Warning: Could not load ELF symbols: {e}", file=sys.stderr)
+
+    def _load_symbols_from_macho(self):
+        """Load symbols from Mach-O binary using otool"""
+        try:
+            result = subprocess.run(
+                [self.otool_path, '-tv', self.binary_path],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+
+            current_symbol = None
+            for line in result.stdout.strip().split('\n'):
+                line = line.strip()
+
+                # Symbol definition (ends with :)
+                if line.endswith(':') and not line[0].isdigit():
+                    current_symbol = line[:-1]
+
+                # Instruction line with address
+                parts = line.split()
+                if parts and all(c in '0123456789abcdef' for c in parts[0]):
+                    try:
+                        addr = int(parts[0], 16)
+                        if current_symbol:
+                            self.symbols[addr] = current_symbol
+                            current_symbol = None  # Clear after first instruction
+                    except (ValueError, IndexError):
+                        pass
+        except Exception as e:
+            if self.verbose:
+                print(f"Warning: Could not load Mach-O symbols: {e}", file=sys.stderr)
+
+    def analyze(self, crash_context: CrashContext) -> CrashAnalysisResult:
+        """Analyze crash and determine type"""
+
+        # Check for known invalid pointer patterns
+        if crash_context.rax and self._is_invalid_pointer(crash_context.rax):
+            return CrashAnalysisResult(
+                crash_type=CrashType.INVALID_POINTER,
+                confidence=0.95,
+                description=f"RAX contains invalid pointer: {hex(crash_context.rax)}. "
+                          f"Bit 63 set indicates kernel space or error marker.",
+                affected_symbol=self._find_symbol(crash_context.rip),
+                affected_address=crash_context.rip,
+                recommendations=[
+                    "Check dyld's binding/interposing state at this instruction",
+                    "Verify no corrupted mach-o load commands",
+                    "Review recursive dependency loading logic",
+                    "Check for malformed or misinterpreted bind/lazy-bind records",
+                ]
+            )
+
+        # Check for null pointer
+        if crash_context.rax == 0:
+            return CrashAnalysisResult(
+                crash_type=CrashType.NULL_POINTER,
+                confidence=0.90,
+                description="RAX is NULL, likely dereferencing null pointer",
+                affected_symbol=self._find_symbol(crash_context.rip),
+                affected_address=crash_context.rip,
+                recommendations=[
+                    "Add null pointer checks before memory operations",
+                    "Review control flow that could result in null values",
+                ]
+            )
+
+        # Check for syscall-related patterns
+        if self._is_syscall_location(crash_context.rip):
+            return CrashAnalysisResult(
+                crash_type=CrashType.SYSCALL_FAILURE,
+                confidence=0.85,
+                description="Crash at syscall instruction. "
+                          "May indicate invalid syscall number or arguments.",
+                affected_symbol=self._find_symbol(crash_context.rip),
+                affected_address=crash_context.rip,
+                recommendations=[
+                    "Check syscall number in RAX",
+                    "Verify syscall arguments in RDI, RSI, RDX",
+                    "Check if syscall is available in this kernel version",
+                ]
+            )
+
+        # Generic analysis
+        return CrashAnalysisResult(
+            crash_type=CrashType.UNKNOWN,
+            confidence=0.0,
+            description="Unable to determine crash cause from available information",
+            affected_symbol=self._find_symbol(crash_context.rip),
+            affected_address=crash_context.rip,
+            recommendations=[
+                "Obtain full debug symbols",
+                "Run under debugger to capture full register state",
+                "Enable crash reporter diagnostics",
+            ]
+        )
+
+    def _is_invalid_pointer(self, value: int) -> bool:
+        """Check if value looks like an invalid pointer"""
+        # Check bit 63 (high bit)
+        if value & (1 << 63):
+            return True
+
+        # Check known patterns
+        for pattern in self.INVALID_POINTER_MARKERS:
+            if (value & 0xf0f0f0f0f0f0f0f0) == (pattern & 0xf0f0f0f0f0f0f0f0):
+                return True
+
+        return False
+
+    def _find_symbol(self, address: int) -> Optional[str]:
+        """Find symbol containing or near address"""
+        # Look for exact match or closest lower address
+        closest_addr = None
+        closest_name = None
+
+        for addr in sorted(self.symbols.keys()):
+            if addr <= address:
+                closest_addr = addr
+                closest_name = self.symbols[addr]
+            else:
+                break
+
+        if closest_name:
+            offset = address - closest_addr if closest_addr else 0
+            if offset == 0:
+                return closest_name
+            else:
+                return f"{closest_name}+0x{offset:x}"
+
+        return None
+
+    def _is_syscall_location(self, address: int) -> bool:
+        """Check if address appears to be at a syscall instruction"""
+        try:
+            # Try otool first (for Mach-O)
+            if self.otool_path:
+                result = subprocess.run(
+                    [self.otool_path, '-tv', self.binary_path],
+                    capture_output=True,
+                    text=True,
+                    timeout=10
+                )
+
+                for line in result.stdout.split('\n'):
+                    if f'{address:x}' in line and 'syscall' in line.lower():
+                        return True
+
+            # Fall back to objdump (for ELF)
+            result = subprocess.run(
+                ['objdump', '-d', self.binary_path],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+
+            for line in result.stdout.split('\n'):
+                if f'{address:x}' in line and 'syscall' in line.lower():
+                    return True
+        except Exception:
+            pass
+
+        return False
+
+
+def parse_register_value(value_str: str) -> int:
+    """Parse register value (hex or decimal)"""
+    value_str = value_str.strip()
+    if value_str.startswith(('0x', '0X')):
+        return int(value_str, 16)
+    return int(value_str, 16)  # Default to hex for crash analysis
+
+
+def normalize_code_address(raw_addr: int, slide: int) -> int:
+    """Normalize a runtime code address to a file-relative address using slide."""
+    if slide < 0:
+        raise ValueError("slide must be non-negative")
+    if raw_addr < slide:
+        raise ValueError(f"address {hex(raw_addr)} is smaller than slide {hex(slide)}")
+    return raw_addr - slide
+
+
+def print_analysis_report(analysis: CrashAnalysisResult, crash_context: CrashContext):
+    """Pretty-print crash analysis report"""
+    print(f"\n{'='*70}")
+    print(f"  CRASH ANALYSIS REPORT")
+    print(f"{'='*70}\n")
+
+    print(f"Crash Type: {analysis.crash_type.value}")
+    print(f"Confidence: {analysis.confidence*100:.0f}%\n")
+
+    print(f"Description:")
+    print(f"  {analysis.description}\n")
+
+    print(f"Affected Symbol: {analysis.affected_symbol or 'Unknown'}")
+    print(f"Crash Address (RIP): {hex(crash_context.rip)}\n")
+
+    if crash_context.rax is not None:
+        print(f"RAX: {hex(crash_context.rax)}")
+    if crash_context.rdi is not None:
+        print(f"RDI: {hex(crash_context.rdi)}")
+    if crash_context.rsi is not None:
+        print(f"RSI: {hex(crash_context.rsi)}")
+    if crash_context.rdx is not None:
+        print(f"RDX: {hex(crash_context.rdx)}")
+
+    if crash_context.stack_trace:
+        print(f"\nStack Trace ({len(crash_context.stack_trace)} frames):")
+        for i, addr in enumerate(crash_context.stack_trace):
+            print(f"  [{i}] {hex(addr)}")
+
+    print(f"\nRecommendations:")
+    for i, rec in enumerate(analysis.recommendations, 1):
+        print(f"  {i}. {rec}")
+
+    print(f"\n{'='*70}\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Comprehensive crash analysis for ravynOS',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+  %(prog)s --rip 0x1d9660 --rax 0x8010000000000007 --binary /path/to/binary
+  %(prog)s --rip 0x1d9660 --stack-trace 0x...,0x...,0x... --binary /path/to/binary
+  %(prog)s --crash-file crash.txt --binary /path/to/binary
+        '''
+    )
+
+    parser.add_argument('--binary', required=True, help='Path to the crashed binary')
+    parser.add_argument('--rip', type=str, help='RIP register value (crash address)')
+    parser.add_argument('--rax', type=str, help='RAX register value')
+    parser.add_argument('--rdi', type=str, help='RDI register value')
+    parser.add_argument('--rsi', type=str, help='RSI register value')
+    parser.add_argument('--rdx', type=str, help='RDX register value')
+    parser.add_argument('--stack-trace', type=str, help='Stack trace (comma-separated addresses)')
+    parser.add_argument('--slide', type=str, help='ASLR slide to subtract from RIP/stack addresses (e.g. 0x11526d000)')
+    parser.add_argument('--crash-file', type=str, help='Read crash context from file')
+    parser.add_argument('--json', action='store_true', help='Output as JSON')
+    parser.add_argument('-v', '--verbose', action='store_true', help='Verbose output')
+
+    args = parser.parse_args()
+
+    try:
+        slide = parse_register_value(args.slide) if args.slide else 0
+
+        # Parse crash context
+        if args.crash_file:
+            # TODO: Parse crash file format
+            print("Error: --crash-file not yet implemented", file=sys.stderr)
+            return 1
+
+        if not args.rip:
+            parser.print_help()
+            return 1
+
+        raw_rip = parse_register_value(args.rip)
+
+        # Build crash context
+        context = CrashContext(
+            rip=normalize_code_address(raw_rip, slide),
+            rax=parse_register_value(args.rax) if args.rax else None,
+            rdi=parse_register_value(args.rdi) if args.rdi else None,
+            rsi=parse_register_value(args.rsi) if args.rsi else None,
+            rdx=parse_register_value(args.rdx) if args.rdx else None,
+        )
+
+        # Parse stack trace
+        if args.stack_trace:
+            context.stack_trace = [
+                normalize_code_address(parse_register_value(addr.strip()), slide)
+                for addr in args.stack_trace.split(',')
+            ]
+
+        if slide and not args.json:
+            print(f"Applied slide: {hex(slide)}")
+            print(f"RIP normalized: {hex(raw_rip)} -> {hex(context.rip)}")
+
+        # Perform analysis
+        analyzer = CrashAnalyzer(args.binary, verbose=args.verbose)
+        result = analyzer.analyze(context)
+
+        if args.json:
+            output = {
+                'crash_context': context.to_dict(),
+                'analysis': result.to_dict(),
+            }
+            print(json.dumps(output, indent=2))
+        else:
+            print_analysis_report(result, context)
+
+        return 0
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except ValueError as e:
+        print(f"Error: Invalid register value: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())
+
+
+
+

tools/symbolicate.py

@@ -0,0 +1,577 @@
+#!/usr/bin/env python3
+"""
+Symbolication Tool for ravynOS Crash Analysis
+
+This tool maps crash addresses to symbols in compiled binaries, helping identify
+the exact function and instruction where a crash occurred.
+
+Usage:
+    ./symbolicate.py <binary_path> <address> [<address2> ...]
+    ./symbolicate.py <binary_path> --rip <address> --rax <address>
+    ./symbolicate.py <binary_path> --stack-trace <addr1>,<addr2>,<addr3>
+
+Examples:
+    ./symbolicate.py /path/to/launchd 0x1d9660
+    ./symbolicate.py /path/to/dyld 0x00000001154ad2eb
+    ./symbolicate.py /path/to/dyld --rip 0x1d9660 --rax 0x8010000000000007
+    ./symbolicate.py /path/to/dyld --stack-trace 0x1d9660,0x1d9700,0x1d9750
+"""
+
+import sys
+import os
+import subprocess
+import re
+import argparse
+from dataclasses import dataclass
+from typing import List, Optional, Dict, Tuple
+import json
+
+@dataclass
+class Symbol:
+    """Represents a symbol in the binary"""
+    address: int
+    size: int
+    name: str
+    section: str
+    is_function: bool
+
+    def contains(self, addr: int) -> bool:
+        """Check if address falls within this symbol's range"""
+        return self.address <= addr < (self.address + self.size)
+
+    def offset(self, addr: int) -> int:
+        """Get offset from symbol start to given address"""
+        return addr - self.address
+
+    def __repr__(self) -> str:
+        offset_str = f"+0x{self.offset(addr):x}" if hasattr(self, 'addr') else ""
+        return f"{self.name} ({self.section}) @ 0x{self.address:x}"
+
+
+@dataclass
+class SymbolicationResult:
+    """Result of symbolication for a single address"""
+    address: int
+    symbol: Optional[Symbol]
+    context: Optional[str]  # e.g., "first instruction", "middle of function"
+
+    def __str__(self) -> str:
+        if not self.symbol:
+            return f"0x{self.address:x} - Unknown symbol"
+
+        offset = self.offset()
+        if offset == 0:
+            offset_str = " (entry point)"
+        else:
+            offset_str = f" +0x{offset:x}"
+
+        return f"0x{self.address:x} -> {self.symbol.name}{offset_str} ({self.symbol.section})"
+
+    def offset(self) -> int:
+        if self.symbol:
+            return self.symbol.offset(self.address)
+        return 0
+
+
+class Symbolizer:
+    """Main symbolication engine"""
+
+    def __init__(self, binary_path: str, verbose: bool = False):
+        self.binary_path = binary_path
+        self.verbose = verbose
+        self.symbols: List[Symbol] = []
+        self._symbol_map: Dict[int, Symbol] = {}
+
+        if not os.path.exists(binary_path):
+            raise FileNotFoundError(f"Binary not found: {binary_path}")
+
+        self._load_symbols()
+
+    def _find_otool(self) -> Optional[str]:
+        """Find otool in common locations"""
+        possible_paths = [
+            'otool',
+            '/usr/bin/otool',
+            '/usr/local/bin/otool',
+            '/nest/build/Developer/Toolchains/Default.xctoolchain/usr/bin/otool',
+        ]
+
+        for path in possible_paths:
+            try:
+                result = subprocess.run([path, '-h', '--version'],
+                                      capture_output=True, timeout=2)
+                if result.returncode == 0:
+                    return path
+            except:
+                pass
+
+        return None
+
+    def _load_symbols(self):
+        """Load symbols from the binary using nm or otool"""
+        try:
+            # First, check if this is a Mach-O binary (ravynOS/macOS)
+            if self._is_macho_binary():
+                self._load_symbols_from_macho()
+            else:
+                # Fall back to ELF (nm)
+                self._load_symbols_from_elf()
+
+        except FileNotFoundError:
+            raise RuntimeError("Symbol tools not found. Install binutils and/or otool.")
+        except subprocess.TimeoutExpired:
+            raise RuntimeError("Symbol loading timed out")
+
+        if self.verbose:
+            print(f"Loaded {len(self.symbols)} symbols", file=sys.stderr)
+
+    def _is_macho_binary(self) -> bool:
+        """Check if binary is Mach-O format"""
+        try:
+            result = subprocess.run(
+                ['file', self.binary_path],
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            return 'Mach-O' in result.stdout
+        except:
+            return False
+
+    def _load_symbols_from_elf(self):
+        """Load symbols from ELF binary using nm"""
+        result = subprocess.run(
+            ['nm', '-nSt', self.binary_path],
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        if result.returncode != 0:
+            if self.verbose:
+                print(f"Warning: nm failed: {result.stderr}", file=sys.stderr)
+            return
+
+        self._parse_nm_output(result.stdout)
+
+    def _load_symbols_from_macho(self):
+        """Load symbols from Mach-O binary using otool"""
+        # Find otool
+        otool_path = self._find_otool()
+        if not otool_path:
+            if self.verbose:
+                print(f"Warning: otool not found", file=sys.stderr)
+            return
+
+        # Get disassembly with symbols
+        result = subprocess.run(
+            [otool_path, '-tv', self.binary_path],
+            capture_output=True,
+            text=True,
+            timeout=30
+        )
+
+        if result.returncode != 0:
+            if self.verbose:
+                print(f"Warning: otool -tv failed: {result.stderr}", file=sys.stderr)
+            return
+
+        self._parse_otool_output(result.stdout)
+
+    def _parse_nm_output(self, output: str):
+        """Parse nm output in format: address size type section name"""
+        # Format from 'nm -nSt': address size type section name
+        pattern = r'^([0-9a-f]+)\s+([0-9a-f]+)\s+(.)\s+(\S+)\s+(.+)$'
+
+        for line in output.strip().split('\n'):
+            if not line.strip():
+                continue
+
+            match = re.match(pattern, line)
+            if not match:
+                continue
+
+            addr_str, size_str, sym_type, section, name = match.groups()
+
+            try:
+                address = int(addr_str, 16)
+                size = int(size_str, 16)
+                is_function = sym_type in 'tT'  # lowercase = local, uppercase = global
+
+                symbol = Symbol(
+                    address=address,
+                    size=size,
+                    name=name,
+                    section=section,
+                    is_function=is_function
+                )
+
+                self.symbols.append(symbol)
+                if address not in self._symbol_map:
+                    self._symbol_map[address] = symbol
+
+            except (ValueError, IndexError) as e:
+                if self.verbose:
+                    print(f"Warning: Failed to parse symbol line: {line}", file=sys.stderr)
+
+        # Sort symbols by address for binary search
+        self.symbols.sort(key=lambda s: s.address)
+
+    def _parse_otool_output(self, output: str):
+        """Parse otool -tv output for Mach-O binaries
+
+        Format example:
+        _main:
+        0000000100000be0        pushq   %rbp
+
+        Or with actual symbol names at the start
+        """
+        current_symbol = None
+        current_address = None
+        max_instruction_address = None
+
+        for line in output.strip().split('\n'):
+            line = line.strip()
+            if not line:
+                continue
+
+            # Check for symbol name (function definition)
+            # Format: _functionname: or functionname:
+            if line.endswith(':') and not line[0].isdigit():
+                symbol_name = line[:-1]
+                current_symbol = symbol_name
+                current_address = None
+                continue
+
+            # Parse instruction lines to get addresses
+            # Format: 0000000100000be0        pushq   %rbp
+            parts = line.split()
+            if len(parts) >= 2 and all(c in '0123456789abcdef' for c in parts[0]):
+                try:
+                    address = int(parts[0], 16)
+                    if max_instruction_address is None or address > max_instruction_address:
+                        max_instruction_address = address
+
+                    if current_symbol and current_address is None:
+                        # This is the first instruction of a symbol
+                        current_address = address
+
+                        # Create symbol entry
+                        symbol = Symbol(
+                            address=address,
+                            size=0,  # We don't know the size from otool -tv alone
+                            name=current_symbol,
+                            section='__text',  # Usually in text section
+                            is_function=True
+                        )
+
+                        self.symbols.append(symbol)
+                        if address not in self._symbol_map:
+                            self._symbol_map[address] = symbol
+
+                        current_symbol = None
+
+                except (ValueError, IndexError):
+                    pass
+
+        # Sort symbols and infer synthetic sizes so range lookups work for Mach-O.
+        self.symbols.sort(key=lambda s: s.address)
+        for i in range(len(self.symbols) - 1):
+            next_addr = self.symbols[i + 1].address
+            curr_addr = self.symbols[i].address
+            inferred = max(1, next_addr - curr_addr)
+            if self.symbols[i].size == 0:
+                self.symbols[i].size = inferred
+
+        # Keep the final symbol searchable for nearby addresses.
+        if self.symbols and self.symbols[-1].size == 0:
+            if max_instruction_address is not None and max_instruction_address >= self.symbols[-1].address:
+                self.symbols[-1].size = (max_instruction_address - self.symbols[-1].address) + 1
+            else:
+                self.symbols[-1].size = 1
+
+    def symbolicate(self, address: int) -> SymbolicationResult:
+        """Find the symbol containing the given address"""
+
+        # Quick lookup if exact address exists
+        if address in self._symbol_map:
+            return SymbolicationResult(
+                address=address,
+                symbol=self._symbol_map[address],
+                context="entry point"
+            )
+
+        # Binary search for containing symbol
+        symbol = self._find_containing_symbol(address)
+
+        if symbol:
+            context = None
+            offset = symbol.offset(address)
+
+            # Provide context based on offset
+            if offset == 0:
+                context = "entry point"
+            elif offset < 32:  # Typical prologue size
+                context = "in prologue"
+            elif offset == symbol.size - 1:
+                context = "at exit"
+
+            return SymbolicationResult(
+                address=address,
+                symbol=symbol,
+                context=context
+            )
+
+        return SymbolicationResult(address=address, symbol=None, context=None)
+
+    def _find_containing_symbol(self, address: int) -> Optional[Symbol]:
+        """Binary search to find symbol containing address"""
+        left, right = 0, len(self.symbols) - 1
+
+        while left <= right:
+            mid = (left + right) // 2
+            symbol = self.symbols[mid]
+
+            if symbol.contains(address):
+                return symbol
+            elif symbol.address > address:
+                right = mid - 1
+            else:
+                left = mid + 1
+
+        # Check the symbol just before the address
+        if right >= 0 and right < len(self.symbols):
+            symbol = self.symbols[right]
+            if symbol.contains(address):
+                return symbol
+
+        return None
+
+    def symbolicate_multiple(self, addresses: List[int]) -> List[SymbolicationResult]:
+        """Symbolicate multiple addresses"""
+        return [self.symbolicate(addr) for addr in addresses]
+
+    def find_symbol_by_name(self, name: str, exact: bool = False) -> List[Symbol]:
+        """Find symbols by name (substring or exact match)"""
+        results = []
+        for symbol in self.symbols:
+            if exact:
+                if symbol.name == name:
+                    results.append(symbol)
+            else:
+                if name.lower() in symbol.name.lower():
+                    results.append(symbol)
+        return results
+
+    def get_context_around_address(self, address: int, before: int = 5, after: int = 5) -> List[Symbol]:
+        """Get symbols around a given address"""
+        idx = self._find_symbol_index(address)
+        if idx is None:
+            return []
+
+        start = max(0, idx - before)
+        end = min(len(self.symbols), idx + after + 1)
+        return self.symbols[start:end]
+
+    def _find_symbol_index(self, address: int) -> Optional[int]:
+        """Find the index of a symbol containing or near the address"""
+        left, right = 0, len(self.symbols) - 1
+
+        while left <= right:
+            mid = (left + right) // 2
+            symbol = self.symbols[mid]
+
+            if symbol.contains(address):
+                return mid
+            elif symbol.address > address:
+                right = mid - 1
+            else:
+                left = mid + 1
+
+        return right if right >= 0 else None
+
+
+def parse_hex_address(addr_str: str) -> int:
+    """Parse address string (with or without 0x prefix)"""
+    addr_str = addr_str.strip()
+    if addr_str.startswith(('0x', '0X')):
+        return int(addr_str, 16)
+    return int(addr_str, 16)
+
+
+def format_hex_address(addr: int) -> str:
+    """Format address as hex string"""
+    return f"0x{addr:x}"
+
+
+def normalize_code_address(raw_addr: int, slide: int) -> int:
+    """Normalize a runtime code address to a file-relative address using slide."""
+    if slide < 0:
+        raise ValueError("slide must be non-negative")
+    if raw_addr < slide:
+        raise ValueError(f"address {format_hex_address(raw_addr)} is smaller than slide {format_hex_address(slide)}")
+    return raw_addr - slide
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Symbolicate crash addresses in ravynOS binaries',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog='''
+Examples:
+  %(prog)s /path/to/launchd 0x1d9660
+  %(prog)s /path/to/dyld 0x1d9660 0x1d9700 0x1d9750
+  %(prog)s /path/to/dyld --rip 0x1d9660
+  %(prog)s /path/to/dyld --stack-trace 0x1d9660,0x1d9700,0x1d9750
+  %(prog)s /path/to/dyld --search syscall
+        '''
+    )
+
+    parser.add_argument('binary', help='Path to the binary to symbolicate')
+    parser.add_argument('addresses', nargs='*', help='Addresses to symbolicate')
+    parser.add_argument('--rip', type=str, help='RIP register value (crashed instruction pointer)')
+    parser.add_argument('--rax', type=str, help='RAX register value (for context)')
+    parser.add_argument('--stack-trace', type=str, help='Stack trace addresses (comma-separated)')
+    parser.add_argument('--slide', type=str, help='ASLR slide to subtract from code addresses (e.g. 0x11526d000)')
+    parser.add_argument('--search', type=str, help='Search for symbol by name')
+    parser.add_argument('--context', type=int, default=5, help='Symbols to show around address (default: 5)')
+    parser.add_argument('--json', action='store_true', help='Output as JSON')
+    parser.add_argument('-v', '--verbose', action='store_true', help='Verbose output')
+
+    args = parser.parse_args()
+
+    try:
+        slide = parse_hex_address(args.slide) if args.slide else 0
+
+        # Initialize symbolizer
+        symbolizer = Symbolizer(args.binary, verbose=args.verbose)
+
+        # Handle search mode
+        if args.search:
+            print(f"\nSearching for symbols matching: {args.search}")
+            results = symbolizer.find_symbol_by_name(args.search)
+            if results:
+                for symbol in results:
+                    print(f"  0x{symbol.address:x} {symbol.name} ({symbol.section}) size=0x{symbol.size:x}")
+            else:
+                print("  No symbols found")
+            return 0
+
+        # Collect addresses to symbolicate
+        addresses_to_symbolicate = []
+
+        # Add RIP if provided
+        if args.rip:
+            try:
+                raw_rip = parse_hex_address(args.rip)
+                normalized_rip = normalize_code_address(raw_rip, slide)
+                addresses_to_symbolicate.append(normalized_rip)
+                if slide:
+                    print(f"RIP: {args.rip} -> {format_hex_address(normalized_rip)} (slide={format_hex_address(slide)})")
+                else:
+                    print(f"RIP: {args.rip}")
+            except ValueError:
+                print(f"Error: Invalid RIP address: {args.rip}", file=sys.stderr)
+                return 1
+
+        # Add RAX if provided (for reference)
+        if args.rax:
+            try:
+                rax_addr = parse_hex_address(args.rax)
+                print(f"RAX: {args.rax} (invalid pointer marker)")
+            except ValueError:
+                print(f"Error: Invalid RAX address: {args.rax}", file=sys.stderr)
+
+        # Add stack trace addresses
+        if args.stack_trace:
+            try:
+                for addr_str in args.stack_trace.split(','):
+                    raw_addr = parse_hex_address(addr_str.strip())
+                    addresses_to_symbolicate.append(normalize_code_address(raw_addr, slide))
+            except ValueError as e:
+                print(f"Error: Invalid stack trace address: {e}", file=sys.stderr)
+                return 1
+
+        # Add positional arguments
+        for addr_str in args.addresses:
+            try:
+                raw_addr = parse_hex_address(addr_str)
+                addresses_to_symbolicate.append(normalize_code_address(raw_addr, slide))
+            except ValueError:
+                print(f"Error: Invalid address: {addr_str}", file=sys.stderr)
+                return 1
+
+        if not addresses_to_symbolicate:
+            parser.print_help()
+            return 1
+
+        # Symbolicate
+        results = symbolizer.symbolicate_multiple(addresses_to_symbolicate)
+
+        if args.json:
+            # JSON output
+            json_results = []
+            for result in results:
+                json_obj = {
+                    'address': format_hex_address(result.address),
+                    'symbol': result.symbol.name if result.symbol else None,
+                    'section': result.symbol.section if result.symbol else None,
+                    'offset': f"0x{result.offset():x}" if result.symbol else None,
+                    'context': result.context
+                }
+                json_results.append(json_obj)
+            print(json.dumps(json_results, indent=2))
+        else:
+            # Human-readable output
+            print("\n=== Symbolication Results ===\n")
+
+            for i, result in enumerate(results):
+                print(f"{i+1}. {result}")
+
+                # Show context
+                if result.symbol:
+                    print(f"   Size: 0x{result.symbol.size:x} bytes")
+                    print(f"   Offset: 0x{result.offset():x}")
+                    if result.context:
+                        print(f"   Context: {result.context}")
+
+                    # Show nearby symbols
+                    if args.context > 0:
+                        context_symbols = symbolizer.get_context_around_address(
+                            result.address,
+                            before=args.context,
+                            after=args.context
+                        )
+                        print(f"   Nearby symbols:")
+                        for nearby in context_symbols:
+                            marker = " <--" if nearby == result.symbol else ""
+                            print(f"     0x{nearby.address:x} {nearby.name}{marker}")
+
+                print()
+
+        return 0
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())
+
+
+
+
+
+
+
+