Security Best Practices
Relevant source files
The following files were used as context for generating this wiki page:
Security in Kamal is centered on the protected handling of sensitive credentials, secure command execution via SSH, and robust validation of network configurations. The system is designed to prevent secret leakage in logs, ensure valid identity verification for load balancers, and maintain deployment integrity through locking mechanisms.
Key architectural components include the Kamal::Secrets system for environment-aware credential management, Kamal::Utils::Sensitive for log redaction, and a comprehensive validation layer in Kamal::Configuration that audits proxy settings and network access controls before deployment.
Secret Management and Redaction
Kamal employs a multi-layered approach to handling sensitive data to ensure that passwords, tokens, and private keys are never exposed in cleartext within human-readable logs or standard output.
Sensitive Data Redaction
The Kamal::Utils::Sensitive class acts as a wrapper for strings that should not be displayed. It implements a redaction attribute that defaults to [REDACTED]. The Kamal::Utils.redacted method recursively traverses hashes and arrays to ensure all sensitive objects are replaced by their redacted forms before YAML output or logging.
Secret Resolution Flow
Secrets are resolved early in the deployment lifecycle via validate_secrets!. This method ensures that registry credentials, builder secrets, and accessory environment variables are accessible before any remote operations begin, preventing mid-deploy failures due to missing credentials.
| Secret Category | Description | Source File |
|---|---|---|
| Registry | Username and password for Docker registry authentication. | lib/kamal/configuration.rb:108-109 |
| Proxy SSL | Private keys and certificates for custom TLS termination. | lib/kamal/configuration.rb:116-117 |
| Environment | Application-level secrets defined in .kamal/secrets. | lib/kamal/configuration.rb:112 |
Sources: lib/kamal/configuration.rb:104-123
Network and Proxy Security
Kamal validates proxy configurations to prevent common misconfigurations that could lead to identity spoofing or unauthorized access.
Client IP and Trust
A critical security check involves the proxy_protocol and trusted_proxies settings. If proxy_protocol is enabled without restricting allowed IPs, the proxy may honor headers from untrusted peers, leading to address spoofing in access logs and rate limiters.
TLS and SSL Integrity
The configuration validator enforces strict rules for SSL/TLS:
- Minimum TLS: Refuses versions 1.0 and 1.1; requires 1.2 or 1.3.
- Host Uniqueness: Prevents different roles from sharing the same host for SSL to avoid certificate conflicts.
- On-Demand TLS: Blocks the combination of
on_demand_urlwith fixed hosts or custom certificates to maintain clear certificate management boundaries.
Sources: lib/kamal/configuration.rb:453-459, lib/kamal/configuration/validator/proxy.rb:448-464
Command Execution Security
Kamal ensures that commands executed on remote servers are sanitized and that the deployment process itself is protected from concurrent modification.
Shell Escaping
To prevent command injection, the Kamal::Utils.escape_shell_value method sanitizes inputs by handling ASCII and non-ASCII characters. It specifically targets characters like backticks and dollar signs (without shell expansion syntax) to prevent unintended subshell execution.
Sources: lib/kamal/utils.rb:74-88
Deployment Locking
To maintain system integrity, Kamal implements a deployment lock. This prevents multiple users or CI processes from deploying to the same service simultaneously.
| Component | Security Function |
|---|---|
| Acquire Lock | Creates a directory on the primary host; fails if it exists. |
| Lock Details | Stores version, message, and performer to provide audit trails. |
| Manual Lock | Detects manual maintenance locks and prevents automatic overrides. |
Sources: lib/kamal/cli/base.rb:149-215
Auditor and Logging
Kamal maintains an audit log on the remote servers. The audit command allows developers to inspect the history of operations performed on the server, ensuring accountability for deployment actions. This log is typically stored at .kamal/app-audit.log.
Sources: lib/kamal/cli/main.rb:113-118, .claude/commands/security.md
Deployment operations are wrapped in modify blocks which instrument notifications and ensure that logs are broadcasted to configured outputs while maintaining the configured verbosity levels to prevent leaking too much internal state in standard production environments.
Sources: lib/kamal/commander.rb:128-138
Summary
Kamal’s security architecture prioritizes the protection of credentials through a dedicated Sensitive wrapper and early validation of Secrets. It enforces network best practices by validating proxy trust relationships and TLS versions. Deployment integrity is managed through a primary-host-based locking mechanism, while command safety is maintained via rigorous shell escaping and audit logging. Developers should prioritize using the built-in secret resolution and avoid disabling healthchecks or IP restrictions in proxy configurations.