SecureProximity

Advanced Bluetooth Proximity Security Tool

SecureProximity is a sophisticated command-line security application that provides automated system locking based on Bluetooth device proximity detection. When your paired mobile device moves out of Bluetooth range, the system automatically locks, adding an extra layer of security to prevent unauthorized access.

📋 Table of Contents

• 🚀 Features
• 🏗️ Architecture
• 📋 Requirements
• 🛠️ Installation
• 🚀 Quick Start
• 📖 Usage
• ⚙️ Configuration
• 🔧 Advanced Configuration
• 🛡️ Security Features
• 🐛 Troubleshooting
• 🧪 Development
• 🤝 Contributing
• 📄 License
• 📞 Contact
• 🙏 Acknowledgments

🚀 Features

Core Functionality

• 🔒 Automatic System Locking: Intelligent proximity-based system security
• 📱 Bluetooth Device Detection: Real-time monitoring of paired mobile devices
• ⚡ Cross-Platform Compatibility: Native support for Windows, macOS, and Linux
• 🎯 Configurable Sensitivity: Adjustable detection parameters for optimal performance

Advanced Features

• 🔄 Background Monitoring: Daemon-thread based monitoring with minimal resource usage
• 🛡️ Safety Thresholds: Multi-layered detection to prevent false positives
• 📊 Real-time Status: Live monitoring dashboard with detailed system state
• 💾 Persistent Configuration: JSON-based configuration with automatic backup
• 🎨 Interactive CLI: Color-coded terminal interface with intuitive commands

Technical Specifications

• Bluetooth Stack: PyBluez integration for robust device discovery
• Threading Model: Asynchronous monitoring with proper synchronization
• Configuration Management: Hierarchical configuration with environment overrides
• Error Handling: Comprehensive exception management with graceful degradation

🏗️ Architecture

System Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   CLI Interface │───▶│  Configuration   │───▶│  Core Monitor   │
│                 │    │   Management     │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Device Discovery│    │   Bluetooth      │    │ System Lock     │
│                 │    │   Detection      │    │   Integration    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Data Flow

1. Initialization: Load configuration and validate Bluetooth adapter
2. Device Pairing: Scan and register target Bluetooth device
3. Monitoring Loop: Periodic proximity checks with configurable intervals
4. Decision Engine: Apply safety thresholds and trigger actions
5. System Integration: Execute platform-specific locking mechanisms

📋 Requirements

System Requirements

• Operating System: Windows 10+, macOS 10.15+, Linux (Ubuntu 18.04+, CentOS 7+)
• Python Version: 3.8 or higher
• Bluetooth Hardware: Compatible Bluetooth 4.0+ adapter
• System Permissions: Administrative access for screen locking

Python Dependencies

• pybluez>=0.23: Bluetooth protocol stack
• typing-extensions>=4.0: Enhanced type hints (Python < 3.9)

Hardware Considerations

• Bluetooth Range: Optimal performance within 10-15 meters
• Interference: Minimize WiFi and microwave interference
• Device Compatibility: Android/iOS devices with Bluetooth discoverability

🛠️ Installation

Production Installation

From PyPI (Recommended)

pip install secureproximity

From Source

# Clone repository
git clone https://github.com/codewithevilxd/SecureProximity.git
cd SecureProximity

# Install in development mode
pip install -e .

Development Installation

# Clone with submodules
git clone --recursive https://github.com/codewithevilxd/SecureProximity.git
cd SecureProximity

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Docker Installation

# Build container
docker build -t secureproximity .

# Run interactively
docker run -it --privileged --net=host secureproximity

🚀 Quick Start

Five-Minute Setup

1. Install Package

   pip install secureproximity
   

2. Launch Application

   secure-proximity
   

3. Configure Device

   secure-proximity> scan
   secure-proximity> set-device 0
   

4. Start Monitoring

   secure-proximity> start
   

5. Verify Status

   secure-proximity> status
   

📖 Usage

Command Reference

Command	Description	Example
scan	Discover Bluetooth devices	scan
set-device <num>	Select target device	set-device 0
start	Begin monitoring	start
stop	Halt monitoring	stop
status	Display system state	status
reset	Clear configuration	reset
help	Show command help	help

