BrowserDig

BrowserDig — Browser Digital Information Gatherer — is a modern, cross-platform browser forensics and artifact analysis tool built in Python.
Think of it as the linPEAS equivalent for web browsers: portable, lightweight, rules-driven, and investigator-friendly.

BrowserDig is an open-source browser forensics utility designed for digital forensics, incident response (DFIR), threat hunting, OSINT, and privacy audits. It extracts, normalizes, and correlates artifacts from popular web browsers including Google Chrome, Chromium, Microsoft Edge, Brave, Opera, Vivaldi, Firefox, and Safari.

Unlike many forensic utilities with heavy dependencies, BrowserDig is designed to be lightweight and portable — it can run directly against a live browser profile folder or an offline ZIP archive of user data, making it ideal for both field investigations and automated pipelines.

Why BrowserDig?

• Cross-platform: Works on Windows, Linux, and macOS
• Portable: Built into a single binary using PyInstaller, no Python installation required
• Forensic-safe: Read-only operations ensure no modifications to source data
• Fast indexing: Optimized SQLite handling for large browser databases
• Rule-driven intelligence: Extend detection logic easily with custom rules, similar to Sigma for browser artifacts

Features

• Multi-Browser Support: Chrome, Chromium, Edge, Brave, Opera, Vivaldi, Firefox, and Safari (macOS)
• Offline Analysis: Works entirely offline with ZIP archives or local directories - can analyze folders or ZIP dumps of browser profiles
• Comprehensive Artifact Parsing:
  • History (visits, downloads, top sites)
  • Cookies
  • Saved logins
  • Bookmarks
  • Preferences & extensions
  • Cache metadata
• Rule-Based Detection: Flexible rule engine for IOCs and suspicious patterns, detecting:
  • Malicious or phishing domains
  • Executable downloads
  • Tracker and ad networks
  • Insecure cookies
  • Bulk logins or suspicious behavior
• Multiple Output Formats:
  • JSONL (normalized events timeline)
  • CSV (timeline / artifacts)
  • HTML (one-file forensic report with inline CSS)
  • JSON (findings with severity)
• Minimal Dependencies: Core functionality uses only Python standard library
• Standalone Binary: Single-file executables for Windows, macOS, and Linux built with PyInstaller
• Forensic-Ready: Read-only operation with chain of custody considerations
• Fast Performance: Optimized SQLite handling for large browser databases

Quick Start

Download Pre-built Binary

Download the latest release for your platform from the releases page.

Basic Usage

# Analyze a browser profile dump
browserdig scan --input ./profile.zip --out out/

# Scan browser profiles from a directory
browserdig scan /path/to/browser/profiles

# Force Firefox parsing only
browserdig scan --input ./firefox/ --browser firefox --out results/

# Parse specific artifacts from Chrome
browserdig parse /path/to/chrome/profile --browser chrome --artifact history

# Use custom rules
browserdig scan --input ./dump/ --rules ./rules/ --out findings/

# Generate HTML report from previous analysis
browserdig report --input results.jsonl --format html

Typical Outputs:

• events.jsonl — raw normalized timeline
• timeline.csv — merged chronology
• findings.json — rule hits with severity
• report.html — one-file HTML summary

Installation

From Source

# Clone the repository
git clone https://github.com/browserdig/browserdig.git
cd browserdig

# Install dependencies
pip install -r requirements-build.txt

# Run from source
python -m browserdig --help

Build Binary

# Linux/macOS
./build/build-linux.sh    # or build-macos.sh

# Windows
build\build-windows.bat

# Cross-platform Python script
python build/build.py --clean --analyze

Usage

Command Line Interface

BrowserDig provides several subcommands for different analysis workflows:

Scan Command

Auto-detect and analyze browser profiles:

browserdig scan [INPUT] [OPTIONS]

# Examples
browserdig scan /Users/john/Library/Application\ Support/
browserdig scan evidence.zip --browser chrome --output-dir ./investigation
browserdig scan /mnt/forensic-image/browsers/ --format html --rules custom-rules.yaml

Options:

• --output-dir, -o: Output directory (default: ./browserdig_output)
• --browser: Limit to specific browser (chrome, firefox, safari, edge, brave, opera, vivaldi)
• --format: Output format (json, csv, html, all)
• --rules: Custom rules file (YAML or JSON)
• --enable-yaml: Enable YAML rule support
• --threads: Number of worker threads
• --no-findings: Skip rule evaluation

Parse Command

Parse specific artifacts from browser profiles:

browserdig parse [INPUT] --browser [BROWSER] [OPTIONS]

# Examples
browserdig parse /path/to/chrome/profile --browser chrome --artifact history
browserdig parse /path/to/firefox/profile --browser firefox --artifact cookies --format csv

Options:

• --browser: Browser type (required)
• --artifact: Artifact type (history, cookies, logins, bookmarks, preferences, downloads, all)
• --output-dir, -o: Output directory
• --format: Output format (json, csv)

Report Command

Generate reports from existing analysis data:

browserdig report --input [EVENTS_FILE] --format [FORMAT] [OPTIONS]

# Examples
browserdig report --input results.jsonl --format html --output report.html
browserdig report --input events.jsonl --format timeline --findings findings.json

Rules Command

Validate and test rule files:

browserdig rules test [RULES_FILE] [OPTIONS]

# Examples
browserdig rules test custom-rules.yaml --enable-yaml --verbose
browserdig rules test rules.json

Selftest Command

