Skip to content

Configuration Guide

Jump to bottom
Auto Bot Solutions edited this page Apr 27, 2026 · 1 revision

This document provides comprehensive guidance on configuring the Secure Browser project, including installation, setup, and customization options.

Table of Contents

Overview

Secure Browser provides multiple configuration options to customize the browsing experience. Configuration can be done through:

  • Command-line arguments
  • Configuration files (JSON)
  • In-browser settings panels
  • Environment variables

Installation

Prerequisites

  • Python 3.7 or higher
  • pip (Python package manager)
  • Virtual environment (recommended)

Step-by-Step Installation

1. Clone the Repository

git clone <repository-url>
cd secure_browser

2. Create Virtual Environment

# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

# Windows
python -m venv .venv
.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Verify Installation

python main.py --help

Expected output:

usage: main.py [-h] [--browser {pyqt5,tkinter,webview,search}]

Secure Browser - A secure web browser implementation

optional arguments:
  -h, --help            show this help message and exit
  --browser {pyqt5,tkinter,webview,search}
                        Select browser implementation (default: pyqt5)

Dependency Installation

All Dependencies

pip install -r requirements.txt

Individual Browser Dependencies

# PyQt5 Browser only
pip install PyQt5>=5.15.0 PyQtWebEngine>=5.15.0

# Tkinter Browser only
pip install tkinterweb>=3.0

# WebView Browser only
pip install pywebview>=4.0

System-Specific Installation

Linux

# Install system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv

# Install Qt dependencies for PyQt5
sudo apt-get install python3-pyqt5 python3-pyqt5-dev python3-pyqt5.qtwebengine

# Install Tkinter
sudo apt-get install python3-tk

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python3

# Install Qt dependencies
brew install pyqt5 pyqt5-webengine

Windows

# Install Python from python.org
# During installation, check "Add Python to PATH"

# Install Qt dependencies
pip install PyQt5 PyQtWebEngine

Configuration File

File Location

Configuration is stored in config/user_settings.json.

Default Configuration

{
  "home_url": "https://search.brave.com/",
  "security": {
    "https_enforcement": true,
    "javascript_enabled": true,
    "whitelist": [],
    "blacklist": [],
    "security_headers": {
      "X-Content-Type-Options": "nosniff",
      "X-Frame-Options": "DENY",
      "Content-Security-Policy": "default-src 'self'; script-src 'self'; object-src 'none';"
    },
    "user_agent": "default"
  },
  "proxy": {
    "http": "",
    "https": ""
  },
  "vpn_enabled": false,
  "bookmarks": []
}

Configuration Options

home_url

security.https_enforcement

  • Type: Boolean
  • Default: true
  • Description: Automatically add HTTPS prefix to URLs
  • Example: true

security.javascript_enabled

  • Type: Boolean
  • Default: true
  • Description: Enable JavaScript execution
  • Example: false

security.whitelist

  • Type: Array of strings
  • Default: []
  • Description: Allowed website URLs (prefix matching)
  • Example: ["https://example.com", "https://trusted.org"]

security.blacklist

  • Type: Array of strings
  • Default: []
  • Description: Blocked website URLs (prefix matching)
  • Example: ["http://malicious.com", "http://phishing.net"]

security.security_headers

  • Type: Object
  • Default: See default configuration
  • Description: HTTP security headers
  • Example: See Security Headers section

security.user_agent

  • Type: String
  • Default: "default"
  • Description: Custom user-agent string
  • Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"

proxy.http

proxy.https

vpn_enabled

  • Type: Boolean
  • Default: false
  • Description: Enable VPN (placeholder for future implementation)
  • Example: true

bookmarks

  • Type: Array of strings
  • Default: []
  • Description: Saved bookmark URLs
  • Example: ["https://example.com", "https://docs.python.org"]

Browser-Specific Configuration

PyQt5 Browser Configuration

Settings Panel Configuration

The PyQt5 browser provides a settings panel accessible via the "Settings" button.

Accessing Settings:

  1. Click the "Settings" button in the navigation bar
  2. Modify settings in the dialog
  3. Click "Save" to apply changes

Available Settings:

  • VPN Toggle: Enable/disable VPN (placeholder)
  • JavaScript Checkbox: Enable/disable JavaScript
  • Proxy Input: Configure proxy server

Programmatic Configuration

from src.browsers.hope import Browser
from PyQt5.QtWidgets import QApplication
import sys

app = QApplication(sys.argv)
browser = Browser()

# Set configuration programmatically
browser.use_vpn = False
browser.enable_javascript = True
browser.proxy = "http://proxy.example.com:8080"

