learningcircuit--local-deep-research/docs/processes/security-review-process/README.md

# Security Review Process

## Overview

This repository uses an automated alert system to highlight when PRs modify security-critical files. Instead of blocking development, we provide clear warnings and checklists to ensure dangerous changes get proper scrutiny.

## How It Works

### 🚨 Automatic Detection
When a PR modifies any of these files:
- Database encryption (`encrypted_db.py`, `sqlcipher_*.py`)
- Authentication (`/auth/` directory, `password*.py`)
- Security utilities (`/security/` directory)
- Encryption/decryption code (`*encrypt*.py`, `*decrypt*.py`, `*crypto*.py`)

The CI will:
1. **Post a prominent warning comment** with security-specific review checklist
2. **Add labels** to the PR (`security-review-needed`, `touches-encryption`, etc.)
3. **Create a status check** showing "Security Review Required" (informational, not blocking)

### 📋 Review Checklists

The bot creates specific checklists based on what was modified:

#### For Encryption Changes:
- SQLCipher pragma order (key must come first)
- No hardcoded keys
- Backward compatibility
- Migration paths

#### For Authentication Changes:
- No auth bypasses
- Secure session handling
- Proper password hashing
- No privilege escalation

#### For All Security Changes:
- No exposed secrets
- No debug bypasses
- Safe error messages
- Secure logging

## For Developers

### When You Modify Security Files:

1. **Expect the warning** - It's not a failure, just a heads-up
2. **Self-review first** - Go through the checklist yourself
3. **Document your changes** - Explain WHY the security code needed to change
4. **Test thoroughly** - Especially with existing encrypted databases
5. **Be patient** - Security reviews take time

### Red Flags to Avoid:

❌ Changing pragma order in SQLCipher code
❌ Adding "temporary" auth bypasses
❌ Logging passwords or encryption keys
❌ Hardcoding credentials
❌ Disabling security checks "for testing"

## For Reviewers

### When You See the Warning:

1. **Take it seriously** - These files can break security if done wrong
2. **Go through the checklist** - Don't just check boxes, verify each item
3. **Test locally** - Especially encryption changes with real databases
4. **Ask questions** - If something seems off, dig deeper
5. **Get a second opinion** - For CRITICAL changes, ask another reviewer

### What Caused Our Previous Issue:

The SQLCipher pragma order bug that corrupted databases happened because:
- Pragmas were applied BEFORE setting the encryption key
- This wasn't caught in review despite being in "hotfix" branch
- The change seemed logical but was actually breaking

**Lesson:** Even "obvious" changes to encryption code need careful review!

## The Philosophy

- **Warnings, not blocks** - We trust developers but want awareness
- **Specific guidance** - Checklists for what to look for
- **Risk-based** - More critical files get scarier warnings
- **Educational** - Help reviewers know what to check

## Labels Added Automatically

- `security-review-needed` - Always added for security files
- `touches-encryption` - Database encryption modified
- `touches-authentication` - Auth system modified
- `critical-changes` - Multiple security systems affected

## It's Not Perfect

This system won't catch everything:
- Logic bugs in security code
- Subtle vulnerabilities
- Dependencies with security issues

It's meant to make reviewers **pause and think** when touching dangerous code.

## Questions?

If you're unsure about a security change:
1. Ask in the PR for additional reviewers
2. Test with production-like data
3. Consider doing a security-focused code review session
4. When in doubt, be more cautious