safeweb 1.0.4

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)

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

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 for Excel/report
safeweb export -f excel
safeweb report --charts

---

License

Educational and research use -- Capstone Project 2026