browser.show()
sys.exit(app.exec_())

Tkinter Browser Configuration

Settings Window Configuration

The Tkinter browser provides a comprehensive settings window.

Accessing Settings:

  1. Click the "⚙ Settings" button
  2. Navigate to configuration sections
  3. Apply settings using buttons

Configuration Sections:

User-Agent Settings:

  • Enter custom user-agent string
  • Click "Set User-Agent" to apply
  • Enter "default" to reset

Proxy Settings:

  • Enter HTTP proxy URL
  • Enter HTTPS proxy URL
  • Click "Save Proxy" to apply

Security Settings:

  • Toggle JavaScript enable/disable
  • Enter whitelist sites (comma-separated)
  • Enter blacklist sites (comma-separated)
  • Click "Save Security Settings" to apply

Bookmarks:

  • View saved bookmarks
  • Double-click to open bookmark

Programmatic Configuration

import tkinter as tk
from src.browsers.secure_browser import SimpleBrowser

root = tk.Tk()
browser = SimpleBrowser(root)

# Set configuration programmatically
browser.whitelist = ["https://example.com"]
browser.blacklist = ["http://malicious.com"]
browser.javascript_var.set(False)
browser.toggle_javascript()

root.mainloop()

WebView Browser Configuration

Settings Window Configuration

The WebView browser provides a basic settings window.

Accessing Settings:

  1. Click the "⚙ Settings" button
  2. Configure user-agent and proxy
  3. Apply settings

Available Settings:

  • User-Agent: Custom user-agent (limited support)
  • HTTP Proxy: HTTP proxy configuration
  • HTTPS Proxy: HTTPS proxy configuration

Programmatic Configuration

import tkinter as tk
from src.browsers.modern_browser import SimpleBrowser

root = tk.Tk()
browser = SimpleBrowser(root)

# Set proxy via environment variables
import os
os.environ["http_proxy"] = "http://proxy.example.com:8080"
os.environ["https_proxy"] = "https://proxy.example.com:8080"

root.mainloop()

Security Configuration

HTTPS Enforcement

Purpose: Ensure all connections use HTTPS for encryption.

Configuration Methods:

  1. Configuration File:
{
  "security": {
    "https_enforcement": true
  }
}
  1. Programmatic:
# Implemented automatically in load_url methods
if not url.startswith(("http://", "https://")):
    url = "https://" + url

Testing:

JavaScript Control

Purpose: Enable or disable JavaScript execution for security.

Configuration Methods:

  1. Tkinter Browser Settings:
  • Open settings window
  • Toggle "Enable JavaScript" checkbox
  • Click "Save Security Settings"
  1. Configuration File:
{
  "security": {
    "javascript_enabled": false
  }
}
  1. Programmatic:
browser.javascript_var.set(False)
browser.toggle_javascript()

Testing:

  • Disable JavaScript
  • Visit JavaScript-heavy site (e.g., modern web app)
  • Verify scripts don't execute

Website Filtering

Purpose: Control which websites can be accessed.

Whitelist Configuration:

  1. Tkinter Browser Settings:
  • Open settings window
  • Enter whitelist sites (comma-separated)
  • Click "Save Security Settings"
  1. Configuration File:
{
  "security": {
    "whitelist": [
      "https://example.com",
      "https://trusted.org"
    ]
  }
}

Blacklist Configuration:

  1. Tkinter Browser Settings:
  • Open settings window
  • Enter blacklist sites (comma-separated)
  • Click "Save Security Settings"
  1. Configuration File:
{
  "security": {
    "blacklist": [
      "http://malicious.com",
      "http://phishing.net"
    ]
  }
}

Testing:

  • Add site to whitelist, try accessing non-whitelisted site (should be blocked)
  • Add site to blacklist, try accessing it (should be blocked)

Security Headers

Purpose: Apply HTTP security headers to prevent common web vulnerabilities.

Configuration:

{
  "security": {
    "security_headers": {
      "X-Content-Type-Options": "nosniff",
      "X-Frame-Options": "DENY",
      "Content-Security-Policy": "default-src 'self'; script-src 'self'; object-src 'none';"
    }
  }
}

Available Headers:

X-Content-Type-Options:

  • nosniff: Prevent MIME type sniffing

X-Frame-Options:

  • DENY: Prevent framing
  • SAMEORIGIN: Allow framing from same origin

Content-Security-Policy:

  • default-src 'self': Only load from same origin
  • script-src 'self': Only scripts from same origin
  • object-src 'none': No plugins

User-Agent Customization

