Security & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
Clawdbot implements a multi-layered security and authentication system designed to protect the gateway, manage user identities, and secure communication channels. The system architecture encompasses gateway connection security, channel-specific DM policies, and automated security auditing via the "doctor" utility. Authentication is handled through a combination of passwords, environment-level tokens, and cryptographic device identities.
The primary goal of the security subsystem is to ensure that only authorized clients and devices can interact with the Clawdbot gateway while maintaining strict isolation between user sessions when multiple senders are present. This is achieved through configurable DM scopes and rigorous handshake protocols during gateway connection establishment.
Gateway Authentication Mechanisms
The Clawdbot gateway supports several authentication modes to secure WebSocket connections. These modes are verified during the initial handshake process when a client attempts to connect to the gateway server.
Authentication Modes
| Mode | Description | Configuration Source |
|---|---|---|
| Default | Standard handshake returning a hello-ok payload with a system snapshot. | src/gateway/server.auth.e2e.test.ts:47-66 |
| Password | Requires a plain-text password match configured in the gateway state. | src/gateway/server.auth.e2e.test.ts:133-145 |
| Token | Uses a secret token, typically provided via environment variables. | src/gateway/server.auth.e2e.test.ts:153-170 |
| Device Identity | Cryptographic authentication using public/private key pairs and signed payloads. | src/gateway/server.auth.e2e.test.ts:241-270 |
Connection Handshake Flow
When a client initiates a connection, the server sends a connect.challenge containing a unique nonce. The client must respond with valid credentials (password, token, or signed device identity) within a specified timeout period, or the connection is terminated.
Channel Security & DM Policies
Clawdbot manages how external users interact with the bot through "Direct Message (DM) Policies." These policies define who can send messages and how sessions are isolated.
DM Policy Types
- Open: Anyone can message the bot. This requires the configuration to include a wildcard (
*) in theallowFromlist. - Locked/Restricted: Only specific users in the allowlist can interact. Unknown senders are blocked or prompted for a pairing code.
- Disabled: DM functionality is completely turned off for the specific channel.
Sources: src/commands/doctor-security.ts:25-50
Session Isolation (DM Scope)
To prevent multiple users from interfering with each other's data, the system supports session isolation via the session.dmScope setting.
- Main Scope: Multiple senders share a single global session. The security auditor warns against this when multiple senders are detected.
- Per-Channel-Peer: Isolates sessions so that each sender has their own unique context and state.
Sources: src/commands/doctor-security.ts:52-57
Automated Security Auditing
The doctor command includes a specialized security audit module that scans the current configuration for vulnerabilities and misconfigurations.
Audit Checks and Warnings
The audit system performs the following checks:
- DM Policy Validity: Ensures "open" policies have wildcards and that locked policies have defined users.
- Session Integrity: Checks for shared sessions in multi-user environments.
- State Directory Presence: Verifies the existence of the critical state directory (where credentials and sessions are stored).
- Auth Token Presence: Checks if
CLAWDBOT_GATEWAY_TOKENis set when running in local mode. - Provider Overrides: Warns if specific providers (like OpenCode) have potentially insecure API overrides.
Device Identity and Pairing
For high-security contexts (like the Control UI), Clawdbot requires Device Identity pairing. This involves cryptographic signing of payloads to prove device ownership.
Pairing Scopes
Devices can be granted specific scopes, such as operator.read or operator.admin. Upgrading a device's scope requires a new pairing approval flow.
Revocation
Tokens associated with a specific device and role can be revoked. Once revoked, the gateway will reject any connection attempts using that token, even if the cryptographic signature is otherwise valid.
Sources: src/gateway/server.auth.e2e.test.ts:286-340, src/gateway/server.auth.e2e.test.ts:342-378
Operational Security Guidelines
The project maintains a strict security policy for reporting and hardening the system.
- Private Reporting: Security issues should be reported privately to
steipete@gmail.com. - Deep Audits: Users are encouraged to run
clawdbot security audit --deepfor comprehensive hardening. - Environment Variables: Sensitive credentials should be managed via
~/.profileor specific environment variables rather than hardcoded in configuration files.
Sources: SECURITY.md:1-12, CLAUDE.md:120-125
Auth Monitoring
A systemd-based auth monitor is available to check token expiry (e.g., for Claude API tokens) every 30 minutes and send notifications via ntfy.sh or direct phone alerts.
Sources: scripts/setup-auth-system.sh:44-70
Conclusion
Clawdbot's security architecture is built on the principle of least privilege and explicit authorization. By combining robust WebSocket handshakes, granular DM policies, and automated auditing, the system provides a secure environment for hosting AI agents. Developers and administrators should prioritize running regular security audits and ensuring session isolation in multi-user deployments to maintain system integrity.