ronitchidara 5aae2aa197 security: comprehensive pre-PR security audit fixes (rebased)

2026-01-28 17:03:07 +05:30

8.6 KiB

Raw Blame History

Enterprise Deployment Guide

This guide covers deployment patterns for enterprise environments with multiple users, teams, and security requirements.

Deployment Patterns

Single-Tenant (Recommended for Teams)

A single gateway serves one team with shared configuration:

┌─────────────────────────────────────────┐
│              Gateway Host               │
│  ┌─────────────────────────────────┐   │
│  │         Moltbot Gateway        │   │
│  │  - All team channels            │   │
│  │  - Shared agent config          │   │
│  │  - Team-wide RBAC               │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
         │           │           │
    ┌────┴───┐  ┌────┴───┐  ┌────┴───┐
    │ User A │  │ User B │  │ User C │
    └────────┘  └────────┘  └────────┘

Configuration:

# config.yaml
gateway:
  port: 18789
  auth:
    mode: token
    token: ${GATEWAY_TOKEN}

rbac:
  enabled: true
  defaultRole: user
  assignments:
    "admin@company.com": admin
    "dev@company.com": operator

Multi-Tenant (Isolated Teams)

Separate gateway instances per team for full isolation:

┌──────────────────┐  ┌──────────────────┐
│   Team A Host    │  │   Team B Host    │
│ ┌──────────────┐ │  │ ┌──────────────┐ │
│ │   Gateway A  │ │  │ │   Gateway B  │ │
│ │  Port 18789  │ │  │ │  Port 18790  │ │
│ └──────────────┘ │  │ └──────────────┘ │
└──────────────────┘  └──────────────────┘
        │                     │
   Team A Users          Team B Users

Benefits:

Complete data isolation between teams
Independent configuration and credentials
Separate audit logs per team
Different RBAC policies per team

Setup:

# Team A gateway
clawdbot config set gateway.port 18789
clawdbot config set gateway.auth.token "team-a-token"

# Team B gateway (different host or port)
clawdbot config set gateway.port 18790
clawdbot config set gateway.auth.token "team-b-token"

Multi-Agent Routing

Route different users to different agents based on channel or identity:

# config.yaml
agents:
  main:
    model: claude-sonnet-4-20250514
    system: "You are a general assistant."

  devops:
    model: claude-sonnet-4-20250514
    system: "You are a DevOps specialist."
    tools:
      policy: elevated

  support:
    model: claude-sonnet-4-20250514
    system: "You are a customer support agent."
    tools:
      policy: read-only

bindings:
  - channel: slack
    channelId: "devops-channel"
    agentId: devops

  - channel: telegram
    senderId: "support-team"
    agentId: support

Per-User Agent Isolation

Give each user their own agent instance:

# config.yaml
agents:
  template:
    model: claude-sonnet-4-20250514
    session:
      mode: persistent
      dir: ~/.clawdbot/sessions/${senderId}

bindings:
  - channel: "*"
    agentId: template
    sessionKey: "${channel}:${senderId}"

Container Deployment

Docker

FROM node:22-alpine
RUN npm install -g clawdbot@latest
EXPOSE 18789
VOLUME /root/.clawdbot
CMD ["clawdbot", "gateway", "run", "--bind", "0.0.0.0"]

# docker-compose.yaml
services:
  clawdbot:
    image: clawdbot:latest
    ports:
      - "18789:18789"
    volumes:
      - ./config:/root/.clawdbot
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GATEWAY_TOKEN=${GATEWAY_TOKEN}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Kubernetes

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: clawdbot-gateway
spec:
  replicas: 1
  selector:
    matchLabels:
      app: clawdbot
  template:
    metadata:
      labels:
        app: clawdbot
    spec:
      containers:
        - name: gateway
          image: clawdbot:latest
          ports:
            - containerPort: 18789
          env:
            - name: ANTHROPIC_API_KEY
              valueFrom:
                secretKeyRef:
                  name: clawdbot-secrets
                  key: anthropic-api-key
          livenessProbe:
            httpGet:
              path: /health
              port: 18789
            initialDelaySeconds: 10
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /ready
              port: 18789
            initialDelaySeconds: 5
            periodSeconds: 10
          volumeMounts:
            - name: config
              mountPath: /root/.clawdbot
      volumes:
        - name: config
          configMap:
            name: clawdbot-config

# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: clawdbot
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "18789"
    prometheus.io/path: "/metrics"
spec:
  selector:
    app: clawdbot
  ports:
    - port: 18789
      targetPort: 18789

High Availability

Load Balancing Considerations

Moltbot gateway is stateful (WebSocket connections, session state). For HA:

Sticky sessions - Route users to the same instance
Shared state - Use external session storage (future feature)
Active-passive - Run standby instance for failover

Health Endpoints

Configure your load balancer to use:

Liveness: GET /health - Returns 200 if process is alive
Readiness: GET /ready - Returns 200 if channels are connected

Graceful Shutdown

The gateway handles SIGTERM gracefully:

Stops accepting new connections
Completes in-flight requests
Closes WebSocket connections cleanly
Flushes audit logs

Network Configuration

Firewall Rules

Port	Direction	Purpose
18789	Inbound	Gateway WebSocket/HTTP
443	Outbound	Anthropic API, channel APIs

Reverse Proxy

With nginx:

upstream clawdbot {
    server localhost:18789;
}

server {
    listen 443 ssl;
    server_name gateway.company.com;

    ssl_certificate /etc/ssl/certs/gateway.crt;
    ssl_certificate_key /etc/ssl/private/gateway.key;

    location / {
        proxy_pass http://clawdbot;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}

Configure trusted proxies in Moltbot:

gateway:
  trustedProxies:
    - "10.0.0.0/8"
    - "172.16.0.0/12"
    - "192.168.0.0/16"

Environment Variables

Variable	Description
`ANTHROPIC_API_KEY`	API key for Claude models
`GATEWAY_TOKEN`	Gateway authentication token
`CLAWDBOT_CONFIG_PATH`	Custom config file path
`CLAWDBOT_STATE_DIR`	State directory (sessions, logs)
`LOG_LEVEL`	Logging verbosity (debug, info, warn, error)

Backup and Recovery

Critical Data

Path	Description	Backup Priority
`~/.clawdbot/config.yaml`	Configuration	High
`~/.clawdbot/credentials/`	Channel tokens, pairing	High
`~/.clawdbot/sessions/`	Session history	Medium
`~/.clawdbot/audit.jsonl`	Audit logs	High

Backup Script

#!/bin/bash
BACKUP_DIR="/backups/clawdbot/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Config and credentials (encrypted)
tar -czf "$BACKUP_DIR/config.tar.gz" \
  ~/.clawdbot/config.yaml \
  ~/.clawdbot/credentials/

# Audit logs
cp ~/.clawdbot/audit*.jsonl "$BACKUP_DIR/"

# Retain 30 days
find /backups/clawdbot -mtime +30 -delete

Next Steps

Security Hardening - TLS, rate limiting, audit configuration
Observability - Metrics, tracing, dashboards
Gateway Configuration - Full configuration reference

8.6 KiB Raw Blame History