Purpose: Customize user-agent for privacy or compatibility.

Configuration Methods:

  1. Tkinter Browser Settings:
  • Open settings window
  • Enter custom user-agent
  • Click "Set User-Agent"
  1. Configuration File:
{
  "security": {
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }
}

Common User-Agents:

Chrome on Windows:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36

Firefox on Linux:

Mozilla/5.0 (X11; Linux x86_64; rv:89.0) Gecko/20100101 Firefox/89.0

Safari on macOS:

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.1 Safari/605.1.15

Network Configuration

Proxy Configuration

Purpose: Route traffic through proxy servers for security, privacy, or access control.

Configuration Methods:

  1. Browser Settings:
  • Open settings window
  • Enter HTTP proxy URL
  • Enter HTTPS proxy URL
  • Click "Save Proxy"
  1. Configuration File:
{
  "proxy": {
    "http": "http://proxy.example.com:8080",
    "https": "https://proxy.example.com:8080"
  }
}
  1. Environment Variables:
export http_proxy="http://proxy.example.com:8080"
export https_proxy="https://proxy.example.com:8080"
  1. Programmatic:
import os
os.environ["http_proxy"] = "http://proxy.example.com:8080"
os.environ["https_proxy"] = "https://proxy.example.com:8080"

Proxy URL Format:

http://username:password@proxy.example.com:8080
https://username:password@proxy.example.com:8080

Testing:

  • Configure proxy
  • Try loading a website
  • Check proxy logs for connection

VPN Configuration

Purpose: Route all traffic through VPN for privacy and security.

Current Status: Placeholder feature (not fully implemented)

Configuration:

{
  "vpn_enabled": true
}

Note: This is a placeholder for future VPN integration. Currently, VPN must be configured at the system level.

UI Customization

PyQt5 Browser Theming

The PyQt5 browser uses Qt Style Sheets (QSS) for theming.

Modifying Colors:

Edit src/browsers/hope.py in the __init__ method:

self.setStyleSheet("""
    QMainWindow {
        background-color: #2b2b2b;  /* Change background color */
        color: #ffffff;              /* Change text color */
    }
    QPushButton {
        background-color: #5865f2;  /* Change button color */
        color: #ffffff;
    }
    # ... additional styling
""")

Color Schemes:

Light Theme:

self.setStyleSheet("""
    QMainWindow {
        background-color: #ffffff;
        color: #000000;
    }
    QPushButton {
        background-color: #007bff;
        color: #ffffff;
    }
""")

Custom Theme:

self.setStyleSheet("""
    QMainWindow {
        background-color: #1a1a2e;
        color: #e94560;
    }
    QPushButton {
        background-color: #16213e;
        color: #0f3460;
    }
""")

Window Dimensions

PyQt5 Browser:

# In src/browsers/hope.py
self.setGeometry(100, 100, 1280, 720)  # x, y, width, height

Tkinter Browser:

# In src/browsers/secure_browser.py
root.geometry("1280x720")  # width x height

WebView Browser:

# In src/browsers/modern_browser.py
root.geometry("900x650")  # width x height

Font Customization

PyQt5 Browser:

self.setStyleSheet("""
    QLineEdit {
        font: 12px 'Segoe UI';
    }
""")

Tkinter Browser:

self.url_entry = tk.Entry(nav_frame, font=("Arial", 14))

Environment Variables

Supported Environment Variables

HTTP_PROXY

  • Purpose: HTTP proxy configuration
  • Format: http://proxy.example.com:8080
  • Example: export HTTP_PROXY="http://proxy.example.com:8080"

HTTPS_PROXY

  • Purpose: HTTPS proxy configuration
  • Format: https://proxy.example.com:8080
  • Example: export HTTPS_PROXY="https://proxy.example.com:8080"

NO_PROXY

  • Purpose: Exclude URLs from proxy
  • Format: Comma-separated list
  • Example: export NO_PROXY="localhost,127.0.0.1,.local"

Setting Environment Variables

Linux/macOS

# Temporary (current session)
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export HTTP_PROXY="http://proxy.example.com:8080"' >> ~/.bashrc
echo 'export HTTPS_PROXY="https://proxy.example.com:8080"' >> ~/.bashrc

Windows

# Temporary (current session)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=https://proxy.example.com:8080

# Permanent (system environment variables)
# Use System Properties > Environment Variables

Advanced Configuration

Multiple Profiles

Create multiple configuration files for different use cases:

Work Profile (config/work_profile.json):

