MasterClaw takes security seriously. This document outlines our security practices, how to report vulnerabilities, and the security features built into the ecosystem.
| Version | Supported |
|---|---|
| 0.21.x | ✅ |
| < 0.20 | ❌ |
If you discover a security vulnerability in MasterClaw, please report it responsibly:
- Do not open a public issue
- Email security concerns to: rexdeus@gmail.com
- Include:
- Description of the vulnerability
- Steps to reproduce
- Potential impact
- Suggested fix (if any)
We aim to respond within 48 hours and will work with you to understand and address the issue promptly.
All user inputs are validated and sanitized:
- Container names: Validated against whitelist pattern (
/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/) - File paths: Path traversal attempts (
../,..\) are blocked - Command arguments: Dangerous characters (
;,|,&,`) are rejected - Log entries: Control characters and newlines are sanitized to prevent log injection
- JSON inputs: Depth-limited parsing with prototype pollution protection
Command rate limiting prevents abuse:
| Category | Commands | Limit | Window |
|---|---|---|---|
| High Security | config-audit, exec, restore |
3-10 | 1-5 min |
| Deployment | deploy, revive |
5-10 | 1-5 min |
| Data Modification | cleanup, import |
5-10 | 1 min |
| Read-Only | status, logs, validate |
30-60 | 1 min |
Service resilience through circuit breaker pattern:
- Opens after 3 consecutive failures
- Automatic recovery testing in half-open state
- Per-service isolation prevents cascading failures
All security-relevant events are logged with HMAC-SHA256 signatures:
- Authentication attempts (success/failure)
- Security violations
- Configuration changes
- Container executions
- Backup/restore operations
Tamper Detection: Audit log integrity can be verified with mc audit-verify
Secure handling of API keys and tokens:
- Secrets stored with
0o600file permissions - Masked display by default (show first/last 4 chars only)
- Format validation for API keys
- Audit logging of all secret operations (values never logged)
The mc exec command includes multiple protections:
- Container whitelist (only MasterClaw containers allowed)
- Command injection prevention
- Blocked dangerous commands:
rm,dd,mkfs,fdisk - 5-minute timeout for non-interactive commands
- All executions logged for security review
Comprehensive error handling prevents information leakage:
- Sensitive data (tokens, passwords) automatically masked in logs
- User-friendly error messages without technical details
- Proper exit codes for CI/CD integration
- Structured JSON output mode for production environments
Distributed tracing via correlation IDs:
- Automatic generation for each command execution
- Propagates through logs, audit entries, and HTTP headers
- Prevents log injection (max 64 chars, alphanumeric +
_-) - Enables request tracing across services
- Keep tokens secure: Store
GATEWAY_TOKENand API keys in environment variables or secure vaults - Regular audits: Run
mc securityandmc config-auditperiodically - Verify backups: Use
mc backup-verifyto ensure backups are restorable - Monitor audit logs: Review
mc auditoutput for suspicious activity - Update regularly: Keep MasterClaw updated to latest version
- Validate all inputs: Use
lib/security.jsutilities for input validation - Sanitize logs: Use
sanitizeForLog()andmaskSensitiveData()for all logged output - Use wrapCommand: Wrap all command handlers with
wrapCommand()for automatic error handling - Audit security events: Log security violations with
logSecurityViolation() - Test security features: Add tests for security validation in
tests/*.security.test.js
The mc performance command implements comprehensive security hardening:
Input Validation:
- All numeric parameters (
n,limit) are validated and bounded - Maximum limits prevent DoS (100 endpoints, 1000 profiles)
- Safe integer validation prevents overflow attacks
- String inputs are parsed with validation
Retry Logic with Exponential Backoff:
- Prevents thundering herd with jitter (±25%)
- Only retries transient errors (network, 5xx, 429)
- Bounded delays prevent resource exhaustion
Correlation ID Propagation:
- Distributed tracing via
x-correlation-idheader - Enables request tracking across services
- Automatic integration with existing correlation system
Response Safety:
- Maximum response size (1MB) prevents memory exhaustion
- Configurable timeout bounds (1s - 60s)
- Sensitive data masking in error messages
Run the security-focused test suite:
cd masterclaw-tools
npm test -- --testNamePattern="security"Security test coverage includes:
- Path traversal prevention
- Command injection blocking
- Log injection sanitization
- Prototype pollution protection
- Rate limiting enforcement
- SSL/TLS validation
- Audit log integrity
- Day 0: Vulnerability reported
- Day 2: Acknowledgment and initial assessment
- Day 7: Patch developed and tested
- Day 14: Patch released and security advisory published
Critical vulnerabilities may be addressed sooner.
# Security scan
mc security # Full security scan
mc security --status # Quick status check
# Configuration audit
mc config-audit # Audit config file permissions
mc config-fix # Fix config permissions
# Audit log review
mc audit # View recent audit entries
mc audit-verify # Verify audit log integrity
# Rate limiting
mc rate-limit # View rate limit status
# Circuit breaker
mc circuits # View circuit breaker statusMasterClaw's security features help with:
- SOC 2: Audit logging, access controls, monitoring
- GDPR: Data retention policies, secure deletion
- HIPAA: Audit trails, access logging (when properly configured)
We thank security researchers and contributors who help improve MasterClaw's security.
Last updated: February 2026