Security Overview

ChameleonDB implements a defense-in-depth security model with five layers protecting schema integrity and access control.

Security Architecture

┌───────────────────────────────────────┐
│  Application Code (Restricted)        │
│  - Can only load from vault           │
│  - Mode enforcement at runtime        │
└───────────────────────────────────────┘
                  ↓
┌───────────────────────────────────────┐
│  Schema Vault (Source of Truth)       │
│  - Versioned schemas                  │
│  - SHA256 integrity                   │
│  - Immutable snapshots                │
└───────────────────────────────────────┘
                  ↑
┌───────────────────────────────────────┐
│  CLI (Trusted)                        │
│  - Merge schemas                      │
│  - Verify integrity                   │
│  - Register versions                  │
└───────────────────────────────────────┘

The 5 Security Layers

1. File Permissions (OS-level)

# Recommended permissions
chmod 700 .chameleon/              # Owner only
chmod 700 .chameleon/vault/
chmod 600 .chameleon/vault/auth/   # Passwords
chmod 644 .chameleon.yml           # Readable config

Purpose: Prevent unauthorized file system access at the OS level.

2. Hash Integrity (Vault)

Every schema version is cryptographically hashed using SHA256:

.chameleon/vault/
├── manifest.json          # Version metadata
├── versions/
│   ├── v001.json         # Schema snapshot
│   └── v002.json
└── hashes/
    ├── v001.hash         # SHA256 verification
    └── v002.hash

How it works:

Schema saved to versions/v001.json
SHA256 hash computed and saved to hashes/v001.hash
On every load, hash is verified
If mismatch → integrity violation detected

Purpose: Tamper detection for all schema files.

Learn more about vault integrity in Vault Integrity.

3. Integrity Modes (Access Control)

Four operational modes control schema modifications:

Mode	Ring	Access	Schema Changes
readonly	R3	Production default	❌ Blocked
standard	R2	Development teams	✅ Controlled
privileged	R1	DBAs	✅ Direct (logged)
emergency	R0	Incident recovery	✅ No checks (audited)

Mode enforcement:

Application code checks mode before operations
Mode upgrades require password authentication
All mode changes logged in audit trail

Learn more about modes in Mode Enforcement.

4. Vault-Enforced Loading

Application code cannot bypass the vault:

// ✅ SECURE (default)
eng, err := engine.NewEngine()
// ↑ Loads ONLY from .chameleon/state/schema.merged.cham
// ↑ Verifies integrity automatically
// ↑ Enforces mode restrictions

// ❌ INSECURE (blocked by mode)
eng.LoadSchemaFromFile("untrusted.cham")
// → Error: blocked by readonly mode

Purpose: Prevent schema bypass attacks.

5. Audit Trail

Complete event logging: integrity.log (append-only):

2026-02-23T10:30:00Z [INIT] vault_created version=v001
2026-02-23T10:30:00Z [REGISTER] schema_registered version=v001 hash=3f2a8b9c...
2026-02-23T10:35:00Z [MIGRATE] migration_applied version=v001 tables_created=3
2026-02-23T15:45:00Z [MODE_CHANGE] from=readonly to=privileged type=upgrade

Purpose: Forensics and compliance.

Threat Model

What ChameleonDB Protects Against

Schema tampering - Hashes detect file modifications

Unauthorized schema changes - Mode enforcement blocks operations

Schema bypass attacks - Vault is the only trusted source

Privilege escalation - Mode upgrades require password

Audit trail tampering - Append-only logs

What ChameleonDB Does NOT Protect Against

Root/admin access - OS-level root can modify anything. Use OS access controls (sudoers, SELinux).

Database compromise - ChameleonDB doesn’t secure the database itself. Use database security (SSL, auth, encryption at rest).

Memory attacks - Passwords are in memory during operation. Use memory protection (ASLR, DEP).

Social engineering - Users giving away passwords. Implement security training and MFA for production.

Security Checklist

Before deploying to production:

Security Configuration:
[ ] File permissions set (700 for .chameleon/)
[ ] Mode password configured
[ ] Mode set to readonly
[ ] DATABASE_URL in environment (not config)
[ ] .env file gitignored

Verification:
[ ] chameleon verify passes
[ ] No secrets in .chameleon.yml
[ ] Audit logs working
[ ] Mode upgrades require password

Monitoring:
[ ] integrity.log monitored for violations
[ ] journal reviewed regularly
[ ] Unexpected mode changes alerted

Next Steps

Vault Integrity

Learn about SHA256 hashing and tamper detection

Mode Enforcement

Understand ring-based access control

Best Practices

Security recommendations for production

Get Started

Core Concepts

Schema Language

Query System

Mutations

Guides

Security

Security Architecture

The 5 Security Layers

1. File Permissions (OS-level)

2. Hash Integrity (Vault)

3. Integrity Modes (Access Control)

4. Vault-Enforced Loading

5. Audit Trail

Threat Model

What ChameleonDB Protects Against

What ChameleonDB Does NOT Protect Against

Security Checklist

Next Steps

Vault Integrity

Mode Enforcement

Best Practices

​Security Architecture

​The 5 Security Layers

​1. File Permissions (OS-level)

​2. Hash Integrity (Vault)

​3. Integrity Modes (Access Control)

​4. Vault-Enforced Loading

​5. Audit Trail

​Threat Model

​What ChameleonDB Protects Against

​What ChameleonDB Does NOT Protect Against

​Security Checklist

​Next Steps

Vault Integrity

Mode Enforcement

Best Practices

Security Architecture

The 5 Security Layers

1. File Permissions (OS-level)

2. Hash Integrity (Vault)

3. Integrity Modes (Access Control)

4. Vault-Enforced Loading

5. Audit Trail

Threat Model

What ChameleonDB Protects Against

What ChameleonDB Does NOT Protect Against

Security Checklist

Next Steps