OxiBot runs autonomous agent loops that can execute shell commands, read/write files, and interact with external APIs. This guide covers how to deploy it safely.

1. Reporting Vulnerabilities
2. Threat Model
3. Workspace Sandbox
4. User Allowlists
5. API Key Management
6. Docker Hardening
7. Network Security
8. Tool Restrictions
9. Logging & Auditing
10. Security Checklist

If you discover a security issue, please do NOT open a public GitHub issue.

Instead, email security@diocrafts.com with:

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

We will respond within 72 hours and aim to release a patch within 7 days for critical issues.

OxiBot is designed as a personal assistant — typically running on your own machine or a private server. The primary threats are:

The most important security control. When enabled, the agent's file/directory tools are restricted to ~/.oxibot/workspace/.

{
  "tools": {
    "restrictToWorkspace": true
  }
}

Or via environment variable:

export OXIBOT_TOOLS__RESTRICT_TO_WORKSPACE=true

Each channel supports an allowedUsers array. When set, only listed users can interact with the bot.

{
  "channels": {
    "telegram": {
      "token": "...",
      "allowedUsers": ["123456789"]
    },
    "discord": {
      "token": "...",
      "allowedUsers": ["987654321"]
    },
    "whatsapp": {
      "bridgeUrl": "ws://localhost:3001",
      "allowedUsers": ["+1234567890"]
    },
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "allowedUsers": ["U01ABCDEF"]
    },
    "email": {
      "allowedUsers": ["trusted@example.com"]
    }
  }
}

# Hardcoding keys in shell history
export OXIBOT_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-abc123  # In .bashrc

Option 1: Config file with proper permissions

chmod 600 ~/.oxibot/config.json

Option 2: Environment variables from a secrets manager

# From 1Password
export OXIBOT_PROVIDERS__OPENROUTER__API_KEY=$(op read "op://Private/OxiBot/api-key")

Option 3: Docker secrets

# docker-compose.yml
services:
  oxibot:
    image: oxibot
    secrets:
      - oxibot_api_key
    environment:
      OXIBOT_PROVIDERS__OPENROUTER__API_KEY_FILE: /run/secrets/oxibot_api_key

secrets:
  oxibot_api_key:
    file: ./api_key.txt

Rotate API keys periodically:

1. Generate new key at provider dashboard
2. Update config.json or environment variable
3. Restart OxiBot (oxibot gateway)
4. Revoke old key at provider dashboard

The OxiBot Dockerfile already runs as non-root user oxibot. Additional hardening:

docker run -d \
  --name oxibot \
  --read-only \
  --tmpfs /tmp \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  --memory 128m \
  --cpus 0.5 \
  -v ~/.oxibot:/home/oxibot/.oxibot:rw \
  -p 127.0.0.1:18790:18790 \
  oxibot gateway

version: "3.8"
services:
  oxibot:
    build: .
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL
    mem_limit: 128m
    cpus: 0.5
    tmpfs:
      - /tmp
    volumes:
      - ~/.oxibot:/home/oxibot/.oxibot:rw
    ports:
      - "127.0.0.1:18790:18790"

OxiBot makes outbound HTTPS calls to:

• LLM provider APIs (OpenRouter, Anthropic, OpenAI, etc.)
• Channel APIs (Telegram Bot API, Discord Gateway, etc.)
• Tool URLs (web_get, web_search via Brave)

OxiBot does not expose any HTTP server by default. All channels use outbound polling or WebSocket connections:

The only inbound port is the heartbeat/health endpoint on port 18790 (configurable, optional).

# Allow outbound HTTPS only
iptables -A OUTPUT -p tcp --dport 443 -j ACCEPT
iptables -A OUTPUT -p tcp --dport 993 -j ACCEPT  # IMAP (if using email)
iptables -A OUTPUT -p tcp --dport 587 -j ACCEPT  # SMTP (if using email)

# Block all other outbound
iptables -A OUTPUT -j DROP

The agent has access to these built-in tools:

Mitigations:

• Enable restrictToWorkspace to sandbox file/dir tools
• Use allowedUsers to restrict who can trigger tool use
• Run in Docker with minimal capabilities
• Monitor agent logs for suspicious activity

Enable verbose logging to track agent activity:

# Full debug logs
RUST_LOG=debug oxibot gateway

# Agent-specific logs
RUST_LOG=oxibot_agent=debug oxibot gateway

# Log to file
RUST_LOG=info oxibot gateway 2>&1 | tee -a /var/log/oxibot.log

Key events to monitor:

• tool_call: bash — Shell commands executed
• tool_call: write_file — Files modified
• incoming_message — User messages received
• auth_rejected — Unauthorized access attempts

Use this checklist before deploying OxiBot in production:

• Set restrictToWorkspace: true
• Configure allowedUsers for every channel
• Set chmod 600 ~/.oxibot/config.json
• Use environment variables or secrets manager for API keys
• Run as non-root user (Docker image does this by default)

• Run in Docker with hardening flags
• Use --read-only container filesystem
• Limit container memory and CPU
• Bind health port to localhost only
• Enable verbose logging for auditing
• Set up log rotation

• Use Docker secrets for API keys
• Configure firewall rules (outbound HTTPS only)
• Run in dedicated VM or namespace
• Set up alerting on auth_rejected events
• Regular API key rotation schedule
• Periodic dependency audit (cargo audit)

_{Security is a shared responsibility. If you find a vulnerability, please report it responsibly.}