Run diagnostic tests on sample data:

browserdig selftest [OPTIONS]

# Examples
browserdig selftest --quick
browserdig selftest --output-dir ./selftest-results

Supported Browsers and Artifacts

Browser	History	Cookies	Logins	Bookmarks	Downloads	Preferences
Chrome	✓	✓	✓	✓	✓	✓
Edge	✓	✓	✓	✓	✓	✓
Brave	✓	✓	✓	✓	✓	✓
Opera	✓	✓	✓	✓	✓	✓
Vivaldi	✓	✓	✓	✓	✓	✓
Firefox	✓	✓	✓	✓	✓	✓
Safari	✓	-	-	✓	✓	-

Rule Engine

BrowserDig includes a flexible rule engine for detecting indicators of compromise (IOCs) and suspicious patterns:

Default Rules

The tool includes 12+ default rules covering:

• Known malicious domains
• Suspicious file downloads
• Disabled security features
• Unusual top-level domains
• Bulk download patterns
• Insecure cookie configurations

Custom Rules

Create custom rules in YAML or JSON format:

rules:
  - id: "suspicious_domain"
    name: "Suspicious Domain Access"
    description: "Access to known malicious domains"
    level: "HIGH"
    conditions:
      - field: "domain"
        operator: "in"
        values: ["malware.example.com", "phishing.test"]
      - field: "event_type"
        operator: "equals"
        value: "visit"

  - id: "bulk_downloads"
    name: "Bulk File Downloads"
    description: "Multiple downloads in short timeframe"
    level: "MEDIUM"
    conditions:
      - field: "event_type"
        operator: "equals"
        value: "download"
      - field: "timestamp_utc"
        operator: "time_window"
        value: "1h"
        count: ">10"

Output Formats

JSON Lines (JSONL)

Machine-readable event stream:

{"timestamp_utc": "2024-01-15T10:30:00Z", "browser": "chrome", "event_type": "visit", "url": "https://example.com", "title": "Example Site"}
{"timestamp_utc": "2024-01-15T10:31:00Z", "browser": "chrome", "event_type": "download", "url": "https://example.com/file.pdf", "download_path": "/Users/john/Downloads/file.pdf"}

CSV

Tabular format for spreadsheet analysis:

timestamp_utc,browser,profile,event_type,url,domain,title
2024-01-15T10:30:00Z,chrome,Default,visit,https://example.com,example.com,Example Site
2024-01-15T10:31:00Z,chrome,Default,download,https://example.com/file.pdf,example.com,

HTML Report

Self-contained HTML report with:

• Executive summary with risk breakdown
• Interactive timeline view
• Findings section with detailed analysis
• Browser and artifact statistics

Security Considerations

Forensic Use Authorization

IMPORTANT: BrowserDig is designed for authorized forensic analysis only. Users must:

• Obtain proper legal authorization before analyzing any browser data
• Comply with applicable laws and regulations (GDPR, CCPA, etc.)
• Follow organizational policies for data handling
• Maintain chain of custody documentation

Data Handling

• Read-Only Operation: BrowserDig never modifies input files or browser profiles
• Offline Analysis: No network communication; all processing is local
• Temporary Files: Temporary files are created in secure temporary directories. All temporary data is automatically cleaned up after analysis
• Privacy: Browser artifacts may contain sensitive personal information

Security Features

• Path Traversal Protection: Safe ZIP extraction prevents malicious archives. However, always scan ZIP files with antivirus before analysis. Be cautious with ZIP files from untrusted sources.
• Input Validation: Comprehensive validation of all input data
• Memory Safety: Secure handling of sensitive data in memory
• Error Handling: Graceful failure without exposing system information
• Output Data Security: Generated reports may contain sensitive personal information. Store output files in secure locations with appropriate access controls Consider encryption for sensitive analysis results

Privacy Considerations

Personal Data Handling:

• Browser artifacts contain highly sensitive personal information
• Implement data minimization principles
• Anonymize or pseudonymize data when possible
• Ensure compliance with privacy regulations

Data Processing:

• All processing occurs locally on your system
• No telemetry or usage data is collected
• No internet connection is required or used during analysis
• User data never leaves the local system

Development

Requirements

• Python 3.10 or higher
• PyInstaller (for building binaries)
• PyYAML (optional, for YAML rule support)

Building from Source

# Install development dependencies
pip install -r requirements-build.txt

# Run tests
python -m pytest browserdig/tests/ -v

# Type checking
mypy browserdig/ --ignore-missing-imports

# Code formatting
black browserdig/
isort browserdig/

# Build binary
python build/build.py --clean --analyze

Project Structure

browserdig/
├── browserdig/           # Main package
│   ├── browsers/         # Browser-specific parsers
│   ├── core/            # Core functionality
│   ├── inputs/          # Input handling
│   ├── report/          # Report generation
│   └── rules/           # Rule engine
├── build/               # Build scripts and configuration
├── .github/workflows/   # CI/CD configuration
└── docs/               # Documentation

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (python -m pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Python Software Foundation for the excellent standard library
• The forensics and incident response community for inspiration and feedback
• Contributors and testers who help improve the tool

Support

• Documentation: GitHub Wiki
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Disclaimer

This software is provided "AS IS" without warranty of any kind. Users are solely responsible for ensuring compliance with applicable laws and regulations when using this tool for forensic analysis.

The authors and contributors disclaim all liability for any damages or legal consequences arising from the use or misuse of this software.