Metadata-Version: 2.4
Name: safeweb
Version: 1.0.5
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)

Unzip the folder, then run:

    cd safeweb-cli
    ./safeweb_run.sh list

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

All subsequent commands use `./safeweb_run.sh`:

    ./safeweb_run.sh run-tests -b chrome -t 1
    ./safeweb_run.sh analyze
    ./safeweb_run.sh recommend
    ./safeweb_run.sh export -f csv

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

pipx is the recommended way to install CLI tools on macOS. It automatically creates an isolated environment so there are no conflicts with your system Python.

    pipx install safeweb

If pipx is not installed:

    brew install pipx
    pipx install safeweb

Then run from any folder:

    cd ~/your-project-folder
    safeweb list
    safeweb run-tests -b chrome -t 1
    safeweb analyze

Results are saved in a `results/` folder inside whatever directory you run the commands from. Always run all safeweb commands from the same folder so they share the same data.

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

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

---

## Commands

Note: Zip users run `./safeweb_run.sh <command>`. pipx/pip users run `safeweb <command>`. The commands and options are identical.

### 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
    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 -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 files

Zip users: results/ is inside the safeweb-cli folder.
pipx users: results/ is created in whatever folder you run safeweb from.

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 -- pipx (easiest, no files needed):

    pipx install safeweb

Option 2 -- Zip:

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

Recipient runs:

    unzip safeweb-cli.zip
    cd safeweb-cli
    ./safeweb_run.sh 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 (zip)         Delete venv/ folder and re-run ./safeweb_run.sh 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 data
    safeweb export -f csv

---

## License

Educational and research use -- Capstone Project 2026
