openclaw-secure-kit

Secure-by-default, profile-driven hardening for running OpenClaw on Ubuntu with verifiable egress guardrails.

This kit is designed to run after you have a host (Ubuntu + Docker), and before you start using OpenClaw in production. It generates a hardened, reproducible deployment under out/<profile>/ and provides a one-command verifier that writes a security report.

Note: v1 focuses on DNS allowlisting + host firewall guardrails. It does not guarantee impossible-bypass outbound control (see docs/THREAT_MODEL.md).

---

Table of contents

• Who this is for
• Who it’s not for
• Need this deployed for your team?
• Demo
• Quickstart
• How it works
• Profiles
• Verification (ocs doctor)
• Security model and caveats
• Install / uninstall
• Troubleshooting
• Docs
• Contact
• Contributing
• Security policy

---

Who this is for

• You need a hardened deployment posture you can reproduce across Ubuntu hosts using out/<profile>/ artifacts.
• You need verifier outputs (security-report.md) you can hand to security/IT reviewers and internal stakeholders.
• You need DNS allowlist + host firewall guardrails without building your own hardening pipeline from scratch.

Who it’s not for

• You need impossible-bypass outbound control guarantees (including guaranteed direct-to-IP blocking) in v1.
• You need cloud provisioning, a multi-tenant control plane, or a web UI in this release.
• You need ad-hoc manual setup instead of profile-driven, repeatable operations.

---

Need this deployed for your team?

This repo stays fully open-source. Want a hardened OpenClaw environment set up quickly with a shareable verifier report?

See docs/SERVICES.md.

---

Demo

---

Quickstart

Why sudo? The installer sets host controls (systemd/nftables) and installs to /opt.

git clone https://github.com/NinoSkopac/openclaw-secure-kit
cd openclaw-secure-kit
chmod +x install.sh

sudo ./install.sh

# Generate a hardened deployment under out/<profile>/
ocs install --profile research-only

# Start the generated stack
docker compose -f out/research-only/docker-compose.yml --env-file out/research-only/.env up -d

# Verify host + runtime controls and write reports
sudo ocs doctor --profile research-only

# Read the security checks report
cat out/research-only/security-report.md

Notes:

• The generated research-only profile is non-interactive by default (no manual “setup” step required).

---

How it works

1. You choose a profile (example: research-only).

2. ocs install generates a hardened deployment bundle under:

   out/<profile>/
     .env
     docker-compose.yml
     security-report.md   (security checks from doctor)
     doctor-report.md     (doctor preflight + orchestration checks)
   

3. You run Docker Compose using the generated .env + compose file.

4. ocs doctor verifies the host and runtime posture and writes a report you can hand to:

• teammates
• clients
• compliance/security reviewers

Architecture

---

Profiles

Profiles are intended to be simple, auditable, and repeatable.

• Start with an existing profile (e.g. research-only)
• Create additional profiles when you need different allowlists, exposure, or policy posture
• Output is always generated under out/<profile>/ so you can diff/commit internally if you want

Tip: if ports 18789/18790 are already in use, ocs install will auto-select free ports and write them into out/<profile>/.env. Always check the generated .env before connecting clients.

---

Verification (ocs doctor)

ocs doctor is the “trust but verify” step.

sudo ocs doctor --profile research-only --verbose

It writes:

• out/<profile>/security-report.md (security checks)
• out/<profile>/doctor-report.md (doctor preflight/orchestration checks)

And prints a summary like:

Wrote doctor report to out/research-only/doctor-report.md
Wrote security report to out/research-only/security-report.md
DOCTOR:   PASS: 10  WARN: 1  FAIL: 0
SECURITY: PASS: 11  WARN: 1  FAIL: 0

If doctor reports any FAIL, treat the host as not compliant until fixed.

Strict IP egress check (optional)

DNS allowlisting controls domain resolution, but it cannot block direct HTTPS connections to raw IPs by itself.

• Default policy: network.direct_ip_policy: warn
• Strict policy: network.direct_ip_policy: fail (or network.strict_ip_egress: true)
• One-off strict run:

sudo ocs doctor --profile research-only --strict-ip-egress

---

Security model and caveats

What v1 focuses on

• domain-level egress control (DNS allowlist + host firewall)
• loopback-first gateway exposure (not public by default)
• non-root containers
• secrets externalized (OPENCLAW_GATEWAY_TOKEN stays in .env)
• pinned image tags (no latest)

What v1 does not guarantee

This is not an “impossible-bypass” outbound control model.

Direct-to-IP HTTPS may still work (example: https://1.1.1.1) even when non-allowlisted domains are blocked by DNS policy. Do not claim v1 makes egress bypass impossible.

Assumptions

• end-users do not have SSH access to the host
• workloads do not mount the Docker socket
• deployment target is Ubuntu 22.04/24.04 with Docker

See the threat model doc for guarantees, assumptions, limitations, and hardening roadmap.

---

Install / uninstall

Install

chmod +x install.sh
sudo ./install.sh

Common options:

sudo ./install.sh --dry-run
sudo ./install.sh --no-deps
sudo ./install.sh --prefix /srv/openclaw-secure-kit
sudo ./install.sh --force
sudo ./install.sh --version

Curl | bash

curl -fsSL https://raw.githubusercontent.com/NinoSkopac/openclaw-secure-kit/refs/heads/main/install.sh | bash

Uninstall

sudo ./uninstall.sh
sudo ./uninstall.sh --purge
sudo ./uninstall.sh --purge --prefix /srv/openclaw-secure-kit

By default, uninstall.sh also tears down generated compose stacks found under out/*/docker-compose.yml. Use ./uninstall.sh --no-down to skip stack teardown.

---

Troubleshooting

“I don’t see tmpfs mounts in docker inspect ... .Mounts”

On fresh installs, /home/node/.openclaw/canvas and /home/node/.openclaw/cron are intentionally mounted as tmpfs overlays to avoid bind-mount permission issues.

tmpfs entries don’t show up under .Mounts. Inspect .HostConfig.Tmpfs instead:

cd out/research-only
CID="$(docker compose --env-file .env ps -q openclaw-gateway)"
docker inspect "$CID" --format '{{json .HostConfig.Tmpfs}}' | jq .
docker compose --env-file .env exec openclaw-gateway sh -lc 'mount | rg openclaw'

Port collisions

If ports are busy, ocs install auto-selects new ones. Verify:

cat out/research-only/.env | rg 'OPENCLAW_.*PORT'

“Doctor results differ when not using sudo”

Run doctor with sudo for reliable host/runtime checks:

sudo ocs doctor --profile research-only --verbose

---

Docs

• Services: docs/SERVICES.md
• Threat model: docs/THREAT_MODEL.md
• Quickstart: docs/QUICKSTART.md
• Install guide: docs/INSTALL.md
• Hardening notes: docs/HARDENING.md
• Public release checklist: docs/PUBLIC_RELEASE_CHECKLIST.md

---

Contributing

PRs welcome. See CONTRIBUTING.md.

---

Security policy

Please report security issues privately. See SECURITY.md.