Skip to content

enforcement-integrations.md

Latest commit

 

History

History
310 lines (235 loc) · 8.71 KB

enforcement-integrations.md

File metadata and controls

310 lines (235 loc) · 8.71 KB

Enforcement & Observability Integrations

g0 generates configuration for third-party enforcement and observability tools. No kernel modules or privileged access is required in g0 itself — it produces config files that these tools consume.

Tetragon (eBPF Enforcement)

Tetragon is a Cilium project that enforces security policies at the kernel level using eBPF. g0 generates TracingPolicy CRDs for OpenClaw deployments.

Generated Policies

g0 generates 6 Tetragon TracingPolicies:

Policy Kernel Hook Action Purpose
g0-openclaw-egress sys_connect Sigkill/Post Block unauthorized outbound connections
g0-openclaw-cross-agent sys_openat Sigkill/Post Prevent cross-agent file access
g0-openclaw-docker-socket sys_openat Sigkill/Post Block Docker socket access
g0-openclaw-sensitive-binary sys_execve Post Alert on curl, wget, nc, ssh execution
g0-openclaw-credential-protection sys_openat Post Alert on .env, key file access
g0-openclaw-log-protection sys_unlinkat/sys_truncate Post Alert on log file deletion/truncation

Modes

  • Observe mode (default): Policies use Post action — events are logged but processes are not killed
  • Enforce mode (enforce: true): Critical policies use Sigkill — violating processes are killed immediately

Usage

# Generate policies (observe mode)
g0 scan . --openclaw-audit /path/to/agents --json | jq '.tetragonPolicies'

# Programmatic usage
import { generateTetragonRules } from '@guard0/g0';

const result = generateTetragonRules({
  agentDataPath: '/data/openclaw/agents',
  egressAllowlist: ['104.18.0.0/16', '52.0.0.0/8'],
  enforce: false,  // observe mode
});

// Write policies
fs.writeFileSync('tetragon-policies.yaml', result.yaml);

// Get Docker Compose snippet
fs.writeFileSync('docker-compose.tetragon.yml', result.dockerCompose);

Deployment

# docker-compose.tetragon.yml (generated by g0)
services:
  tetragon:
    image: quay.io/cilium/tetragon:v1.3
    privileged: true
    pid: host
    volumes:
      - /sys/kernel:/sys/kernel
      - /proc:/procHost
      - ./tetragon-policies:/etc/tetragon/tetragon.tp.d:ro
    command:
      - tetragon
      - --export-filename=/var/log/tetragon/events.log
# Install policies
cp g0-openclaw-*.yaml /etc/tetragon/tetragon.tp.d/

# Deploy
docker compose -f docker-compose.tetragon.yml up -d

# Tail events
docker exec tetragon tetra getevents -o compact

Event Forwarding to g0 Daemon

Tetragon events can be forwarded to the g0 daemon event receiver:

// daemon.json
{
  "eventReceiver": {
    "enabled": true,
    "port": 6040,
    "bind": "127.0.0.1"
  }
}

Use a sidecar or tetragon-events-exporter to POST JSONL events to http://localhost:6040/events.

Falco (Runtime Detection)

Falco is the cloud-native runtime security engine. g0 generates Falco rules for OpenClaw agent monitoring.

Generated Rules

g0 generates 9 Falco rules, 2 macros, and 2 lists:

Rule Priority Triggers On
g0_openclaw_unexpected_egress Warning Outbound connection to non-allowlisted destination
g0_openclaw_cross_agent_access Critical Agent reading another agent's data directory
g0_openclaw_credential_access Warning Reading .env or credential files in agent dirs
g0_openclaw_session_access Warning Reading session transcript .jsonl files
g0_openclaw_root_container Warning Container running as UID 0
g0_openclaw_sensitive_binary Warning Execution of curl, wget, nc, ssh in container
g0_openclaw_docker_socket_access Critical Access to /var/run/docker.sock
g0_openclaw_gateway_external_bind Critical Gateway binding to 0.0.0.0 instead of 127.0.0.1
g0_openclaw_log_tampering Critical Deletion or truncation of log files

Usage

# View generated rules in deployment audit output
g0 scan . --openclaw-audit /path/to/agents

# JSON output includes falcoRules field
g0 scan . --openclaw-audit /path/to/agents --json | jq -r '.falcoRules'

Deployment