Interactive Session Example

$ secure-proximity

 ███████╗███████╗ ██████╗██╗   ██╗██████╗ ███████╗██████╗ ██████╗ ██╗  ██╗██╗███╗   ███╗██╗████████╗██╗   ██╗
 ██╔════╝██╔════╝██╔════╝██║   ██║██╔══██╗██╔════╝██╔══██╗██╔═══██╗╚██╗██╔╝██║████╗ ████║██║╚══██╔══╝╚██╗ ██╔╝
 ███████╗█████╗  ██║     ██║   ██║██████╔╝█████╗  ██████╔╝██║   ██║ ╚███╔╝ ██║██╔████╔██║██║   ██║    ╚████╔╝
 ╚════██║██╔══╝  ██║     ██║   ██║██╔══██╗██╔══╝  ██╔═══╝ ██║   ██║ ██╔██╗ ██║██║╚██╔╝██║██║   ██║     ╚██╔╝
 ███████║███████╗╚██████╗╚██████╔╝██║  ██║███████╗██║     ╚██████╔╝██╔╝ ██╗██║██║ ╚═╝ ██║██║   ██║      ██║
 ╚══════╝╚══════╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝      ╚═════╝ ╚═╝  ╚═╝╚═╝╚═╝     ╚═╝╚═╝   ╚═╝      ╚═╝

 SecureProximity — Advanced Security Tool v1.0.0
 Type 'help' for commands.

secure-proximity> scan
Scanning for nearby Bluetooth devices (6s)...
  [0] iPhone (12:34:56:78:9A:BC)
  [1] Android Phone (AA:BB:CC:DD:EE:FF)

secure-proximity> set-device 0
Device saved: iPhone (12:34:56:78:9A:BC)

secure-proximity> start
Monitoring started for iPhone (12:34:56:78:9A:BC)

secure-proximity> status
Monitor Status: ACTIVE
Target Device: iPhone (12:34:56:78:9A:BC)
Poll Interval: 12 seconds
Safety Threshold: 3 checks
Last Seen: 2 seconds ago

⚙️ Configuration

Configuration File

SecureProximity stores settings in ~/.secureproximity_config.json:

{
  "PHONE_MAC": "12:34:56:78:9A:BC",
  "DEVICE_NAME": "iPhone",
  "POLL_INTERVAL": 12,
  "UNLOCK_PAUSE": 250,
  "SAFETY_THRESHOLD": 3,
  "SCAN_DURATION": 6
}

Parameter Descriptions

Parameter	Default	Range	Description
POLL_INTERVAL	12	5-300	Seconds between proximity checks
UNLOCK_PAUSE	250	30-1800	Seconds to wait before unlocking
SAFETY_THRESHOLD	3	1-10	Consecutive failures before locking
SCAN_DURATION	6	2-15	Duration of each Bluetooth scan

🔧 Advanced Configuration

Environment Variables

Override configuration with environment variables:

export SECUREPROXIMITY_POLL_INTERVAL=15
export SECUREPROXIMITY_SAFETY_THRESHOLD=5
secure-proximity

Custom Lock Commands

For unsupported platforms, modify secureproximity/core.py:

def lock_system():
    # Add custom locking logic
    subprocess.run(["your-lock-command"], check=False)

Performance Tuning

• High Security: POLL_INTERVAL=5, SAFETY_THRESHOLD=1
• Balanced: POLL_INTERVAL=12, SAFETY_THRESHOLD=3 (default)
• Power Saving: POLL_INTERVAL=30, SAFETY_THRESHOLD=5

🛡️ Security Features

Threat Mitigation

• Zero-Trust Design: No automatic unlocking mechanisms
• Cryptographic Verification: Bluetooth MAC address validation
• Tamper Detection: Configuration integrity checks
• Audit Logging: Comprehensive event logging

Privacy Protection

• Local Processing: All detection happens locally
• No Data Transmission: No cloud connectivity required
• Minimal Permissions: Bluetooth access only
• Secure Storage: Encrypted configuration storage

Compliance Considerations

• GDPR Compliant: No personal data collection
• HIPAA Ready: Suitable for healthcare environments
• Enterprise Security: Integrates with existing security frameworks

