SafeSurf

SafeSurf is a privacy and browsing safety environment for defensive everyday use. It provides a persistent command shell for checking website reputation, cleaning URLs, launching a browser with safer defaults, reviewing exposure lookups, managing shell-native settings and profiles, and exporting reports.

The project is intentionally plain. It behaves like a practical command shell instead of a dashboard or themed terminal UI. Output is text-first, readable, and structured for daily use.

Philosophy

SafeSurf is built around a few core ideas:

• Keep the interaction shell-like and low-friction.
• Prefer realistic checks and honest limitations over dramatic claims.
• Treat privacy features as risk reduction, not anonymity guarantees.
• Store useful history and reports so the shell becomes an operational workspace.

Features

• Interactive shell loop with plain prompt and persistent line history
• Website scanning with URL normalization and trust scoring
• DNS, SSL, redirect, header, tracking, WHOIS, and heuristic analysis
• Public breach reputation analysis with local and remote catalog matching
• URL cleaning with tracker removal and clipboard copy support
• Integrated browser window connected to the shell, with navigation controls and session tracking
• External Chromium-based browser launching as a fallback mode
• Leak lookup support for defensive informational checks
• Local threat-feed refresh command for blacklist and breach catalogs
• Nested settings management entirely from inside the shell
• Named SafeSurf behavior profiles
• Persistent SQLite history and saved report files

Project Structure

SafeSurf/
|-- main.py
|-- launcher.py
|-- requirements.txt
|-- README.md
|-- config/
|   |-- settings.json
|   |-- defaults.json
|   |-- profiles.json
|   `-- browser_profiles.json
|-- core/
|   |-- __init__.py
|   |-- shell.py
|   |-- command_router.py
|   |-- parser.py
|   |-- app_state.py
|   |-- logger.py
|   |-- settings_manager.py
|   |-- profile_manager.py
|   |-- browser_launcher.py
|   |-- output.py
|   `-- utils.py
|-- commands/
|   |-- __init__.py
|   |-- scan.py
|   |-- browser.py
|   |-- clean.py
|   |-- feeds.py
|   |-- leaks.py
|   |-- history.py
|   |-- reports.py
|   |-- settings.py
|   |-- profiles.py
|   |-- help_cmd.py
|   `-- system.py
|-- modules/
|   |-- __init__.py
|   |-- site_reputation.py
|   |-- dns_tools.py
|   |-- ssl_tools.py
|   |-- whois_tools.py
|   |-- headers_analysis.py
|   |-- redirects_analysis.py
|   |-- tracking_analysis.py
|   |-- url_cleaner.py
|   |-- leak_checker.py
|   |-- public_breach_checker.py
|   |-- scoring.py
|   |-- threat_feeds.py
|   `-- report_builder.py
|-- services/
|   |-- __init__.py
|   |-- api_clients.py
|   |-- cache.py
|   |-- validators.py
|   `-- storage.py
|-- ui/
|   |-- __init__.py
|   `-- integrated_browser.py
`-- data/
    |-- history.db
    |-- reports/
    |-- sessions/
    `-- cache/

Requirements

• Python 3.12+
• PySide6 for the integrated browser window
• A Chromium-based browser is optional as a fallback mode
• Network access for live site scans and leak lookups

Install dependencies:

pip install -r requirements.txt

Startup

Run the interactive shell from the project root:

python main.py

or:

python launcher.py

Expected startup:

SafeSurf Shell
Type 'help' for commands.
C:\Users\<username> ~ SafeSurf >

Shell Usage

Examples:

scan https://example.com
scan --full https://example.com
clean https://example.com/?utm_source=test&fbclid=abc
clean --copy --explain https://example.com/?utm_source=test
browser https://example.com
browser --profile hardened https://example.com
browser --blank
browser --detach https://example.com
feeds refresh
leaks lookup someone@example.com
settings list
settings set browser.incognito true
profile use strict
history list
report export last --format md

Commands

scan

Scans a URL or domain, normalizes it, runs trust and privacy checks, and computes a score.

Options:

• --full includes technical findings and score breakdown
• --no-whois disables WHOIS lookup for this scan
• --no-headers disables header analysis for this scan
• --no-ssl disables SSL inspection for this scan
• --no-dns disables DNS lookup for this scan
• --json prints raw structured output

browser

Launches the SafeSurf integrated browser by default. The shell waits for the browser window to close, then returns to the prompt with the session recorded. If integrated mode is unavailable and fallback is enabled, SafeSurf can fall back to an external browser.

Options:

• --profile NAME use a named browser profile from config/browser_profiles.json
• --blank launch about:blank
• --temp-profile force a temporary user data directory
• --incognito force incognito mode
• --direct bypass the scan gate if allowed by settings
• --scan force a prelaunch scan
• --detach requests a detached session; in integrated mode SafeSurf falls back to an external browser if fallback is enabled

clean

Removes common tracking parameters and normalizes a URL.

Options:

• --copy copy the cleaned URL to the clipboard when possible
• --explain show removed parameters and HTTPS suggestion
• --preview show the cleaned target prominently
• --json print structured output