{
  "home_url": "https://work-portal.example.com",
  "security": {
    "javascript_enabled": true,
    "whitelist": [
      "https://work-portal.example.com",
      "https://company-intranet.example.com"
    ]
  },
  "proxy": {
    "http": "http://corporate-proxy.example.com:8080",
    "https": "https://corporate-proxy.example.com:8080"
  }
}

Personal Profile (config/personal_profile.json):

{
  "home_url": "https://search.brave.com/",
  "security": {
    "javascript_enabled": false,
    "blacklist": [
      "http://malicious.com"
    ]
  },
  "proxy": {
    "http": "",
    "https": ""
  }
}

Kiosk Profile (config/kiosk_profile.json):

{
  "home_url": "https://kiosk-content.example.com",
  "security": {
    "javascript_enabled": false,
    "whitelist": [
      "https://kiosk-content.example.com"
    ],
    "user_agent": "Kiosk-Browser/1.0"
  },
  "proxy": {
    "http": "http://kiosk-proxy.example.com:8080",
    "https": "https://kiosk-proxy.example.com:8080"
  }
}

Profile Selection

Modify main.py to support profile selection:

import argparse
import json

def load_profile(profile_name):
    with open(f"config/{profile_name}.json", "r") as f:
        return json.load(f)

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--browser", choices=["pyqt5", "tkinter", "webview", "search"], default="pyqt5")
    parser.add_argument("--profile", default="user_settings")
    args = parser.parse_args()
    
    config = load_profile(args.profile)
    # Apply configuration...

Configuration Validation

Create a configuration validator:

import json
import jsonschema

schema = {
    "type": "object",
    "properties": {
        "home_url": {"type": "string", "format": "uri"},
        "security": {
            "type": "object",
            "properties": {
                "https_enforcement": {"type": "boolean"},
                "javascript_enabled": {"type": "boolean"},
                "whitelist": {"type": "array", "items": {"type": "string"}},
                "blacklist": {"type": "array", "items": {"type": "string"}}
            }
        }
    },
    "required": ["home_url"]
}

def validate_config(config_file):
    with open(config_file, "r") as f:
        config = json.load(f)
    
    jsonschema.validate(config, schema)
    return True

Configuration Backup

Automatically backup configuration before changes:

import shutil
from datetime import datetime
import os

def backup_config():
    config_file = "config/user_settings.json"
    if os.path.exists(config_file):
        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
        backup_file = f"config/user_settings_backup_{timestamp}.json"
        shutil.copy2(config_file, backup_file)
        print(f"Configuration backed up to {backup_file}")

Configuration Migration

Migrate configuration between versions:

def migrate_config(old_config):
    new_config = old_config.copy()
    
    # Add new fields with defaults
    if "security" not in new_config:
        new_config["security"] = {
            "https_enforcement": True,
            "javascript_enabled": True,
            "whitelist": [],
            "blacklist": []
        }
    
    # Remove deprecated fields
    if "deprecated_field" in new_config:
        del new_config["deprecated_field"]
    
    return new_config

Troubleshooting Configuration

Configuration Not Loading

Symptoms: Settings not applied, default values used

Solutions:

  1. Verify JSON syntax: python -m json.tool config/user_settings.json
  2. Check file permissions: ls -la config/user_settings.json
  3. Verify file path: Ensure file exists in config/ directory

Proxy Not Working

Symptoms: Traffic not routing through proxy

Solutions:

  1. Verify proxy URL format
  2. Test proxy with curl: curl -x http://proxy.example.com:8080 https://example.com
  3. Check proxy server logs
  4. Verify environment variables: echo $HTTP_PROXY

Website Filtering Not Working

Symptoms: Blacklisted/whitelisted sites still accessible

Solutions:

  1. Verify URL format (include http:// or https://)
  2. Check for typos in URLs
  3. Verify prefix matching logic
  4. Test with exact URL match

JavaScript Still Executing

Symptoms: JavaScript runs despite being disabled

Solutions:

  1. Verify setting was saved
  2. Reload page after changing setting
  3. Check browser-specific implementation
  4. Clear cache and reload

Configuration Best Practices

  1. Backup Configuration: Always backup before making changes
  2. Validate JSON: Use JSON validator to ensure syntax is correct
  3. Test Changes: Apply changes incrementally and test
  4. Document Changes: Keep track of configuration modifications
  5. Version Control: Store configuration files in version control
  6. Use Profiles: Create different profiles for different use cases
  7. Regular Updates: Keep configuration updated with security best practices
  8. Monitor Logs: Check logs for configuration-related errors
  9. Security Review: Regularly review security settings
  10. User Training: Train users on configuration options

Clone this wiki locally