Metadata-Version: 2.4
Name: safeweb
Version: 1.0.1
Summary: Browser safety and sustainability testing tool
Author: SafeWeb Project
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: selenium>=4.15.2
Requires-Dist: webdriver-manager>=4.0.1
Requires-Dist: psutil>=5.9.6
Requires-Dist: pandas>=2.1.4
Requires-Dist: numpy>=1.25.2
Requires-Dist: matplotlib>=3.8.2
Requires-Dist: seaborn>=0.13.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: requests>=2.31.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# SafeWeb CLI

Browser Safety and Sustainability Testing Tool

Test and compare web browsers on your Mac to determine which is most energy-efficient and safest. Collects 35+ real-time metrics including CPU, memory, energy consumption, privacy, security, and AI impact.

---

## Quick Start

### Option A: Zip (recommended for most users)

New users -- just run:

    cd safeweb-cli
    safeweb list

The script automatically sets up a virtual environment, installs all dependencies, and detects your installed browsers. No manual setup needed.

All subsequent commands:

    safeweb run-tests -b chrome -t 1
    safeweb analyze
    safeweb recommend
    safeweb export -f csv

### Option B: pip install (any machine, no files needed)

    pip install safeweb
    cd ~/your-project-folder
    safeweb list

All commands work the same way -- just use `safeweb` instead of `safeweb`. Results are saved in a `results/` folder in whatever directory you run the commands from. Always run all commands from the same folder so they share the same data.

    safeweb run-tests -b chrome -t 1
    safeweb analyze
    safeweb recommend
    safeweb export -f csv

Package page: https://pypi.org/project/safeweb/1.0.0/

Need help? Run `safeweb --help` or `safeweb <command> --help`

---

## Commands

> Zip users prefix commands with `safeweb`. Pip users use `safeweb`. Examples below use `safeweb` for brevity.

### list -- Show installed browsers

    safeweb list

Detects which browsers are installed in /Applications/ on your Mac.

---

### run-tests -- Run browser tests

    safeweb run-tests [options]

Options:

    -b    Browsers to test: chrome firefox safari edge opera brave tor  (default: all installed)
    -e    Search engines: google bing duckduckgo yahoo                  (default: all)
    -t    Trials per combination                                         (default: 5)
    -q    Custom search query                                            (default: predefined queries)
    --dry-run   Preview test plan without running

Examples:

    # Quick test (1 trial = ~1 minute)
    safeweb run-tests -b chrome -t 1

    # Two browsers, custom query
    safeweb run-tests -b chrome firefox -q "climate change" -t 3

    # Full research study (25 trials)
    safeweb run-tests -t 25

    # Preview what would run
    safeweb run-tests --dry-run

How long does it take?

    1 trial  = ~1 minute
    5 trials = ~5 minutes  (default)
    25 trials = ~25 minutes  (research)

Each test runs for 30 seconds to collect quality metrics.

---

### analyze -- View results

    safeweb analyze
    safeweb analyze -b chrome          # Single browser
    safeweb analyze --ai-comparison    # AI vs non-AI energy

Shows a comparison table with energy (Wh), CPU%, memory (MB), privacy score, and security score per browser. Also shows CO2 estimates and best-per-category winners.

---

### recommend -- Best browser for your machine

    safeweb recommend

Ranks all tested browser+engine combinations using weighted scoring:

    Energy      40%  -- primary sustainability metric
    Performance 30%  -- CPU, memory, duration
    Privacy     20%  -- cookies, trackers, HTTPS
    Security    10%  -- HTTPS, mixed content, secure cookies

Results are specific to your hardware -- scores are not comparable across different machines.

---

### compare -- Head-to-head comparison

    safeweb compare chrome:google firefox:duckduckgo

Compares two browser:engine configurations with detailed per-metric breakdown and weighted scores.

---

### export -- Export data

    safeweb export -f csv              # CSV (default)
    safeweb export -f json
    safeweb export -f excel
    safeweb export -f csv -o my_data.csv

Exports to results/exports/. Includes all 35+ metrics per test.

---

### report -- Generate markdown report

    safeweb report
    safeweb report --charts            # Include PNG charts
    safeweb report -o my_report.md

Saves to results/reports/.

---

### explain -- Understand the scoring methodology

    safeweb explain

Explains how privacy, security, and sustainability scores are calculated with research citations.

---

## Metrics Collected (35+)

    Category    Metrics
    --------    -------
    CPU         mean, max, min (%)
    Memory      mean MB, max MB, mean %, max %
    Network     bytes sent, bytes received
    Disk        read bytes, write bytes
    Energy      local Wh (CPU + memory + base + display), remote Wh (server + PUE), total Wh
    Privacy     third-party cookies, tracker count, HTTPS, score /10
    Security    mixed content, secure cookies, HTTPS, score /10
    AI          features detected, confidence score
    Test Info   browser, version, engine, query, duration, timestamp, hardware

---

## Energy Calculation Methodology

Local energy (measured per test):

    CPU:          usage% x 0.3W x duration
    Memory:       GB used x 0.02W x duration    (Ghose et al., SIGMETRICS 2018)
    Base system:  15W x duration                (ACM PACS 2005)
    Display:      10W x duration

Remote energy (research-based per query):

    Traditional search:  0.3 Wh x PUE    (Google Official Blog, 2009)
    AI search:           0.24 Wh x PUE   (Google Cloud, 2025)
    PUE:                 Google 1.12, others 1.30

CO2: (total Wh / 1000) x 400g   (IEA global average grid intensity)

---

## Where Data Is Stored

    results/
    +-- database/safe_web.db    All test data (SQLite)
    +-- exports/                CSV / JSON / Excel files
    +-- reports/                Generated markdown reports
    +-- logs/                   Run logs

To reset all data:

    rm results/database/safe_web.db

---

## System Requirements

    OS:       macOS
    Python:   3.8 or higher
    Browsers: At least one installed (Chrome, Firefox, Safari, Edge, Opera, Brave, or Tor)

---

## Sharing This Tool

Option 1 -- Zip (easiest):

    cd ~/Desktop
    zip -r safeweb-cli.zip safeweb-cli

Recipient runs:

    unzip safeweb-cli.zip
    cd safeweb-cli
    safeweb list

Option 2 -- pip package:

    cd ~/Desktop/safeweb-cli
    python3 setup.py sdist
    # share: dist/safeweb-1.0.0.tar.gz

Recipient runs:

    pip install safeweb-1.0.0.tar.gz
    cd ~/any-folder
    safeweb list

---

## Troubleshooting

    Problem                     Fix
    -------                     ---
    No browsers detected        Install Chrome or Firefox; check /Applications/
    Permission denied           chmod +x safeweb_run.sh
    Tests timing out            Use -t 1; check internet connection
    Opera popup                 Accept the data separation popup when it appears
    Module errors               Delete venv/ folder and re-run safeweb list

---

## Example: Full Workflow

    # 1. See what browsers are available
    safeweb list

    # 2. Quick test with a custom query
    safeweb run-tests -b chrome firefox -q "renewable energy" -t 3

    # 3. View comparison
    safeweb analyze

    # 4. See AI energy impact
    safeweb analyze --ai-comparison

    # 5. Get a recommendation
    safeweb recommend

    # 6. Export for Excel/report
    safeweb export -f excel
    safeweb report --charts

---

## License

Educational and research use -- Capstone Project 2026
