safeweb 1.0.0__tar.gz

safeweb-1.0.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include WORKFLOW_GUIDE.md
+include requirements.txt
+include config.py
+include safeweb_run.sh
+include test_install.sh
+include validate_data.py
+recursive-include src *.py
+recursive-include results .gitkeep
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.db
+global-exclude *.csv
+global-exclude *.json
+global-exclude *.xlsx
+global-exclude .DS_Store
+prune venv
+prune safeweb.egg-info

safeweb-1.0.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: safeweb
+Version: 1.0.0
+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_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:
+
+    ./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: pip install
+
+    pip install safeweb-1.0.0.tar.gz
+    cd ~/your-project-folder
+    safeweb list
+
+All commands work the same way -- just replace `./safeweb_run.sh` with `safeweb`. Results are saved in a `results/` folder created in whatever directory you run the commands from. 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
+
+Need help? Run `safeweb --help` or `safeweb <command> --help`
+
+---
+
+## Commands
+
+### list -- Show installed browsers
+
+    ./safeweb_run.sh list
+
+Detects which browsers are installed in /Applications/ on your Mac.
+
+---
+
+### run-tests -- Run browser tests
+
+    ./safeweb_run.sh 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.sh run-tests -b chrome -t 1
+
+    # Two browsers, custom query
+    ./safeweb_run.sh run-tests -b chrome firefox -q "climate change" -t 3
+
+    # Full research study (25 trials)
+    ./safeweb_run.sh run-tests -t 25
+
+    # Preview what would run
+    ./safeweb_run.sh 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_run.sh analyze
+    ./safeweb_run.sh analyze -b chrome          # Single browser
+    ./safeweb_run.sh 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_run.sh 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_run.sh compare chrome:google firefox:duckduckgo
+
+Compares two browser:engine configurations with detailed per-metric breakdown and weighted scores.
+
+---
+
+### export -- Export data
+
+    ./safeweb_run.sh export -f csv              # CSV (default)
+    ./safeweb_run.sh export -f json
+    ./safeweb_run.sh export -f excel
+    ./safeweb_run.sh export -f csv -o my_data.csv
+
+Exports to results/exports/. Includes all 35+ metrics per test.
+
+---
+
+### report -- Generate markdown report
+
+    ./safeweb_run.sh report
+    ./safeweb_run.sh report --charts            # Include PNG charts
+    ./safeweb_run.sh report -o my_report.md
+
+Saves to results/reports/.
+
+---
+
+### explain -- Understand the scoring methodology
+
+    ./safeweb_run.sh 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_run.sh 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_run.sh list
+
+---
+
+## Example: Full Workflow
+
+    # 1. See what browsers are available
+    ./safeweb_run.sh list
+
+    # 2. Quick test with a custom query
+    ./safeweb_run.sh run-tests -b chrome firefox -q "renewable energy" -t 3
+
+    # 3. View comparison
+    ./safeweb_run.sh analyze
+
+    # 4. See AI energy impact
+    ./safeweb_run.sh analyze --ai-comparison
+
+    # 5. Get a recommendation
+    ./safeweb_run.sh recommend
+
+    # 6. Export for Excel/report
+    ./safeweb_run.sh export -f excel
+    ./safeweb_run.sh report --charts
+
+---
+
+## License
+
+Educational and research use -- Capstone Project 2026

safeweb-1.0.0/README.md

@@ -0,0 +1,273 @@
+# 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_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:
+
+    ./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: pip install
+
+    pip install safeweb-1.0.0.tar.gz
+    cd ~/your-project-folder
+    safeweb list
+
+All commands work the same way -- just replace `./safeweb_run.sh` with `safeweb`. Results are saved in a `results/` folder created in whatever directory you run the commands from. 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
+
+Need help? Run `safeweb --help` or `safeweb <command> --help`
+
+---
+
+## Commands
+
+### list -- Show installed browsers
+
+    ./safeweb_run.sh list
+
+Detects which browsers are installed in /Applications/ on your Mac.
+
+---
+
+### run-tests -- Run browser tests
+
+    ./safeweb_run.sh 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.sh run-tests -b chrome -t 1
+
+    # Two browsers, custom query
+    ./safeweb_run.sh run-tests -b chrome firefox -q "climate change" -t 3
+
+    # Full research study (25 trials)
+    ./safeweb_run.sh run-tests -t 25
+
+    # Preview what would run
+    ./safeweb_run.sh 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_run.sh analyze
+    ./safeweb_run.sh analyze -b chrome          # Single browser
+    ./safeweb_run.sh 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_run.sh 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_run.sh compare chrome:google firefox:duckduckgo
+
+Compares two browser:engine configurations with detailed per-metric breakdown and weighted scores.
+
+---
+
+### export -- Export data
+
+    ./safeweb_run.sh export -f csv              # CSV (default)
+    ./safeweb_run.sh export -f json
+    ./safeweb_run.sh export -f excel
+    ./safeweb_run.sh export -f csv -o my_data.csv
+
+Exports to results/exports/. Includes all 35+ metrics per test.
+
+---
+
+### report -- Generate markdown report
+
+    ./safeweb_run.sh report
+    ./safeweb_run.sh report --charts            # Include PNG charts
+    ./safeweb_run.sh report -o my_report.md
+
+Saves to results/reports/.
+
+---
+
+### explain -- Understand the scoring methodology
+
+    ./safeweb_run.sh 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_run.sh 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_run.sh list
+
+---
+
+## Example: Full Workflow
+
+    # 1. See what browsers are available
+    ./safeweb_run.sh list
+
+    # 2. Quick test with a custom query
+    ./safeweb_run.sh run-tests -b chrome firefox -q "renewable energy" -t 3
+
+    # 3. View comparison
+    ./safeweb_run.sh analyze
+
+    # 4. See AI energy impact
+    ./safeweb_run.sh analyze --ai-comparison
+
+    # 5. Get a recommendation
+    ./safeweb_run.sh recommend
+
+    # 6. Export for Excel/report
+    ./safeweb_run.sh export -f excel
+    ./safeweb_run.sh report --charts
+
+---
+
+## License
+
+Educational and research use -- Capstone Project 2026