SECURITY.md

# VREyeSAM - Model Security & Protection Guide

## 🔒 Overview

VREyeSAM is protected with multiple security layers to prevent model weight extraction and ensure safe deployment.

## Security Measures Implemented

### 1. **Model Weight Protection**
- ✅ Model weights are loaded at startup and never exposed to the client
- ✅ Weights are managed in `model_server.py` using a singleton pattern
- ✅ Checkpoint paths are resolved internally and never sent to the frontend

### 2. **File System Isolation**
- ✅ Checkpoint files have restricted permissions (600)
- ✅ Only the inference API is exposed to users
- ✅ Raw file access is blocked

### 3. **API-Only Architecture**
- ✅ No direct model file downloads
- ✅ Only prediction results are returned to users
- ✅ Model internals stay hidden

## Deployment to Hugging Face Spaces

### Prerequisites
1. HuggingFace account with Spaces access
2. Model weights in private HuggingFace repository
3. Docker setup for containerized deployment

### Step 1: Create Private Model Repository

```bash
# Clone your model repo (if not already done)
# Ensure checkpoints are NOT committed to git
# Add to .gitignore if needed
```

### Step 2: Deploy to HF Spaces

1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Fill in details:
   - **Space name**: vreyesam
   - **License**: MIT
   - **SDK**: Docker
   - **Visibility**: Public (only code, not weights)
4. After creation, upload your `Dockerfile` and code files

### Step 3: Authentication for Model Downloads

For accessing private model weights during Docker build:

1. Create HuggingFace token: https://huggingface.co/settings/tokens
2. Set in Spaces environment (Settings → Secrets with HF_TOKEN)
3. OR use direct URL with token (not recommended, keep private)

### Step 4: Verify Security

Before deployment:

```bash
# Check what files will be uploaded
git status
git ls-files | grep -E '\.(pt|pth|torch|bin)$'

# Should output: (nothing - no weights!)
```

## Security Checklist

- [ ] Model weights are in `.gitignore`
- [ ] Checkpoint paths are not hardcoded in code
- [ ] Only `model_server.py` handles weight loading
- [ ] Docker build uses secure downloads
- [ ] `.env` files are in `.gitignore`
- [ ] Frontend cannot access file paths
- [ ] API only exposes prediction results

## Best Practices

### ✅ DO:
- Keep model weights private and download during deployment
- Use environment variables for configuration
- Only expose prediction API endpoints
- Log errors without exposing paths
- Use Hugging Face tokens securely in Spaces secrets

### ❌ DON'T:
- Commit model weights to git
- Hardcode checkpoint paths in code
- Expose debug routes that show model structure
- Log full file paths to users
- Include weights in Docker layers visible to users

## Troubleshooting

### Issue: "Model weights not found"
1. Verify `.gitignore` contains checkpoint paths
2. Check Dockerfile correctly downloads from HuggingFace
3. Ensure HF_TOKEN is set in Spaces secrets

### Issue: "File path exposed in error"
1. Update `model_server.py` to not show paths
2. Generic error messages only: "Model initialization failed"
3. Check logs don't contain sensitive details

## Advanced Security

### Optional: Encrypt Weights
```python
# In model_server.py
from cryptography.fernet import Fernet
encrypted_weights = Fernet(key).encrypt(state_dict)
```

### Optional: Disable Direct File Access
```python
# Set file permissions
chmod 600 segment-anything-2/checkpoints/*
# Only the app process can read them
```

## Support

For security questions or issues:
- Check the [GitHub Issues](https://github.com/GeetanjaliGTZ/VREyeSAM/issues)
- Contact: geetanjalisharma546@gmail.com

---

**Last Updated**: March 2025
**Security Level**: High Protection ✅