AgentDefender for Cloudron

Security monitoring and network policy enforcement for Cloudron

Overview

AgentDefender is a security monitoring system for Cloudron with two components:

Component	Status	Description
AgentDefenderUI	✅ Complete	Cloudron app for app inventory, risk scoring, and canary detection
AgentDefenderCLI	🚧 Scaffold	Host-level eBPF agent for network monitoring (Phase 2)

Quick Start

Install AgentDefenderUI (Phase 1)

# Build and install the Cloudron app
cd cloudron-agentdefenderui
# Use your Cloudron deployment scripts

Then configure:

1. Open AgentDefenderUI dashboard
2. Follow post-install steps to configure Cloudron API token
3. View app inventory with risk scores

Install AgentDefenderCLI (Phase 2)

Prerequisites:

• Linux kernel >= 5.15 with BTF support
• Root access to Cloudron host
• Docker running

Build:

cd agentdefender-cli
./build.sh
# Creates: bin/agentdefender-linux-amd64 (8.7MB static binary)

Deploy to Cloudron host:

Method 1: Using install script (recommended)

# Build and commit binary to repo first:
./build.sh
git add agentdefender-cli/bin/agentdefender-linux-amd64
git commit -m "Add built binary"
git push

# Then run install script:
curl -fsSL https://forgejo.tcjc.uk/cca/cloudron-agentdefenderui/raw/branch/main/agentdefender-cli/install.sh | sudo bash

Note: The install script installs to /root/agentdefender/:

# Binary location
/root/agentdefender/agentdefender

# Config location
/root/agentdefender/config/config.yaml

# Alternative: Manual installation
scp bin/agentdefender-linux-amd64 root@cloudron-host:/root/agentdefender/agentdefender

# SSH to host and create config
ssh root@cloudron-host <<'EOF'
mkdir -p /root/agentdefender/config
cat > /root/agentdefender/config/config.yaml <<'CONFIG'
enforce: false
webhook:
  url: "http://agentdefender-ui:3000/webhook/flows"
  secret: "$(openssl rand -hex 32)"
  flush_interval: 5s
docker_socket: /var/run/docker.sock
api:
  listen: 127.0.0.1:8080
canaries:
  admin_service_contact: { enabled: true, severity: critical }
  dashboard_contact: { enabled: true, severity: high }
  cotenant_contact: { enabled: true, severity: high }
  bridge_scan: { enabled: true, severity: critical, threshold: 20, window: 60s }
  external_egress: { enabled: true, severity: info }
default_policy: deny
allow_dns: true
apps: {}
CONFIG

# Install systemd service
cp /path/to/agentdefender.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable agentdefender
systemctl start agentdefender
EOF

Verify installation:

# On Cloudron host
systemctl status agentdefender
curl http://127.0.0.1:8080/health
# Expected: {"status":"ok","version":"0.1.0","enforce_mode":false,"phase":"2"}
journalctl -u agentdefender -f

Configure webhook integration:

1. Generate secret: openssl rand -hex 32
2. Update /root/agentdefender/config/config.yaml with the secret
3. In AgentDefenderUI Settings, enter the same webhook secret
4. Save settings

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Cloudron Host                            │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  AgentDefenderCLI (Phase 2)                            │  │
│  │  /root/agentdefender/agentdefender                     │  │
│  │  Monitors: All container network traffic               │  │
│  │  Sends: Webhook alerts to AgentDefenderUI              │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  AgentDefenderUI (Phase 1 - Cloudron App)              │  │
│  │  /app/code                                             │  │
│  │  Receives: Webhook alerts                              │  │
│  │  Displays: Dashboard, app inventory, canaries          │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Features

Phase 1: AgentDefenderUI

App Risk Scoring:

• Analyzes all Cloudron apps
• Scores based on addons (docker, ldap, mail, sql) and capabilities (net_admin, ping)
• Configurable thresholds and factor scores
• Risk levels: 5-Critical, 4-High, 3-Medium, 2-Low, 1-Minimal

Dashboard:

• Risk distribution chart
• High-risk apps list
• Recent canary events
• AgentDefenderCLI connection status

Canary Detection:

• Monitors Cloudron event log
• Detects admin service access (LDAP, Docker, Redis, Mail)
• Detects dashboard access
• Detects co-tenant communication

Settings:

• Cloudron API configuration with polling
• Webhook secret for CLI integration
• Risk configuration editor

Phase 2: AgentDefenderCLI (Scaffold)

Currently implemented:

• ✅ Configuration system (YAML)
• ✅ API server with /health endpoint
• ✅ Webhook secret generation
• ✅ Installation script and systemd service
• ✅ Build system (static binary)

Scaffolded (not yet implemented):

• 🚧 eBPF program for packet inspection
• 🚧 Docker container watcher
• 🚧 Flow processing and batching
• 🚧 Canary detection logic
• 🚧 Webhook delivery with HMAC auth

Phase 3: Enforcement (Future)

• Policy enforcement with eBPF DROP verdicts
• Per-app egress allowlists
• Policy management UI
• Connection tracking

Configuration Reference

AgentDefenderUI Settings

Field	Description	Default
cloudronApiToken	Cloudron API token	(required)
cloudronApiUrl	Cloudron API URL	https://my.cloudron.uk
pollInterval	App sync interval (seconds)	60
webhookSecret	CLI webhook authentication	(generated)

AgentDefenderCLI Config (/root/agentdefender/config/config.yaml)

enforce: false  # Phase 2 (observe) or Phase 3 (enforce)

webhook:
  url: "http://agentdefender-ui:3000/webhook/flows"
  secret: "<64-char-hex-secret>"
  flush_interval: 5s

docker_socket: /var/run/docker.sock

api:
  listen: 127.0.0.1:8080

canaries:
  admin_service_contact:
    enabled: true
    severity: critical
  dashboard_contact:
    enabled: true
    severity: high
  cotenant_contact:
    enabled: true
    severity: high
  bridge_scan:
    enabled: true
    severity: critical
    threshold: 20
    window: 60s
  external_egress:
    enabled: true
    severity: info

default_policy: deny
allow_dns: true
apps: {}  # Synced from AgentDefenderUI

Data Storage

AgentDefenderUI (/app/data/):

• settings.json - Configuration (encrypted)
• apps.json - App inventory with risk scores
• canaries.json - Canary event log (10k events ring buffer)
• flows.json - Network flows from CLI (50k events ring buffer)
• policies.json - Per-app egress policies (Phase 3)

AgentDefenderCLI (/etc/agentdefender/):

• config.yaml - Configuration file

Security Model

AgentDefenderUI:

• Cloudron app isolation (localstorage addon)
• Encrypted settings storage
• Webhook authentication via shared secret

AgentDefenderCLI:

• Static binary (no system dependencies)
• eBPF JIT-compiled (no kernel modules)
• Uses eBPF DROP verdicts (no iptables modifications)
• Read-only Docker socket access
• Localhost-only API (127.0.0.1:8080)
• Capabilities: CAP_NET_ADMIN, CAP_BPF, CAP_PERFMON

Troubleshooting

Service won't start:

journalctl -u agentdefender -n 50
# Check: binary executable, config valid, port available

Webhook not working:

# Verify secret matches in both CLI config and UI settings
# Test connectivity:
curl -X POST http://agentdefender-ui:3000/webhook/flows \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Kernel too old:

uname -r  # Must be >= 5.15 for eBPF features

Uninstall

AgentDefenderUI:

cloudron uninstall --app agentdefender

AgentDefenderCLI:

sudo systemctl stop agentdefender
sudo systemctl disable agentdefender
sudo rm /usr/local/bin/agentdefender \
      /etc/systemd/system/agentdefender.service
sudo rm -rf /etc/agentdefender
sudo systemctl daemon-reload

Repository

• Main Repo: https://forgejo.tcjc.uk/cca/cloudron-agentdefenderui
• CLI Repo: https://forgejo.tcjc.uk/cca/cloudron-agentdefenderui/agentdefender-cli
• Design Spec: local/dev-spec.md

Status

Phase	Component	Status
Phase 1	AgentDefenderUI	✅ Complete
Phase 2	AgentDefenderCLI	🚧 Scaffold
Phase 3	Enforcement	🎯 Future

License

MIT