Security Best Practices

Follow these best practices to ensure secure deployment and operation of ChameleonDB.

File Permissions

Set Permissions After Init

# After running chameleon init
chmod 700 .chameleon/
chmod 700 .chameleon/vault/
chmod 600 .chameleon/vault/auth/mode.key
chmod 644 .chameleon.yml

Critical: The auth/mode.key file contains your hashed mode password. It must only be readable by the owner.

Verify Permissions

# Check current permissions
ls -la .chameleon/
ls -la .chameleon/vault/
ls -la .chameleon/vault/auth/

# Expected output:
drwx------  .chameleon/
drwx------  .chameleon/vault/
-rw-------  .chameleon/vault/auth/mode.key
-rw-r--r--  .chameleon.yml

Password Management

Set Strong Passwords

# Use strong, unique password
chameleon config auth set-password

Enter new password: ********  # 16+ chars, mixed case, numbers, symbols
Confirm password: ********
✅ Mode password configured

Password requirements:

Minimum 16 characters
Mix of uppercase and lowercase
Include numbers and symbols
Not used for other systems
Stored in password manager

Environment Variables for CI/CD

Don’t hardcode passwords:

# ❌ BAD - Don't do this
script:
  - chameleon config set mode=standard --password="hardcoded123"

Use environment variables:

# ✅ GOOD
env:
  CHAMELEON_MODE_PASSWORD: ${{ secrets.CHAMELEON_PASSWORD }}
  
script:
  - chameleon config set mode=standard
  - chameleon migrate --apply
  - chameleon config set mode=readonly

Password Rotation

Rotate passwords regularly:

# Schedule quarterly rotation
chameleon config auth set-password

# Update in all environments:
# 1. Development
# 2. Staging  
# 3. Production
# 4. CI/CD secrets

Rotate immediately after personnel changes (departures, role changes).

Mode Strategy

Environment-Based Modes

Environment	Mode	Password Access	Monitoring
Development	standard	Team shared	Basic
Staging	readonly	DevOps only	Alerts on changes
Production	readonly	DBA only	Alert on ANY change
CI/CD	standard	Secret manager	Full audit

Production Mode Workflow

# 1. Always start readonly
Mode: readonly (default)

# 2. Upgrade only during maintenance windows
#    - Require change ticket
#    - Get approval
#    - Schedule window

# 3. Upgrade, apply, downgrade
chameleon config set mode=standard
chameleon migrate --apply
chameleon config set mode=readonly  # IMMEDIATELY

# 4. Verify downgrade
chameleon config get mode
# Output: readonly

Never leave production in standard/privileged mode. Downgrade immediately after maintenance.

Secrets Management

Never Commit Secrets

.gitignore (required):

# Environment variables
.env
.env.local
.env.*.local

# Passwords and keys
.chameleon/vault/auth/

# Generated files
.chameleon/state/schema.merged.cham

# Database files (if using SQLite for testing)
*.db
*.sqlite

Configuration Files

Don’t put secrets in .chameleon.yml:

# ❌ BAD - Don't do this
database:
  host: "localhost"
  port: 5432
  user: "postgres"
  password: "hardcoded123"  # ← NO!
  database: "myapp"

Use environment variables:

# ✅ GOOD
database:
  connection_string: "${DATABASE_URL}"

Environment Variables

.env (gitignored):

# Database connection
DATABASE_URL=postgresql://user:password@host:5432/db

# ChameleonDB mode password
CHAMELEON_MODE_PASSWORD=strong-password-here

# Application secrets
API_KEY=xyz123
SECRET_KEY=abc456

Load in application:

# Load .env
export $(cat .env | xargs)

# Or use direnv
echo 'dotenv' > .envrc
direnv allow

Git Strategy

What to Commit

DO commit:

✅ .chameleon.yml          # Public config (no secrets)
✅ vault/manifest.json      # Version metadata
✅ vault/versions/          # Schema snapshots
✅ vault/hashes/            # Integrity hashes
✅ vault/integrity.log      # Audit trail
✅ schemas/*.cham           # Source schemas

DON’T commit:

❌ vault/auth/              # Passwords
❌ .env                     # Secrets
❌ state/schema.merged.cham # Generated
❌ journal/                 # Local logs (optional)

Pre-commit Hook

Prevent accidental secret commits: .git/hooks/pre-commit:

#!/bin/bash

# Check for secrets
if git diff --cached --name-only | grep -q '.env$'; then
  echo "❌ Error: Attempting to commit .env file"
  exit 1
fi

if git diff --cached --name-only | grep -q 'vault/auth/'; then
  echo "❌ Error: Attempting to commit password files"
  exit 1
fi

# Verify vault integrity before commit
chameleon verify || {
  echo "❌ Error: Vault integrity check failed"
  exit 1
}

echo "✅ Pre-commit checks passed"
exit 0

# Make executable
chmod +x .git/hooks/pre-commit

Monitoring & Alerts

Monitor integrity.log

Set up log monitoring:

# Watch for violations
tail -f .chameleon/vault/integrity.log | grep -i "violation\|emergency"

Alert on suspicious events:

#!/bin/bash
# monitor-integrity.sh

LOG=".chameleon/vault/integrity.log"
ALERT_EMAIL="security@company.com"

# Check for violations
if tail -100 "$LOG" | grep -q "VIOLATION"; then
  echo "ALERT: Integrity violation detected" | mail -s "ChameleonDB Alert" "$ALERT_EMAIL"
fi

# Check for emergency mode
if tail -100 "$LOG" | grep -q "mode=emergency"; then
  echo "ALERT: Emergency mode activated" | mail -s "ChameleonDB Alert" "$ALERT_EMAIL"
fi

Run periodically:

# Cron every 5 minutes
*/5 * * * * /path/to/monitor-integrity.sh

Key Events to Monitor

Alert immediately on:

Integrity violations
Emergency mode activation
Failed password attempts
Unexpected mode changes
Unusual migration activity

Review regularly:

Mode change history
Migration patterns
User activity in logs

Backup Strategy

What to Backup

Critical:

.chameleon/vault/          # Entire vault
schemas/                   # Source schemas
.chameleon.yml             # Configuration

Optional:

.chameleon/state/          # Current state
.chameleon/journal/        # Operation logs

Automated Backups

Daily vault backup:

#!/bin/bash
# backup-vault.sh

DATE=$(date +%Y%m%d)
BACKUP_DIR="/backups/chameleon"

# Create backup
tar -czf "$BACKUP_DIR/vault-$DATE.tar.gz" .chameleon/vault/

# Keep last 30 days
find "$BACKUP_DIR" -name "vault-*.tar.gz" -mtime +30 -delete

echo "✅ Vault backed up: vault-$DATE.tar.gz"

Cron daily at 2 AM:

0 2 * * * /path/to/backup-vault.sh

Verify Backups

# Test restore process
tar -tzf /backups/chameleon/vault-20260223.tar.gz

# Restore to temp location and verify
mkdir /tmp/vault-test
tar -xzf /backups/chameleon/vault-20260223.tar.gz -C /tmp/vault-test
cd /tmp/vault-test
chameleon verify

Compliance & Audit

Audit Trail Requirements

ChameleonDB provides:

Who - User information in logs

What - Detailed operation records

When - Timestamp for all events

Why - Context in commit messages

How - Complete operation details

Regular Audit Review

Weekly:

# Review recent mode changes
chameleon journal last 100 | grep mode

# Review migrations
chameleon journal schema

Monthly:

# Full integrity log review
cat .chameleon/vault/integrity.log | grep -E "MODE_CHANGE|VIOLATION|EMERGENCY"

# Generate compliance report
chameleon journal export --format=csv --since=30d > audit-$(date +%Y%m).csv

Quarterly:

Review access controls
Rotate passwords
Update security procedures
Test incident response

Compliance Checklist

Before Production Deployment:
[ ] File permissions set (700 for .chameleon/)
[ ] Mode password configured (16+ chars)
[ ] Mode set to readonly
[ ] DATABASE_URL in environment (not config)
[ ] .env file gitignored
[ ] Pre-commit hooks installed
[ ] Backup strategy implemented
[ ] Monitoring alerts configured
[ ] chameleon verify passes
[ ] No secrets in .chameleon.yml
[ ] Audit logs working
[ ] Mode upgrades require password
[ ] Incident response plan documented
[ ] Team trained on security procedures

Incident Response

Integrity Violation

Response steps:

# 1. STOP - Halt all migrations immediately
echo "INCIDENT: Integrity violation detected" | mail -s "URGENT" ops@company.com

# 2. INVESTIGATE
chameleon verify
cat .chameleon/vault/integrity.log | tail -50
ls -la .chameleon/vault/versions/
ls -la .chameleon/vault/hashes/

# 3. RESTORE from backup
cp -r /backups/chameleon/vault-latest/ .chameleon/vault/

# 4. VERIFY restoration
chameleon verify

# 5. REVIEW access logs
sudo grep "chameleon" /var/log/auth.log

# 6. ROTATE passwords
chameleon config auth set-password

# 7. DOCUMENT incident
echo "$(date): Integrity violation - restored from backup" >> incidents.log

Unauthorized Mode Change

# 1. Check who changed mode
chameleon journal last 50 | grep mode

# 2. Immediately downgrade
chameleon config set mode=readonly

# 3. Change password
chameleon config auth set-password

# 4. Review recent migrations
chameleon journal schema

# 5. Audit for unauthorized changes
chameleon status

# 6. Document and investigate

Password Compromise

# 1. Immediately rotate password
chameleon config auth set-password

# 2. Update in all environments
# - Development
# - Staging
# - Production
# - CI/CD secrets

# 3. Review recent activity
cat .chameleon/vault/integrity.log | tail -100

# 4. Check for unauthorized migrations
chameleon journal schema

# 5. Verify vault integrity
chameleon verify

Security Hardening

Operating System Level

Linux with SELinux:

# Set SELinux context
semanage fcontext -a -t user_home_t ".chameleon(/.*)?"
restorecon -Rv .chameleon/

# Verify
ls -Z .chameleon/

AppArmor profile:

# /etc/apparmor.d/usr.local.bin.chameleon
#include <tunables/global>

/usr/local/bin/chameleon {
  #include <abstractions/base>
  
  # Allow read/write to vault
  owner @{HOME}/.chameleon/** rw,
  
  # Deny network access
  deny network,
}

Network Security

Database connection:

# Use SSL/TLS
database:
  connection_string: "postgresql://user:pass@host:5432/db?sslmode=require"

Firewall rules:

# Only allow database connection from app server
sudo ufw allow from APP_IP to DB_IP port 5432

Summary

File Permissions

700 for .chameleon/
600 for auth files

Password Management

16+ character passwords
Rotate quarterly
Use environment variables

Mode Strategy

readonly for production
Time-limited upgrades
Immediate downgrades

Monitoring

Watch integrity.log
Alert on violations
Regular audits

Next Steps

Security Overview

Review the complete security model

​File Permissions

​Set Permissions After Init

​Verify Permissions

​Password Management

​Set Strong Passwords

​Environment Variables for CI/CD

​Password Rotation

​Mode Strategy

​Environment-Based Modes

​Production Mode Workflow

​Secrets Management

​Never Commit Secrets

​Configuration Files

​Environment Variables

​Git Strategy

​What to Commit

​Pre-commit Hook

​Monitoring & Alerts

​Monitor integrity.log

​Key Events to Monitor

​Backup Strategy

​What to Backup

​Automated Backups

​Verify Backups

​Compliance & Audit

​Audit Trail Requirements

​Regular Audit Review

​Compliance Checklist

​Incident Response

​Integrity Violation

​Unauthorized Mode Change

​Password Compromise

​Security Hardening

​Operating System Level

​Network Security

​Summary

File Permissions

Password Management

Mode Strategy

Monitoring

​Next Steps

Security Overview

File Permissions

Set Permissions After Init

Verify Permissions

Password Management

Set Strong Passwords

Environment Variables for CI/CD

Password Rotation

Mode Strategy

Environment-Based Modes

Production Mode Workflow

Secrets Management

Never Commit Secrets

Configuration Files

Environment Variables

Git Strategy

What to Commit

Pre-commit Hook

Monitoring & Alerts

Monitor integrity.log

Key Events to Monitor

Backup Strategy

What to Backup

Automated Backups

Verify Backups

Compliance & Audit

Audit Trail Requirements

Regular Audit Review

Compliance Checklist

Incident Response

Integrity Violation

Unauthorized Mode Change

Password Compromise

Security Hardening

Operating System Level

Network Security

Summary

Next Steps