evankolega · kolega-dev-github-app · Feb 14, 2026
diff --git a/docs/security/payload-sanitization.md b/docs/security/payload-sanitization.md
@@ -0,0 +1,242 @@
+# Payload Sanitization Security Guide
+
+## Overview
+
+The payload sanitization system protects against CWE-532 vulnerabilities (Sensitive Data Exposure in Logs) by automatically detecting and redacting sensitive information before it's written to log files.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Options | Default | Description |
+|----------|---------|---------|-------------|
+| `OPENCLAW_ANTHROPIC_PAYLOAD_LOG` | `true`/`false` | `false` | Enable/disable payload logging |
+| `PAYLOAD_LOG_SANITIZATION_LEVEL` | `none`/`minimal`/`standard`/`paranoid` | `standard` | Sanitization strictness |
+| `PAYLOAD_LOG_MAX_CONTENT_LENGTH` | number | `10000` | Max content length before truncation |
+| `PAYLOAD_LOG_INCLUDE_HINTS` | `true`/`false` | `true` | Include redaction type hints |
+| `PAYLOAD_LOG_CUSTOM_FIELDS` | comma-separated | - | Additional sensitive field names |
+
+### Sanitization Levels
+
+#### `none` (⚠️ DANGEROUS)
+- **No sanitization performed**
+- Blocked in production environments
+- Only for isolated debugging
+- **WARNING**: Exposes sensitive data in plaintext
+
+#### `minimal`
+- Detects obvious secrets (API keys, tokens)
+- Suitable for controlled environments
+- Fast processing
+
+#### `standard` (Recommended)
+- Detects secrets + PII + sensitive fields
+- Balances security and functionality
+- Default for production
+
+#### `paranoid`
+- Maximum protection
+- Truncates system prompts aggressively
+- May over-redact legitimate data
+
+## What Gets Sanitized
+
+### API Keys and Secrets
+- Anthropic API keys (`sk-ant-...`)
+- OpenAI API keys (`sk-...`, `sk-proj-...`)
+- GitHub tokens (`ghp_...`, `github_pat_...`)
+- AWS access keys (`AKIA...`)
+- JWT tokens
+- Bearer/Basic auth headers
+- Private key blocks
+- Generic API key patterns
+
+### Personal Information (PII)
+- Social Security Numbers (`123-45-6789`)
+- Credit card numbers (Visa, MC, Amex, Discover)
+- US phone numbers
+- Email addresses
+- IP addresses (paranoid level only)
+
+### Sensitive Fields
+Field names are matched case-insensitively with various naming conventions:
+- `password`, `passwd`, `pwd`
+- `secret`, `apiKey`, `api_key`, `token`
+- `authorization`, `bearer`, `credentials`
+- `sessionKey`, `session_token`, `cookie`
+- `privateKey`, `private_key`
+- And many more...
+
+## Security Features
+
+### Production Protection
+- Forces minimum `STANDARD` level in production
+- Prevents accidental exposure via environment override
+- Displays clear warnings for risky configurations
+
+### Defense in Depth
+1. **Field-level filtering**: Removes entire sensitive fields
+2. **Pattern matching**: Regex-based secret detection
+3. **Content truncation**: Limits payload size
+4. **Safe error handling**: Fails securely if sanitization errors occur
+
+### Audit Trail
+Each log entry includes sanitization metadata:
+- `sanitizationLevel`: Applied protection level
+- `redactionCount`: Number of items redacted
+- `detectedSensitiveTypes`: Types of sensitive data found
+- `sanitizationWarnings`: Any issues during processing
+
+## Example Usage
+
+### Basic Setup
+```bash
+# Enable logging with standard protection
+export OPENCLAW_ANTHROPIC_PAYLOAD_LOG=true
+export PAYLOAD_LOG_SANITIZATION_LEVEL=standard
+```
+
+### High-Security Environment
+```bash
+# Paranoid mode with custom sensitive fields
+export OPENCLAW_ANTHROPIC_PAYLOAD_LOG=true
+export PAYLOAD_LOG_SANITIZATION_LEVEL=paranoid
+export PAYLOAD_LOG_CUSTOM_FIELDS="customer_id,internal_token,proprietary_key"
+export PAYLOAD_LOG_MAX_CONTENT_LENGTH=5000
+```
+
+### Development/Debug Mode
+```bash
+# Minimal sanitization for faster processing
+export NODE_ENV=development
+export OPENCLAW_ANTHROPIC_PAYLOAD_LOG=true
+export PAYLOAD_LOG_SANITIZATION_LEVEL=minimal
+```
+
+## Log Output Example
+
+### Before Sanitization
+```json
+{
+  "payload": {
+    "apiKey": "sk-ant-api03-abcdefghij1234567890",
+    "userQuery": "My SSN is 123-45-6789",
+    "systemPrompt": "Use API key sk-proj-xyz123 for calls"
+  }
+}
+```
+
+### After Sanitization
+```json
+{
+  "sanitizationLevel": "standard",
+  "redactionCount": 3,
+  "detectedSensitiveTypes": ["ANTHROPIC_API_KEY", "SSN", "OPENAI_PROJECT_KEY"],
+  "payload": {
+    "apiKey": "[REDACTED:SENSITIVE_FIELD]",
+    "userQuery": "My SSN is [REDACTED:SSN]", 
+    "systemPrompt": "Use API key [REDACTED:OPENAI_PROJECT_KEY] for calls"
+  },
+  "sanitizationWarnings": ["Redacted 3 instances of sensitive data"]
+}
+```
+
+## Best Practices
+
+### For Production
+1. Always use `STANDARD` or `PARANOID` level
+2. Secure log file permissions (`600` or `640`)
+3. Implement log rotation to prevent disk exhaustion
+4. Restrict access to log files (audit who can read them)
+5. Never transmit logs over insecure channels
+
+### For Development
+1. Use `MINIMAL` level for faster iteration
+2. Review logs periodically for false positives
+3. Add custom patterns for domain-specific secrets
+4. Test sanitization with realistic data
+
+### General Guidelines
+1. **Defense in depth**: Don't rely solely on sanitization
+2. **Regular audits**: Review what's being logged
+3. **Incident response**: Know how to secure logs if compromised
+4. **Documentation**: Keep security configurations documented
+
+## Limitations
+
+### What Sanitization Cannot Prevent
+- Novel secret formats not covered by patterns
+- Business logic secrets embedded in natural language
+- Inference attacks on redacted data
+- Accidental exposure if sanitization is disabled
+
+### Performance Considerations
+- Regex matching adds processing overhead
+- Large payloads take longer to sanitize
+- `PARANOID` level has highest performance impact
+
+### False Positives/Negatives
+- May redact legitimate UUIDs or tokens (false positives)
+- May miss custom secret formats (false negatives)
+- Pattern maintenance required for new secret types
+
+## Troubleshooting
+
+### Common Issues
+
+#### High Redaction Count
+```bash
+# Check what's being detected
+grep "detectedSensitiveTypes" anthropic-payload.jsonl | head -5
+```
+
+#### Performance Problems
+```bash
+# Reduce sanitization level or content length
+export PAYLOAD_LOG_SANITIZATION_LEVEL=minimal
+export PAYLOAD_LOG_MAX_CONTENT_LENGTH=5000
+```
+
+#### Missing Custom Secrets
+```bash
+# Add custom patterns via environment
+export PAYLOAD_LOG_CUSTOM_FIELDS="my_secret_field,internal_key"
+```
+
+#### Production Override Errors
+Production environments automatically upgrade `none`/`minimal` to `standard`. This is intentional security behavior.
+
+### Emergency Procedures
+
+#### Suspected Data Exposure
+1. Immediately disable logging: `OPENCLAW_ANTHROPIC_PAYLOAD_LOG=false`
+2. Secure existing log files (move to restricted location)
+3. Audit log contents for actual exposure
+4. Rotate any potentially compromised secrets
+5. Document incident for security review
+
+#### Log File Compromise
+1. Assume all logged data is compromised
+2. Rotate all API keys/tokens from the time period
+3. Review access patterns for unauthorized activity
+4. Implement additional monitoring
+
+## Contributing
+
+### Adding New Secret Patterns
+1. Update `SECRET_PATTERNS` in `src/agents/payload-sanitizer.ts`
+2. Include pattern name, regex, and minimum level
+3. Add test cases in `src/agents/payload-sanitizer.test.ts`
+4. Consider false positive rate
+
+### Testing Changes
+```bash
+# Run sanitization tests
+npm test -- --testNamePattern="PayloadSanitizer"
+
+# Test with sample sensitive data
+echo '{"key": "sk-ant-test123"}' | node -e "
+const {sanitizePayload} = require('./dist/agents/payload-sanitizer.js');
+console.log(JSON.stringify(sanitizePayload(JSON.parse(require('fs').readFileSync(0))), null, 2));
+"
+```