# Copy generated rules
cp g0-openclaw-falco.yaml /etc/falco/rules.d/

# Restart Falco
systemctl restart falco

Falcosidekick Integration

Falcosidekick forwards Falco alerts to external systems. g0's daemon event receiver accepts Falcosidekick webhooks:

# docker-compose.falco.yml
services:
  falco:
    image: falcosecurity/falco:latest
    privileged: true
    volumes:
      - /dev:/host/dev
      - /proc:/host/proc:ro
      - /var/run/docker.sock:/var/run/docker.sock
      - ./g0-openclaw-falco.yaml:/etc/falco/rules.d/g0-openclaw.yaml:ro
    environment:
      - FALCO_HTTP_OUTPUT_URL=http://falcosidekick:2801

  falcosidekick:
    image: falcosecurity/falcosidekick:latest
    environment:
      - WEBHOOK_ADDRESS=http://host.docker.internal:6040/falco

Events arrive at the g0 daemon event receiver and are:

  1. Logged with source falcosidekick and rule name
  2. Included in drift detection
  3. Forwarded to configured webhook alerts (Slack/Discord/PagerDuty)

auditd (Kernel Audit Logging)

g0 generates auditd rules for monitoring file access, network connections, and process execution in OpenClaw agent directories.

Generated Rule Sections

Section What It Monitors
Agent data access Read/write to agent data directories
Credential file access Access to .env, API key files
Session file access Access to session transcript .jsonl files
Network connections Outbound connections from agent processes
Process execution Binary execution in agent contexts

Usage

# Generate rules
g0 scan . --openclaw-audit /path/to/agents --json | jq -r '.auditdRules'

# Apply rules
sudo cp g0-openclaw.rules /etc/audit/rules.d/
sudo augenrules --load

# Verify
sudo auditctl -l | grep g0

Daemon Enforcement

The daemon can automatically install auditd rules when observability checks fail:

// daemon.json
{
  "enforcement": {
    "applyAuditdRules": true
  }
}

iptables (Egress Filtering)

g0 generates iptables rules for the DOCKER-USER chain to restrict container egress.

Usage

# Generate from allowlist
# Allowlist entries are resolved to IPs via DNS

Daemon Enforcement

// daemon.json
{
  "openclaw": {
    "enabled": true,
    "egressAllowlist": ["api.anthropic.com", "api.openai.com"],
    "egressIntervalSeconds": 60
  },
  "enforcement": {
    "applyEgressRules": true
  }
}

The daemon's fast egress loop (default: every 60 seconds) scans active connections and:

  1. Logs violations
  2. Sends webhook alerts
  3. Applies iptables rules if enforcement is enabled

Event Receiver

The g0 daemon includes an HTTP event receiver that accepts events from all enforcement tools:

// daemon.json
{
  "eventReceiver": {
    "enabled": true,
    "port": 6040,
    "bind": "127.0.0.1",
    "authToken": "your-shared-secret"
  }
}

Endpoints

Method Path Source Auth
POST /events g0 OpenClaw plugin, Tetragon Bearer token
POST /falco Falcosidekick Bearer token
GET /health Monitoring None
GET /stats Monitoring None

Event Format

POST /events
{
  "source": "g0-plugin",
  "type": "injection-detected",
  "timestamp": "2026-03-10T10:00:00Z",
  "data": {
    "tool": "exec",
    "input": "ignore previous instructions"
  }
}

Security-relevant events (injection, tool-blocked) are logged at WARN level and fed into the behavioral baseline, kill switch, and correlation engine.

Plugin Security Notifications

By default, plugin events are only logged (mode off). To receive Slack/Discord/PagerDuty notifications, add notifications to your alerting config:

{
  "alerting": {
    "webhookUrl": "https://hooks.slack.com/services/...",
    "format": "slack",
    "notifications": {
      "mode": "interval",
      "intervalMinutes": 5
    }
  }
}

Modes:

  • off (default) — No notifications. Events still logged and processed by kill switch / correlation.
  • interval — Sends a single digest every N minutes with all accumulated events grouped by category.
  • realtime — Sends per-event alerts with rate limiting (max 1 per category per rateLimitSeconds, default 60s). Suppressed events are counted and included in the next alert.

Supported event types: injection.detected, tool.blocked, pii.redacted, pii.blocked_outbound, pii.detected, message.blocked, subagent.blocked, plus correlated threats from the correlation engine.