README.md

@@ -1,118 +1,2 @@
-# Browser History to Timesketch Converter
+# browser2timesketch
 
-Converts browser history from Firefox, Chrome, Safari, and all Chromium-based browsers to Timesketch-compatible CSV format.
-
-## Requirements
-
-- Python 3.6+
-- No external dependencies (standard library only)
-
-## Usage
-
-### Simple (Auto-detect browser type)
-```bash
-python browser2timesketch.py -i <database_path>
-```
-
-### With Options
-```bash
-python browser2timesketch.py [OPTIONS] -i <database_path>
-```
-
-## Command-Line Arguments
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `-i`, `--input` | Yes | Path to browser history database file |
-| `-b`, `--browser` | No | Browser type: `firefox`, `chromium`, `safari`, or `auto` (default: auto) |
-| `-o`, `--output` | No | Output CSV file path (default: auto-generated) |
-| `--browser-name` | No | Custom browser name for data_type field (e.g., "Brave", "Edge") |
-
-## Finding Browser Database Files
-
-### Firefox (all platforms)
-
-1. Open Firefox
-2. Type `about:support` in address bar
-3. Look for **Profile Folder** or **Profile Directory**
-4. Click **Open Folder** button
-5. Find `places.sqlite` in that folder
-
-**Standard locations:**
-- **Linux:** `~/.mozilla/firefox/<profile>/places.sqlite`
-- **macOS:** `~/Library/Application Support/Firefox/Profiles/<profile>/places.sqlite`
-- **Windows:** `%APPDATA%\Mozilla\Firefox\Profiles\<profile>\places.sqlite`
-
-### Chrome, Edge, Brave, Opera, Vivaldi (all Chromium browsers)
-
-1. Open your browser
-2. Type `chrome://version/` in address bar
-   - For Edge: `edge://version/`
-   - For Brave: `brave://version/`
-   - For Opera: `opera://about/`
-   - For Vivaldi: `vivaldi://about/`
-3. Look for **Profile Path**
-4. Find `History` file (no extension) in that folder
-
-**Standard locations:**
-
-**Google Chrome:**
-- **Linux:** `~/.config/google-chrome/Default/History`
-- **macOS:** `~/Library/Application Support/Google/Chrome/Default/History`
-- **Windows:** `%LOCALAPPDATA%\Google\Chrome\User Data\Default\History`
-
-**Microsoft Edge:**
-- **Linux:** `~/.config/microsoft-edge/Default/History`
-- **macOS:** `~/Library/Application Support/Microsoft Edge/Default/History`
-- **Windows:** `%LOCALAPPDATA%\Microsoft\Edge\User Data\Default\History`
-
-**Brave:**
-- **Linux:** `~/.config/BraveSoftware/Brave-Browser/Default/History`
-- **macOS:** `~/Library/Application Support/BraveSoftware/Brave-Browser/Default/History`
-- **Windows:** `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data\Default\History`
-
-**Opera:**
-- **Linux:** `~/.config/opera/Default/History`
-- **macOS:** `~/Library/Application Support/com.operasoftware.Opera/History`
-- **Windows:** `%APPDATA%\Opera Software\Opera Stable\History`
-
-**Vivaldi:**
-- **Linux:** `~/.config/vivaldi/Default/History`
-- **macOS:** `~/Library/Application Support/Vivaldi/Default/History`
-- **Windows:** `%LOCALAPPDATA%\Vivaldi\User Data\Default\History`
-
-### Safari (macOS only)
-
-**Location:** `~/Library/Safari/History.db`
-
-**To open in Finder:**
-1. Press `Cmd + Shift + G`
-2. Type `~/Library/Safari/`
-3. Press Enter
-
-## Examples
-
-### Auto-detect (simplest)
-```bash
-python browser2timesketch.py -i ~/.mozilla/firefox/abc123.default/places.sqlite
-python browser2timesketch.py -i ~/.config/google-chrome/Default/History
-python browser2timesketch.py -i ~/Library/Safari/History.db
-```
-
-### Specify browser type
-```bash
-python browser2timesketch.py -b firefox -i places.sqlite -o firefox.csv
-python browser2timesketch.py -b chromium -i History -o chrome.csv
-python browser2timesketch.py -b safari -i History.db -o safari.csv
-```
-
-### With custom browser name
-```bash
-python browser2timesketch.py --browser-name "Brave" -i ~/.config/BraveSoftware/Brave-Browser/Default/History
-```
-
-## Notes
-
-- Close your browser before running to avoid database locks (or the script will use read-only mode)
-- Output contains complete browsing history - handle securely
-- On Windows, use quotes around paths with spaces

