# Credential Rotation Procedures

**Purpose**: Defense-in-Depth Layer 5 (inst_072)
**Status**: Active
**Last Updated**: 2025-10-25

---

## 🚨 When to Rotate Credentials

Rotate credentials IMMEDIATELY if any of the following occur:

1. **Confirmed Exposure**: Credential detected in git history, logs, or public location
2. **Suspected Compromise**: Security incident, unauthorized access attempt, or anomalous activity  
3. **Personnel Change**: Team member with credential access leaves or changes role
4. **Scheduled Rotation**: Regular rotation per security policy (recommended: 90 days)
5. **Detection Alert**: Pre-commit hook blocked credential, GitHub secret scanning alert

---

## 📋 Rotation Procedures by Credential Type

### MongoDB Database Password

**Location**: `.env` file (MONGODB_URI)

**Rotation Steps**:
1. Generate new strong password (16+ characters, mixed case, numbers, symbols)
2. Update MongoDB user: `mongosh tractatus_dev --eval "db.changeUserPassword('tractatus_user', 'NEW_PASSWORD')"`
3. Update `.env` file with new password
4. Test connection: `npm test -- --testPathPattern=mongodb.test.js`
5. Restart application
6. Verify application works
7. Document rotation in security log

**Rollback**: Keep old password active for 24 hours, then revoke

---

## 🔍 Git History Credential Removal

If credentials were committed to git history:

1. Remove from history: `git filter-repo --path .env --invert-paths`
2. Force push (coordinate with team first): `git push origin --force --all`
3. Rotate ALL exposed credentials
4. Notify GitHub Security Team (if public repo)

---

## 📊 Rotation Log

**Location**: `logs/credential-rotations.log`

**Format**: `[TIMESTAMP] ROTATION | Credential: TYPE | Reason: REASON | Performed By: EMAIL | Status: SUCCESS/FAILED`

---

## 🛡️ Prevention Measures

1. Never commit credentials (use .env files, already in .gitignore)
2. Pre-commit hooks active (inst_069)
3. Use credential vault (KeePassXC recommended)
4. GitHub secret scanning enabled
5. Regular security audits

---

## 🚨 Emergency Contact

1. **Immediate**: Rotate exposed credentials
2. **Within 1 hour**: Notify security@agenticgovernance.digital  
3. **Within 24 hours**: Complete incident report
4. **Within 1 week**: Review and update procedures

---

**License**: Apache 2.0

**This document satisfies Defense-in-Depth Layer 5 (inst_072)**