leaks

Performs defensive informational exposure lookups.

Subcommands:

• leaks lookup [--source auto|leakcheck|xon] <value>
• leaks history

feeds

Refreshes SafeSurf's local threat feeds from public catalog sources.

Options:

• refresh updates local feed files
• --blacklist refresh only the SafeSurf blacklist under extra/safesurf-bl.txt
• --breaches refresh only the local breach catalog under extra/safesurf_breachreputation.txt
• --json prints structured output

history

Works with persistent command history stored in SQLite.

Subcommands:

• history list
• history show <ref>
• history search <term>
• history delete <id>
• history clear

report

Exports or displays reports from history or previously saved report records.

Subcommands:

• report list
• report show <ref>
• report export <ref> [--format txt|md|json]

settings

Manages nested configuration from inside the shell.

Examples:

settings list
settings get browser.incognito
settings set browser.incognito true
settings set scan.timeout 15
settings reset browser
settings export
settings import settings.export.json
settings reload

profile

Applies grouped SafeSurf behavior presets.

Built-in profiles:

• default
• strict
• minimal
• research
• private

Examples:

profile list
profile use strict
profile create research2
profile clone strict safer
profile show private

Shell control commands

• help
• clear
• reload
• exit
• quit
• back
• home

Settings Model

SafeSurf settings are stored in JSON and merged from defaults plus user overrides. Core sections include:

• shell
• scan
• scoring
• browser
• leaks
• reports
• history
• logging
• clipboard

The shell exposes these settings through settings get, settings set, settings reset, settings export, and settings import.

Useful integrated-browser settings:

• browser.ui_theme supports ocean, graphite, sand, midnight, forest, ember, slate, ice, olive, or rose
• browser.show_activity_panel enables the live SafeSurf activity panel
• browser.inspect_page_source enables HTML source inspection after page load
• browser.block_suspicious_source blocks pages whose source looks suspicious
• browser.redact_detected_indicators keeps suspicious endpoint indicators partially redacted
• browser.silence_js_console hides noisy page console warnings from the terminal
• browser.log_to_shell mirrors browser activity logs into the shell in real time
• browser.security_level controls the integrated browser hardening level
• leaks.enable_public_breach_history toggles public domain breach-history matching during scans
• browser.block_private_network blocks localhost, .local, and private-network IP targets
• browser.block_raw_ip_hosts blocks direct raw-IP browsing targets
• browser.block_dangerous_schemes blocks non-web schemes such as file:, data:, or javascript:
• browser.block_suspicious_ports blocks navigation to higher-risk ports
• browser.https_only_mode optionally denies plain HTTP navigation

Browser Profiles

Browser launch profiles define runtime behavior such as:

• incognito mode
• temporary profile usage
• extension disabling
• sync disabling
• background networking limits
• speculative prefetch limits
• blank startup behavior
• prelaunch scan requirement
• custom Chromium flags

In integrated mode, SafeSurf uses an embedded Qt WebEngine browser window with:

• back, forward, reload, home, and address bar controls
• a SafeSurf home screen
• session-level visited URL tracking
• real-time SafeSurf activity panel inside the browser window
• toolbar buttons with local SVG icons
• in-browser Settings page via safesurf://settings
• one-click log panel show/hide from the toolbar
• source inspection for suspicious collection or exfiltration behavior
• popup blocking and stricter in-browser security defaults
• private-network and raw-IP destination blocking
• permission denial for sensitive browser features unless explicitly relaxed in settings
• a dedicated Blocked by SafeSurf page with findings and indicators
• shell return after the browser window is closed
• optional fallback to an external browser

These profiles change browser behavior only. They do not provide anonymity, sandboxing, or guaranteed tracking prevention.

Reports

Reports are stored under data/reports/ and can be exported as:

• plain text
• Markdown
• JSON

Reports are derived from stored command details, so scans, browser launches, cleaned URLs, and leak lookups can all be turned into saved artifacts.

History

SafeSurf uses SQLite in data/history.db to persist:

• scans
• cleaned URLs
• browser launches
• leak lookups
• timestamps
• scores
• classifications
• profile information

Defensive Use Disclaimer

SafeSurf is designed for defensive and informational use only. It does not perform offensive actions, bypass protections, exploit targets, or provide anonymity guarantees. Exposure lookup support is intended for legal, authorized self-checks or organizational defensive workflows.

Limitations

• Live scan quality depends on network reachability and third-party responses.
• WHOIS availability varies by TLD and registrar.
• Integrated browser mode depends on PySide6 Qt WebEngine support being available.
• External fallback mode depends on an installed Chromium-based browser.
• Leak lookup endpoints may change behavior or rate-limit requests over time.
• This shell reduces browsing risk but cannot determine trust with certainty.

Future Improvements

• More detailed browser profile management commands from inside the shell
• Optional confirmation prompts for destructive history actions
• Better pager integration for very long technical results
• Configurable command aliases stored in settings
• Optional offline domain reputation lists
• More granular report templates