anti spoofing

# Anti-Spoofing & Security Alerts

## Overview

The system includes advanced multi-layer liveness detection to prevent employees from using photos, videos, or phone screens instead of their actual face during login. **Admins can enable or disable this feature** in company settings.

When anti-spoofing is enabled and a spoofing attempt is detected, the system:

1. **Identifies the suspected employee** using face matching
2. **Captures a screenshot** of the attempt
3. **Logs the incident** with employee details
4. **Blocks the login** attempt
5. **Displays incident** in security dashboard for admin review

## How It Works

### Two-Layer Defense System

#### Layer 1: Client-Side Motion Detection (JavaScript)
- Captures video frames every 300ms
- Compares consecutive frames for pixel differences
- Requires natural micro-movements (blinking, breathing, slight head movement)
- Still images show zero motion → user prompted "Please move slightly (blink or nod)"
- Must detect motion in multiple frames before allowing login

#### Layer 2: Server-Side Multi-Frame Analysis (Python)
- Receives 3 frames captured 150ms apart
- Analyzes frame differences for natural movement
- Real faces: 1-15 avg pixel difference (natural movement)
- Still images: <0.5 avg pixel difference (only camera noise)
- Additional checks: blur analysis, screen moire patterns, glare detection
- Scoring system: ≥40 points = spoof detected

### Detection Methods

| Check | What it Detects | Score |
|-------|-----------------|-------|
| **Multi-frame motion** | No movement between frames (still image) | 50 |
| **Laplacian variance** | Blur detection - photos too sharp or uniformly blurry | 15-20 |
| **Screen moire patterns** | Pixel patterns from phone/monitor screens | 20 |
| **Screen glare** | Bright spots from screen reflections | 10 |
| **Color saturation** | Unnatural color distribution | 10 |

### Why This Defeats Photo/Video Attacks

1. **Still images cannot show motion** - the primary detection method
2. **Screen moire patterns** - phone/monitor screens have detectable pixel patterns
3. **No micro-movements** - real faces have constant subtle motion from breathing, eye movement, etc.

### User Experience

**Normal Login:**
1. Click "Start Face Verification"
2. Position face in camera frame
3. System detects face and natural movement
4. Login proceeds (~2-3 seconds)

**When Motion Not Detected:**
- User sees: "Please move slightly (blink or nod)"
- Natural behavior (looking at camera normally) passes the check

**When Spoofing Detected:**
- Login blocked with message: "🚨 Security Alert: Photo or screen detected. Please use a live camera with your real face. This incident has been logged."

## Security Notifications Dashboard

### Access

**Endpoint**: `/<company>/security`

**Access from**: Admin panel → "🚨 Security Notifications" link

### Dashboard Features

**Incident Table Shows:**
- Incident ID
- Employee name (identified via face matching)
- Incident type (Spoofing Attempt)
- Date and time
- Status (Resolved/Unresolved)
- Action buttons

### Viewing Evidence

Click **"View Evidence"** to see the screenshot captured during the spoofing attempt.

### Resolving Incidents

Click **"Resolve"** button to take action:

**Available Actions:**
- Dismissed - False Positive
- Warning Issued to Employee
- Employee Retrained on Proper Login
- Account Suspended
- Account Terminated
- Reported to Management
- No Action Required

**Resolution includes:**
- Action taken
- Optional notes
- Timestamp of resolution

Click on **"Resolved"** badge to view resolution details in a popup.

## Admin Configuration

### Enabling/Disabling Anti-Spoofing

**Location**: `/<company>/settings` → Security Settings

**Options:**
- **Enabled (Recommended)** - Default setting, provides maximum security
- **Disabled** - Turns off liveness detection

**When to Disable:**
- Testing environment
- Poor webcam quality causing false positives
- Temporary troubleshooting

**When to Enable:**
- Production environment (recommended)
- High-security requirements
- Compliance needs

## Database Schema

### Security Incidents Table

```sql
CREATE TABLE security_incidents (
    id SERIAL PRIMARY KEY,
    company_slug VARCHAR(255) NOT NULL,
    user_id VARCHAR(10),
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    incident_type VARCHAR(50) NOT NULL,
    incident_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    screenshot_data BYTEA,
    resolved BOOLEAN DEFAULT FALSE,
    notes TEXT,
    resolution_action VARCHAR(100),
    resolution_notes TEXT,
    resolved_at TIMESTAMP
)
```

## Detection Scenarios

### Scenario 1: Photo on Phone Screen
**Attack:** Employee holds phone displaying their photo
**Detection:** No motion between frames, screen moire pattern
**Result:** Blocked, incident logged with suspected identity

### Scenario 2: Printed Photo
**Attack:** Employee holds printed photo to webcam
**Detection:** No motion, unnatural sharpness
**Result:** Blocked, incident logged

### Scenario 3: Video Playback
**Attack:** Employee plays video on device
**Detection:** Screen patterns, no natural micro-movements
**Result:** Blocked, incident logged

### Scenario 4: Legitimate Login
**User:** Real person with natural movement
**Detection:** Motion detected, natural characteristics
**Result:** Login proceeds normally

## Files

- `face_verify_server.py` - `detect_spoofing()`, `check_multi_frame_motion()`, `verify_face_no_userid()`
- `templates/login.html` - Client-side motion detection JavaScript
- `templates/security_notifications.html` - Security dashboard
- `templates/security_resolve.html` - Incident resolution form
- `main.go` - Security handlers