safeweb 1.0.2

Browser safety and sustainability testing tool

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