browser2timesketch.py

@@ -1,867 +0,0 @@
-#!/usr/bin/env python3
-"""
-Browser History to Timesketch CSV Converter
-
-Converts browser history from major browser engines to Timesketch-compatible CSV format.
-Supports: Gecko (Firefox), Chromium (Chrome/Edge/Brave/etc.), WebKit (Safari)
-"""
-
-import sqlite3
-import csv
-import argparse
-import sys
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Tuple, Optional, Dict, Any, List
-
-
-class BrowserDetectionError(Exception):
-    """Raised when browser type cannot be detected"""
-    pass
-
-
-class DatabaseValidationError(Exception):
-    """Raised when database validation fails"""
-    pass
-
-
-class TimestampValidationError(Exception):
-    """Raised when timestamp validation fails"""
-    pass
-
-
-def validate_sqlite_database(db_path: str) -> None:
-    """
-    Validate that the file is a SQLite database and is accessible.
-    
-    Args:
-        db_path: Path to database file
-        
-    Raises:
-        DatabaseValidationError: If validation fails
-    """
-    path = Path(db_path)
-    
-    if not path.exists():
-        raise DatabaseValidationError(f"Database file not found: {db_path}")
-    
-    if not path.is_file():
-        raise DatabaseValidationError(f"Path is not a file: {db_path}")
-    
-    # Try to open as SQLite database
-    try:
-        conn = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
-        cursor = conn.cursor()
-        # Check if it's a valid SQLite database by querying sqlite_master
-        cursor.execute("SELECT name FROM sqlite_master WHERE type='table' LIMIT 1")
-        conn.close()
-    except sqlite3.DatabaseError as e:
-        raise DatabaseValidationError(f"Not a valid SQLite database: {db_path}. Error: {e}")
-    except sqlite3.OperationalError as e:
-        raise DatabaseValidationError(f"Cannot access database (may be locked or corrupted): {db_path}. Error: {e}")
-
-
-def detect_browser_type(db_path: str) -> str:
-    """
-    Auto-detect browser type by examining database schema.
-    
-    Args:
-        db_path: Path to database file
-        
-    Returns:
-        Detected browser type: 'gecko', 'chromium', or 'webkit'
-        
-    Raises:
-        BrowserDetectionError: If browser type cannot be determined
-    """
-    try:
-        conn = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
-        cursor = conn.cursor()
-        
-        # Get all table names
-        cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
-        tables = {row[0] for row in cursor.fetchall()}
-        
-        conn.close()
-        
-        # Check for Gecko/Firefox tables
-        if 'moz_historyvisits' in tables and 'moz_places' in tables:
-            return 'gecko'
-        
-        # Check for Chromium tables
-        if 'visits' in tables and 'urls' in tables:
-            return 'chromium'
-        
-        # Check for WebKit/Safari tables
-        if 'history_visits' in tables and 'history_items' in tables:
-            return 'webkit'
-        
-        raise BrowserDetectionError(
-            f"Cannot determine browser type. Found tables: {', '.join(sorted(tables))}\n"
-            f"Expected one of:\n"
-            f"  - Gecko/Firefox: moz_historyvisits, moz_places\n"
-            f"  - Chromium: visits, urls\n"
-            f"  - WebKit/Safari: history_visits, history_items"
-        )
-        
-    except sqlite3.Error as e:
-        raise BrowserDetectionError(f"Error reading database schema: {e}")
-
-
-def validate_timestamp(unix_microseconds: int, browser_type: str) -> None:
-    """
-    Validate that a timestamp is within reasonable bounds.
-    
-    Args:
-        unix_microseconds: Timestamp in Unix microseconds
-        browser_type: Browser type for error messages
-        
-    Raises:
-        TimestampValidationError: If timestamp is unreasonable
-    """
-    if unix_microseconds <= 0:
-        return  # Allow 0 for missing timestamps
-    
-    # Convert to seconds for validation
-    timestamp_seconds = unix_microseconds / 1000000
-    
-    # Check if timestamp is reasonable (between 1990 and 2040)
-    min_date = datetime(1990, 1, 1)
-    max_date = datetime(2040, 1, 1)
-    min_seconds = min_date.timestamp()
-    max_seconds = max_date.timestamp()
-    
-    if timestamp_seconds < min_seconds:
-        dt = datetime.fromtimestamp(timestamp_seconds, tz=timezone.utc)
-        raise TimestampValidationError(
-            f"Timestamp appears too old: {dt.strftime('%Y-%m-%d %H:%M:%S')} (before 1990). "
-            f"This may indicate a timestamp conversion error for {browser_type}."
-        )
-    
-    if timestamp_seconds > max_seconds:
-        dt = datetime.fromtimestamp(timestamp_seconds, tz=timezone.utc)
-        raise TimestampValidationError(
-            f"Timestamp appears to be in the future: {dt.strftime('%Y-%m-%d %H:%M:%S')} (after 2040). "
-            f"This may indicate a timestamp conversion error for {browser_type}."
-        )
-
-
-def convert_gecko_timestamp(gecko_timestamp: Optional[int]) -> Tuple[int, str]:
-    """
-    Convert Gecko/Firefox timestamp (microseconds since Unix epoch) to ISO format.
-    Firefox stores timestamps as microseconds since 1970-01-01 00:00:00 UTC.
-    
-    Args:
-        gecko_timestamp: Gecko timestamp in microseconds
-        
-    Returns:
-        tuple: (microseconds, ISO formatted datetime string)
-    """
-    if gecko_timestamp is None or gecko_timestamp == 0:
-        return 0, ""
-    
-    # Validate
-    validate_timestamp(gecko_timestamp, "Gecko/Firefox")
-    
-    # Convert microseconds to seconds
-    timestamp_seconds = gecko_timestamp / 1000000
-    dt = datetime.fromtimestamp(timestamp_seconds, tz=timezone.utc)
-    return gecko_timestamp, dt.strftime('%Y-%m-%dT%H:%M:%S+00:00')
-
-
-def convert_chromium_timestamp(chromium_timestamp: Optional[int]) -> Tuple[int, str]:
-    """
-    Convert Chromium timestamp to Unix microseconds and ISO format.
-    Chromium stores timestamps as microseconds since 1601-01-01 00:00:00 UTC (Windows epoch).
-    
-    Args:
-        chromium_timestamp: Chromium timestamp in microseconds since 1601
-        
-    Returns:
-        tuple: (Unix microseconds, ISO formatted datetime string)
-    """
-    if chromium_timestamp is None or chromium_timestamp == 0:
-        return 0, ""
-    
-    # Chromium epoch: January 1, 1601
-    # Unix epoch: January 1, 1970
-    # Difference: 11644473600 seconds
-    chromium_epoch_offset = 11644473600
-    
-    # Convert to Unix timestamp (seconds since 1970)
-    timestamp_seconds = (chromium_timestamp / 1000000) - chromium_epoch_offset
-    
-    # Convert to Unix microseconds for Timesketch
-    unix_microseconds = int(timestamp_seconds * 1000000)
-    
-    # Validate
-    validate_timestamp(unix_microseconds, "Chromium")
-    
-    dt = datetime.fromtimestamp(timestamp_seconds, tz=timezone.utc)
-    return unix_microseconds, dt.strftime('%Y-%m-%dT%H:%M:%S+00:00')
-
-
-def convert_webkit_timestamp(webkit_timestamp: Optional[float]) -> Tuple[int, str]:
-    """
-    Convert WebKit/Safari timestamp to Unix microseconds and ISO format.
-    Safari stores timestamps as seconds (with decimal) since 2001-01-01 00:00:00 UTC (Cocoa/Core Data epoch).
-    
-    Args:
-        webkit_timestamp: WebKit timestamp in seconds since 2001
-        
-    Returns:
-        tuple: (Unix microseconds, ISO formatted datetime string)
-    """
-    if webkit_timestamp is None or webkit_timestamp == 0:
-        return 0, ""
-    
-    # WebKit/Cocoa epoch: January 1, 2001
-    # Unix epoch: January 1, 1970
-    # Difference: 978307200 seconds
-    webkit_epoch_offset = 978307200
-    
-    # Convert to Unix timestamp (seconds since 1970)
-    timestamp_seconds = webkit_timestamp + webkit_epoch_offset
-    
-    # Convert to Unix microseconds for Timesketch
-    unix_microseconds = int(timestamp_seconds * 1000000)
-    
-    # Validate
-    validate_timestamp(unix_microseconds, "WebKit/Safari")
-    
-    dt = datetime.fromtimestamp(timestamp_seconds, tz=timezone.utc)
-    return unix_microseconds, dt.strftime('%Y-%m-%dT%H:%M:%S+00:00')
-
-
-def write_timesketch_csv(output_csv: str, fieldnames: List[str], rows: List[Dict[str, Any]]) -> None:
-    """
-    Write history data to Timesketch-compatible CSV format.
-    
-    Args:
-        output_csv: Path to output CSV file
-        fieldnames: List of CSV field names
-        rows: List of row dictionaries to write
-    """
-    with open(output_csv, 'w', newline='', encoding='utf-8') as csvfile:
-        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
-        writer.writeheader()
-        
-        for row in rows:
-            writer.writerow(row)
-
-
-def connect_database_readonly(db_path: str) -> sqlite3.Connection:
-    """
-    Connect to database in read-only mode to avoid lock issues.
-    
-    Args:
-        db_path: Path to database file
-        
-    Returns:
-        SQLite connection object
-        
-    Raises:
-        sqlite3.OperationalError: If database is locked or inaccessible
-    """
-    try:
-        # Use URI with read-only mode to avoid locking issues
-        conn = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
-        return conn
-    except sqlite3.OperationalError as e:
-        raise sqlite3.OperationalError(
-            f"Cannot open database (it may be locked by the browser): {db_path}\n"
-            f"Please close {db_path.split('/')[-2] if '/' in db_path else 'the browser'} "
-            f"and try again, or copy the database file to a temporary location.\n"
-            f"Original error: {e}"
-        )
-
-
-def validate_browser_schema(conn: sqlite3.Connection, expected_tables: List[str], browser_name: str) -> None:
-    """
-    Validate that required tables exist in the database.
-    
-    Args:
-        conn: Database connection
-        expected_tables: List of required table names
-        browser_name: Browser name for error messages
-        
-    Raises:
-        DatabaseValidationError: If required tables are missing
-    """
-    cursor = conn.cursor()
-    cursor.execute("SELECT name FROM sqlite_master WHERE type='table'")
-    existing_tables = {row[0] for row in cursor.fetchall()}
-    
-    missing_tables = set(expected_tables) - existing_tables
-    if missing_tables:
-        raise DatabaseValidationError(
-            f"Database does not appear to be a valid {browser_name} history database.\n"
-            f"Missing required tables: {', '.join(missing_tables)}\n"
-            f"Found tables: {', '.join(sorted(existing_tables))}"
-        )
-
-
-def extract_chromium_history(db_path: str, output_csv: str, browser_name: Optional[str] = None) -> int:
-    """
-    Extract browser history from Chromium-based browsers and convert to Timesketch CSV.
-    Works with all Chromium-based browsers: Chrome, Edge, Brave, Chromium, Opera, Vivaldi, etc.
-    
-    Args:
-        db_path: Path to Chromium History database
-        output_csv: Path to output CSV file
-        browser_name: Optional custom name for data_type field (default: "Chromium")
-        
-    Returns:
-        Number of entries processed
-        
-    Raises:
-        DatabaseValidationError: If database validation fails
-        sqlite3.Error: If database query fails
-    """
-    if browser_name is None:
-        browser_name = "Chromium"
-    
-    # Connect to database
-    conn = connect_database_readonly(db_path)
-    
-    # Validate schema
-    validate_browser_schema(conn, ['visits', 'urls'], browser_name)
-    
-    cursor = conn.cursor()
-    
-    # Query to extract history visits with URL information
-    query = """
-    SELECT 
-        visits.visit_time,
-        urls.url,
-        urls.title,
-        visits.transition,
-        visits.visit_duration,
-        urls.visit_count,
-        urls.typed_count,
-        urls.last_visit_time
-    FROM visits
-    JOIN urls ON visits.url = urls.id
-    ORDER BY visits.visit_time
-    """
-    
-    try:
-        cursor.execute(query)
-        results = cursor.fetchall()
-    except sqlite3.Error as e:
-        conn.close()
-        raise sqlite3.Error(f"Error querying {browser_name} history: {e}")
-    
-    # Transition type mapping (Chromium transition types)
-    transition_types = {
-        0: "Link",
-        1: "Typed",
-        2: "Auto_Bookmark",
-        3: "Auto_Subframe",
-        4: "Manual_Subframe",
-        5: "Generated",
-        6: "Start_Page",
-        7: "Form_Submit",
-        8: "Reload",
-        9: "Keyword",
-        10: "Keyword_Generated"
-    }
-    
-    rows = []
-    validation_errors = []
-    
-    for idx, row in enumerate(results):
-        chromium_timestamp = row[0]
-        url = row[1] or ""
-        title = row[2] or "(No title)"
-        transition = row[3]
-        visit_duration = row[4] or 0
-        visit_count = row[5] or 0
-        typed_count = row[6] or 0
-        
-        # Extract core transition type (lower 8 bits)
-        core_transition = transition & 0xFF
-        transition_name = transition_types.get(core_transition, f"Unknown({core_transition})")
-        
-        # Convert timestamp
-        try:
-            unix_microseconds, iso_datetime = convert_chromium_timestamp(chromium_timestamp)
-        except TimestampValidationError as e:
-            validation_errors.append(f"Entry {idx + 1}: {e}")
-            if len(validation_errors) <= 3:  # Only store first few errors
-                continue
-            else:
-                break  # Too many errors, likely a systematic issue
-        
-        # Construct message
-        message = f"Visited: {title}"
-        
-        rows.append({
-            'timestamp': unix_microseconds,
-            'datetime': iso_datetime,
-            'timestamp_desc': 'Visit Time',
-            'message': message,
-            'url': url,
-            'title': title,
-            'visit_type': transition_name,
-            'visit_duration_us': visit_duration,
-            'total_visits': visit_count,
-            'typed_count': typed_count,
-            'data_type': f'{browser_name.lower()}:history:visit'
-        })
-    
-    conn.close()
-    
-    # Report validation errors if any
-    if validation_errors:
-        print(f"Warning: Found {len(validation_errors)} timestamp validation errors:", file=sys.stderr)
-        for error in validation_errors[:3]:
-            print(f"  {error}", file=sys.stderr)
-        if len(validation_errors) > 3:
-            print(f"  ... and {len(validation_errors) - 3} more errors", file=sys.stderr)
-        print(f"Continuing with {len(rows)} valid entries...", file=sys.stderr)
-    
-    # Write CSV
-    fieldnames = [
-        'timestamp', 'datetime', 'timestamp_desc', 'message',
-        'url', 'title', 'visit_type', 'visit_duration_us',
-        'total_visits', 'typed_count', 'data_type'
-    ]
-    write_timesketch_csv(output_csv, fieldnames, rows)
-    
-    return len(rows)
-
-
-def extract_gecko_history(db_path: str, output_csv: str, browser_name: Optional[str] = None) -> int:
-    """
-    Extract browser history from Gecko-based browsers (Firefox) and convert to Timesketch CSV.
-    Works with Firefox and Firefox derivatives (Waterfox, LibreWolf, etc.)
-    
-    Args:
-        db_path: Path to Gecko places.sqlite database
-        output_csv: Path to output CSV file
-        browser_name: Optional custom name for data_type field (default: "Firefox")
-        
-    Returns:
-        Number of entries processed
-        
-    Raises:
-        DatabaseValidationError: If database validation fails
-        sqlite3.Error: If database query fails
-    """
-    if browser_name is None:
-        browser_name = "Firefox"
-    
-    # Connect to database
-    conn = connect_database_readonly(db_path)
-    
-    # Validate schema
-    validate_browser_schema(conn, ['moz_historyvisits', 'moz_places'], browser_name)
-    
-    cursor = conn.cursor()
-    
-    # Query to extract history visits with URL information
-    query = """
-    SELECT 
-        moz_historyvisits.visit_date as timestamp,
-        moz_places.url,
-        moz_places.title,
-        moz_places.description,
-        moz_historyvisits.visit_type,
-        moz_historyvisits.from_visit
-    FROM moz_historyvisits
-    JOIN moz_places ON moz_historyvisits.place_id = moz_places.id
-    ORDER BY moz_historyvisits.visit_date
-    """
-    
-    try:
-        cursor.execute(query)
-        results = cursor.fetchall()
-    except sqlite3.Error as e:
-        conn.close()
-        raise sqlite3.Error(f"Error querying {browser_name} history: {e}")
-    
-    # Visit type mapping (Firefox visit types)
-    visit_types = {
-        1: "Link",
-        2: "Typed",
-        3: "Bookmark",
-        4: "Embed",
-        5: "Redirect_Permanent",
-        6: "Redirect_Temporary",
-        7: "Download",
-        8: "Framed_Link",
-        9: "Reload"
-    }
-    
-    rows = []
-    validation_errors = []
-    
-    for idx, row in enumerate(results):
-        timestamp_us = row[0]
-        url = row[1] or ""
-        title = row[2] or "(No title)"
-        description = row[3] or ""
-        visit_type_id = row[4]
-        
-        visit_type_name = visit_types.get(visit_type_id, f"Unknown({visit_type_id})")
-        
-        # Convert timestamp
-        try:
-            unix_microseconds, iso_datetime = convert_gecko_timestamp(timestamp_us)
-        except TimestampValidationError as e:
-            validation_errors.append(f"Entry {idx + 1}: {e}")
-            if len(validation_errors) <= 3:
-                continue
-            else:
-                break
-        
-        # Construct message
-        message = f"Visited: {title}"
-        if description:
-            message += f" - {description}"
-        
-        rows.append({
-            'timestamp': unix_microseconds,
-            'datetime': iso_datetime,
-            'timestamp_desc': 'Visit Time',
-            'message': message,
-            'url': url,
-            'title': title,
-            'visit_type': visit_type_name,
-            'data_type': f'{browser_name.lower()}:history:visit'
-        })
-    
-    conn.close()
-    
-    # Report validation errors if any
-    if validation_errors:
-        print(f"Warning: Found {len(validation_errors)} timestamp validation errors:", file=sys.stderr)
-        for error in validation_errors[:3]:
-            print(f"  {error}", file=sys.stderr)
-        if len(validation_errors) > 3:
-            print(f"  ... and {len(validation_errors) - 3} more errors", file=sys.stderr)
-        print(f"Continuing with {len(rows)} valid entries...", file=sys.stderr)
-    
-    # Write CSV
-    fieldnames = [
-        'timestamp', 'datetime', 'timestamp_desc', 'message',
-        'url', 'title', 'visit_type', 'data_type'
-    ]
-    write_timesketch_csv(output_csv, fieldnames, rows)
-    
-    return len(rows)
-
-
-def extract_webkit_history(db_path: str, output_csv: str, browser_name: Optional[str] = None) -> int:
-    """
-    Extract browser history from WebKit-based browsers (Safari) and convert to Timesketch CSV.
-    
-    Args:
-        db_path: Path to Safari History.db database
-        output_csv: Path to output CSV file
-        browser_name: Optional custom name for data_type field (default: "Safari")
-        
-    Returns:
-        Number of entries processed
-        
-    Raises:
-        DatabaseValidationError: If database validation fails
-        sqlite3.Error: If database query fails
-    """
-    if browser_name is None:
-        browser_name = "Safari"
-    
-    # Connect to database
-    conn = connect_database_readonly(db_path)
-    
-    # Validate schema
-    validate_browser_schema(conn, ['history_visits', 'history_items'], browser_name)
-    
-    cursor = conn.cursor()
-    
-    # Query to extract history visits with URL information
-    query = """
-    SELECT 
-        history_visits.visit_time,
-        history_items.url,
-        history_items.title,
-        history_visits.title as visit_title
-    FROM history_visits
-    JOIN history_items ON history_visits.history_item = history_items.id
-    ORDER BY history_visits.visit_time
-    """
-    
-    try:
-        cursor.execute(query)
-        results = cursor.fetchall()
-    except sqlite3.Error as e:
-        conn.close()
-        raise sqlite3.Error(f"Error querying {browser_name} history: {e}")
-    
-    rows = []
-    validation_errors = []
-    
-    for idx, row in enumerate(results):
-        webkit_timestamp = row[0]
-        url = row[1] or ""
-        title = row[2] or row[3] or "(No title)"
-        
-        # Convert timestamp
-        try:
-            unix_microseconds, iso_datetime = convert_webkit_timestamp(webkit_timestamp)
-        except TimestampValidationError as e:
-            validation_errors.append(f"Entry {idx + 1}: {e}")
-            if len(validation_errors) <= 3:
-                continue
-            else:
-                break
-        
-        # Construct message
-        message = f"Visited: {title}"
-        
-        rows.append({
-            'timestamp': unix_microseconds,
-            'datetime': iso_datetime,
-            'timestamp_desc': 'Visit Time',
-            'message': message,
-            'url': url,
-            'title': title,
-            'data_type': f'{browser_name.lower()}:history:visit'
-        })
-    
-    conn.close()
-    
-    # Report validation errors if any
-    if validation_errors:
-        print(f"Warning: Found {len(validation_errors)} timestamp validation errors:", file=sys.stderr)
-        for error in validation_errors[:3]:
-            print(f"  {error}", file=sys.stderr)
-        if len(validation_errors) > 3:
-            print(f"  ... and {len(validation_errors) - 3} more errors", file=sys.stderr)
-        print(f"Continuing with {len(rows)} valid entries...", file=sys.stderr)
-    
-    # Write CSV
-    fieldnames = [
-        'timestamp', 'datetime', 'timestamp_desc', 'message',
-        'url', 'title', 'data_type'
-    ]
-    write_timesketch_csv(output_csv, fieldnames, rows)
-    
-    return len(rows)
-
-
-def generate_default_output_filename(browser_type: str, input_path: str) -> str:
-    """
-    Generate a sensible default output filename based on browser type and input.
-    
-    Args:
-        browser_type: Browser type (gecko, chromium, webkit)
-        input_path: Input database path
-        
-    Returns:
-        Generated output filename
-    """
-    # Extract browser name from path if possible
-    path_lower = input_path.lower()
-    
-    browser_names = {
-        'firefox': 'firefox',
-        'chrome': 'chrome',
-        'edge': 'edge',
-        'brave': 'brave',
-        'opera': 'opera',
-        'vivaldi': 'vivaldi',
-        'safari': 'safari',
-    }
-    
-    detected_name = None
-    for name_key, name_value in browser_names.items():
-        if name_key in path_lower:
-            detected_name = name_value
-            break
-    
-    if detected_name:
-        return f"{detected_name}_history_timesketch.csv"
-    else:
-        return f"{browser_type}_history_timesketch.csv"
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(
-        description='Convert browser history to Timesketch CSV format',
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Browser Engine Types:
-  gecko, firefox      - Gecko-based browsers (Firefox, Waterfox, LibreWolf, etc.)
-  chromium            - Chromium-based browsers (Chrome, Edge, Brave, Opera, Vivaldi, etc.)
-  webkit, safari      - WebKit-based browsers (Safari)
-  auto                - Auto-detect browser type from database schema
-
-All Chromium-based browsers (Chrome, Edge, Brave, Opera, Vivaldi) use identical database 
-schemas and can be processed with the "chromium" option. Use --browser-name to customize 
-the label in the output if needed.
-
-HOW TO FIND YOUR PROFILE PATH:
-  Firefox:
-    1. Open Firefox and type: about:support
-    2. Look for "Profile Folder" or "Profile Directory"
-    3. Click "Open Folder" button or note the path
-    4. The places.sqlite file is in this directory
-    
-  Chromium browsers (Chrome/Edge/Brave/etc.):
-    1. Open browser and type: chrome://version/
-       (or edge://version/, brave://version/, etc.)
-    2. Look for "Profile Path" - this shows the full path
-    3. The History file (no extension) is in this directory
-    
-  Safari:
-    Always at: ~/Library/Safari/History.db
-
-Example usage:
-  # Auto-detect browser type
-  python browser2timesketch.py -i ~/.mozilla/firefox/xyz.default/places.sqlite
-  
-  # Firefox with custom output
-  python browser2timesketch.py -b firefox -i ~/.mozilla/firefox/xyz.default/places.sqlite -o firefox.csv
-  
-  # Any Chromium browser (Chrome, Edge, Brave, etc.)
-  python browser2timesketch.py -b chromium -i ~/.config/google-chrome/Default/History -o output.csv
-  
-  # Chromium browser with custom label
-  python browser2timesketch.py -b chromium --browser-name "Brave" -i ~/.config/BraveSoftware/Brave-Browser/Default/History
-  
-  # Safari (macOS)
-  python browser2timesketch.py -b safari -i ~/Library/Safari/History.db
-
-Database Locations:
-  Gecko/Firefox:
-    Linux:   ~/.mozilla/firefox/<profile>/places.sqlite
-    macOS:   ~/Library/Application Support/Firefox/Profiles/<profile>/places.sqlite
-    Windows: %APPDATA%\\Mozilla\\Firefox\\Profiles\\<profile>\\places.sqlite
-  
-  Chromium (Chrome/Edge/Brave/Opera/Vivaldi):
-    Chrome Linux:   ~/.config/google-chrome/Default/History
-    Chrome macOS:   ~/Library/Application Support/Google/Chrome/Default/History
-    Chrome Windows: %LOCALAPPDATA%\\Google\\Chrome\\User Data\\Default\\History
-    
-    Edge Windows:   %LOCALAPPDATA%\\Microsoft\\Edge\\User Data\\Default\\History
-    Edge macOS:     ~/Library/Application Support/Microsoft Edge/Default/History
-    
-    Brave Linux:    ~/.config/BraveSoftware/Brave-Browser/Default/History
-    Brave macOS:    ~/Library/Application Support/BraveSoftware/Brave-Browser/Default/History
-    Brave Windows:  %LOCALAPPDATA%\\BraveSoftware\\Brave-Browser\\User Data\\Default\\History
-  
-  WebKit/Safari:
-    macOS:   ~/Library/Safari/History.db
-
-Note: The script uses read-only mode to avoid database lock issues, but closing 
-the browser is still recommended for best results.
-        """
-    )
-    
-    parser.add_argument(
-        '-b', '--browser',
-        choices=['gecko', 'firefox', 'chromium', 'webkit', 'safari', 'auto'],
-        default='auto',
-        help='Browser engine type (default: auto-detect)'
-    )
-    
-    parser.add_argument(
-        '-i', '--input',
-        required=True,
-        help='Path to browser history database'
-    )
-    
-    parser.add_argument(
-        '-o', '--output',
-        help='Output CSV file path (default: auto-generated based on browser type)'
-    )
-    
-    parser.add_argument(
-        '--browser-name',
-        help='Custom browser name for the data_type field (e.g., "Chrome", "Brave", "Edge")'
-    )
-    
-    args = parser.parse_args()
-    
-    try:
-        # Validate database file
-        print(f"Validating database: {args.input}")
-        validate_sqlite_database(args.input)
-        print("✓ Database is valid SQLite file")
-        
-        # Detect or validate browser type
-        browser_type = args.browser.lower()
-        
-        if browser_type == 'auto':
-            print("Auto-detecting browser type...")
-            browser_type = detect_browser_type(args.input)
-            print(f"✓ Detected browser type: {browser_type}")
-        else:
-            # Normalize aliases
-            if browser_type == 'firefox':
-                browser_type = 'gecko'
-            elif browser_type == 'safari':
-                browser_type = 'webkit'
-            
-            # Validate that the database matches the specified type
-            detected_type = detect_browser_type(args.input)
-            if detected_type != browser_type:
-                print(f"Warning: You specified '{args.browser}' but database appears to be '{detected_type}'", 
-                      file=sys.stderr)
-                response = input("Continue anyway? [y/N]: ")
-                if response.lower() != 'y':
-                    return 1
-        
-        # Generate output filename if not provided
-        if args.output:
-            output_csv = args.output
-        else:
-            output_csv = generate_default_output_filename(browser_type, args.input)
-            print(f"Using output filename: {output_csv}")
-        
-        # Extract history based on browser type
-        print(f"Extracting history from {browser_type} database...")
-        
-        if browser_type == 'gecko':
-            num_entries = extract_gecko_history(args.input, output_csv, args.browser_name)
-        elif browser_type == 'chromium':
-            num_entries = extract_chromium_history(args.input, output_csv, args.browser_name)
-        elif browser_type == 'webkit':
-            num_entries = extract_webkit_history(args.input, output_csv, args.browser_name)
-        else:
-            raise ValueError(f"Unknown browser type: {browser_type}")
-        
-        print(f"\n✓ Successfully converted {num_entries} history entries")
-        print(f"✓ Output saved to: {output_csv}")
-        return 0
-        
-    except DatabaseValidationError as e:
-        print(f"Database Validation Error: {e}", file=sys.stderr)
-        return 1
-    except BrowserDetectionError as e:
-        print(f"Browser Detection Error: {e}", file=sys.stderr)
-        return 1
-    except TimestampValidationError as e:
-        print(f"Timestamp Validation Error: {e}", file=sys.stderr)
-        print("This indicates a systematic problem with timestamp conversion.", file=sys.stderr)
-        return 1
-    except sqlite3.Error as e:
-        print(f"Database Error: {e}", file=sys.stderr)
-        return 1
-    except FileNotFoundError as e:
-        print(f"File Error: {e}", file=sys.stderr)
-        return 1
-    except KeyboardInterrupt:
-        print("\nOperation cancelled by user", file=sys.stderr)
-        return 130
-    except Exception as e:
-        print(f"Unexpected Error: {e}", file=sys.stderr)
-        import traceback
-        traceback.print_exc()
-        return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())