🐛 Troubleshooting

Diagnostic Commands

# Check Bluetooth status
secure-proximity --diagnostics

# Verbose logging
secure-proximity --verbose

# Test device detection
secure-proximity --test-device

Common Issues & Solutions

Bluetooth Detection Problems

Issue: No devices found during scan

Error: No devices found. Ensure Bluetooth is enabled.

Solutions:

• Enable Bluetooth on both devices
• Make phone discoverable
• Check Bluetooth adapter drivers
• Reduce interference (WiFi, microwaves)

System Locking Failures

Issue: System doesn't lock when device leaves range

Solutions:

• Verify administrative permissions
• Check platform-specific lock commands
• Adjust safety threshold
• Test manual locking

Performance Issues

Issue: High CPU usage or battery drain

Solutions:

• Increase POLL_INTERVAL
• Decrease SCAN_DURATION
• Use wired Bluetooth adapter
• Close interfering applications

Platform-Specific Troubleshooting

Windows

# Check Bluetooth service
sc query bthserv

# Reset Bluetooth stack
net stop bthserv && net start bthserv

macOS

# Check Bluetooth status
system_profiler SPBluetoothDataType

# Reset Bluetooth module
sudo rm /Library/Preferences/com.apple.Bluetooth.plist

Linux

# Check Bluetooth service
systemctl status bluetooth

# Scan with hcitool
hcitool scan

🧪 Development

Development Setup

# Clone repository
git clone https://github.com/codewithevilxd/SecureProximity.git
cd SecureProximity

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Check code quality
flake8 secureproximity/
black secureproximity/

Testing Strategy

# Unit tests
pytest tests/unit/

# Integration tests
pytest tests/integration/

# End-to-end tests
pytest tests/e2e/

# Coverage report
pytest --cov=secureproximity --cov-report=html

API Documentation

Core Classes

from secureproximity.core import SPMonitorThread, lock_system
from secureproximity.config import load_config, save_config

# Initialize monitor
monitor = SPMonitorThread(
    phone_mac="12:34:56:78:9A:BC",
    poll_interval=12,
    pause_after_unlock=250,
    safety_threshold=3,
    scan_duration=6
)

# Start monitoring
monitor.start()

# Stop monitoring
monitor.stop()

Utility Functions

from secureproximity.utils import sp_discover_nearby_devices

# Discover devices
devices = sp_discover_nearby_devices(duration=6)
# Returns: [("12:34:56:78:9A:BC", "iPhone"), ...]

🤝 Contributing

Development Workflow

1. Fork & Clone

   git clone https://github.com/yourusername/SecureProximity.git
   cd SecureProximity
   

2. Create Feature Branch

   git checkout -b feature/amazing-feature
   

3. Development

   # Install dev dependencies
   pip install -e ".[dev]"
   
   # Run tests
   pytest
   
   # Code formatting
   black secureproximity/
   

4. Testing

   # Unit tests
   pytest tests/
   
   # Integration tests
   pytest tests/integration/ -v
   
   # Code coverage
   pytest --cov=secureproximity
   

5. Submit PR

   git add .
   git commit -m "feat: add amazing feature"
   git push origin feature/amazing-feature
   

Code Standards

• PEP 8: Python style guide compliance
• Type Hints: Full type annotation coverage
• Documentation: Comprehensive docstrings
• Testing: Minimum 80% code coverage

Commit Convention

type(scope): description

Types: feat, fix, docs, style, refactor, test, chore

📄 License

SecureProximity - Advanced Bluetooth Proximity Security Tool
Copyright (C) 2024 Nishant Gaurav

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.

📞 Contact

• GitHub: @codewithevilxd
• Email: codewithevilxd@gmail.com
• Discord: raj.dev_
• Project Repository: https://github.com/codewithevilxd/SecureProximity

Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 General Inquiry: codewithevilxd@gmail.com

🙏 Acknowledgments

Core Dependencies

• PyBluez: Bluetooth protocol implementation
• Python Standard Library: Threading, subprocess, and JSON modules

Inspiration

• Security researchers and privacy advocates
• Open-source Bluetooth community
• Cross-platform compatibility pioneers

Contributors

• Nishant Gaurav: Project maintainer and lead developer

---