secureproximity 1.1.0
Advanced security CLI tool that locks your system when your phone moves out of Bluetooth range.
Requires Python: >=3.8

# SecureProximity

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/secureproximity.svg)](https://pypi.org/project/secureproximity/)
[![Build Status](https://img.shields.io/github/actions/workflow/status/codewithevilxd/SecureProximity/ci.yml)](https://github.com/codewithevilxd/SecureProximity/actions)
[![Code Coverage](https://codecov.io/gh/codewithevilxd/SecureProximity/branch/main/graph/badge.svg)](https://codecov.io/gh/codewithevilxd/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](#-features)
- [🏗️ Architecture](#️-architecture)
- [📋 Requirements](#-requirements)
- [🛠️ Installation](#️-installation)
- [🚀 Quick Start](#-quick-start)
- [📖 Usage](#-usage)
- [⚙️ Configuration](#️-configuration)
- [🔧 Advanced Configuration](#-advanced-configuration)
- [🛡️ Security Features](#️-security-features)
- [🐛 Troubleshooting](#-troubleshooting)
- [🧪 Development](#-development)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
- [📞 Contact](#-contact)
- [🙏 Acknowledgments](#-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)
```bash
pip install secureproximity
```

#### From Source
```bash
# Clone repository
git clone https://github.com/codewithevilxd/SecureProximity.git
cd SecureProximity

# Install in development mode
pip install -e .
```

### Development Installation

```bash
# 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

```bash
# Build container
docker build -t secureproximity .

# Run interactively
docker run -it --privileged --net=host secureproximity
```

## 🚀 Quick Start

### Five-Minute Setup

1. **Install Package**
   ```bash
   pip install secureproximity
   ```

2. **Launch Application**
   ```bash
   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

```bash
$ 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`:

```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:

```bash
export SECUREPROXIMITY_POLL_INTERVAL=15
export SECUREPROXIMITY_SAFETY_THRESHOLD=5
secure-proximity
```

### Custom Lock Commands

For unsupported platforms, modify `secureproximity/core.py`:

```python
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

```bash
# 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
```cmd
# Check Bluetooth service
sc query bthserv

# Reset Bluetooth stack
net stop bthserv && net start bthserv
```

#### macOS
```bash
# Check Bluetooth status
system_profiler SPBluetoothDataType

# Reset Bluetooth module
sudo rm /Library/Preferences/com.apple.Bluetooth.plist
```

#### Linux
```bash
# Check Bluetooth service
systemctl status bluetooth

# Scan with hcitool
hcitool scan
```

## 🧪 Development

### Development Setup

```bash
# 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

```bash
# 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

```python
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

```python
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**
   ```bash
   git clone https://github.com/yourusername/SecureProximity.git
   cd SecureProximity
   ```

2. **Create Feature Branch**
   ```bash
   git checkout -b feature/amazing-feature
   ```

3. **Development**
   ```bash
   # Install dev dependencies
   pip install -e ".[dev]"

   # Run tests
   pytest

   # Code formatting
   black secureproximity/
   ```

4. **Testing**
   ```bash
   # Unit tests
   pytest tests/

   # Integration tests
   pytest tests/integration/ -v

   # Code coverage
   pytest --cov=secureproximity
   ```

5. **Submit PR**
   ```bash
   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](https://github.com/codewithevilxd)
- **Email**: codewithevilxd@gmail.com
- **Discord**: raj.dev_
- **Project Repository**: [https://github.com/codewithevilxd/SecureProximity](https://github.com/codewithevilxd/SecureProximity)

### Support

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/codewithevilxd/SecureProximity/issues)
- 💡 **Feature Requests**: [GitHub Discussions](https://github.com/codewithevilxd/SecureProximity/discussions)
- 📧 **General Inquiry**: codewithevilxd@gmail.com

## 🙏 Acknowledgments

### Core Dependencies
- **[PyBluez](https://github.com/pybluez/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

---

<div align="center">

**SecureProximity** - Because your security shouldn't stop when you step away.

⭐ Star this repository if you find it useful!

</div>