local-deep-research/docs/SECURITY_REVIEW_PROCESS.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