From 18582fe9c8ce67b4ddd574e8eed6c59d805e6e2a Mon Sep 17 00:00:00 2001 From: argenis de la rosa Date: Sat, 14 Feb 2026 03:45:37 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20lean=20README=20=E2=80=94=20remove=20re?= =?UTF-8?q?dundant=20security=20layers,=20project=20tree,=20test=20coverag?= =?UTF-8?q?e=20table=20(445=E2=86=92215=20lines)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 229 ------------------------------------------------------ 1 file changed, 229 deletions(-) diff --git a/README.md b/README.md index b1021ae..ba74cf5 100644 --- a/README.md +++ b/README.md @@ -119,113 +119,6 @@ ZeroClaw enforces security at **every layer** — not just the sandbox. It passe > **Run your own nmap:** `nmap -p 1-65535 ` — ZeroClaw binds to localhost only, so nothing is exposed unless you explicitly configure a tunnel. -### Layer 1: Gateway Hardening - -```bash -# Default — localhost only, pairing required -zeroclaw gateway - -# Random port — OS assigns ephemeral port (49152-65535) -zeroclaw gateway --port 0 - -# With tunnel — public access via secure tunnel only -zeroclaw gateway # with [tunnel] configured -``` - -On startup, the gateway prints a **6-digit pairing code**: - -``` -🔐 PAIRING REQUIRED — use this one-time code: - ┌──────────────┐ - │ 482917 │ - └──────────────┘ - Send: POST /pair with header X-Pairing-Code: 482917 -``` - -After pairing, all subsequent requests use `Authorization: Bearer zc_`. - -```toml -[gateway] -require_pairing = true # default: true -allow_public_bind = false # default: false — NEVER set true without tunnel -``` - -### Layer 2: Channel Authentication - -Every channel validates the sender **before** the message reaches the agent loop: - -| Channel | Auth Method | Config | -|---------|------------|--------| -| **Telegram** | `allowed_users` list (username match) | `[channels.telegram] allowed_users` | -| **Discord** | `allowed_users` list (user ID match) | `[channels.discord] allowed_users` | -| **Slack** | `allowed_users` list (user ID match) | `[channels.slack] allowed_users` | -| **Matrix** | `allowed_users` list (MXID match) | `[channels.matrix] allowed_users` | -| **iMessage** | `allowed_contacts` list | `[channels.imessage] allowed_contacts` | -| **Webhook** | `X-Webhook-Secret` header (shared secret) | `[channels.webhook] secret` | -| **CLI** | Local-only (inherently trusted) | — | - -> **Note:** An empty `allowed_users` list or `["*"]` allows all users (open mode). Set specific IDs for production. - -### Layer 3: Rate Limiting - -- **Sliding-window tracker** — counts actions within a 1-hour rolling window -- **`max_actions_per_hour`** — hard cap on tool executions (default: 20) -- **`max_cost_per_day_cents`** — daily cost ceiling (default: $5.00) - -### Layer 4: Filesystem Sandbox - -- **Workspace-only mode** (default) — all paths must be relative to workspace -- **14 system directories blocked** — `/etc`, `/root`, `/home`, `/usr`, `/bin`, `/sbin`, `/lib`, `/opt`, `/boot`, `/dev`, `/proc`, `/sys`, `/var`, `/tmp` -- **4 sensitive dotfiles blocked** — `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config` -- **Null byte injection** — blocked at the path validation layer -- **Path traversal** — `..` in any position is rejected -- **Symlink escape detection** — `is_resolved_path_allowed()` verifies canonicalized paths stay inside workspace -- **Command allowlisting** — only approved shell commands (`git`, `cargo`, `ls`, etc.) -- **Autonomy levels** — `ReadOnly`, `Supervised` (default), `Full` - -### Layer 5: Secure Tunnels - -Expose your gateway securely — **bring your own tunnel provider**: - -| Provider | Binary | Use Case | -|----------|--------|----------| -| **none** | — | Local-only (default) | -| **cloudflare** | `cloudflared` | Cloudflare Zero Trust tunnel | -| **tailscale** | `tailscale` | Tailnet-only (`serve`) or public (`funnel`) | -| **ngrok** | `ngrok` | Quick public URLs, custom domains | -| **custom** | Any | Bring your own: bore, frp, ssh, WireGuard, etc. | - -```toml -[tunnel] -provider = "tailscale" # "none", "cloudflare", "tailscale", "ngrok", "custom" - -[tunnel.tailscale] -funnel = true # true = public internet, false = tailnet only - -# Or use Cloudflare: -# [tunnel] -# provider = "cloudflare" -# [tunnel.cloudflare] -# token = "your-tunnel-token" - -# Or ngrok: -# [tunnel] -# provider = "ngrok" -# [tunnel.ngrok] -# auth_token = "your-ngrok-token" -# domain = "my-zeroclaw.ngrok.io" # optional - -# Or bring your own: -# [tunnel] -# provider = "custom" -# [tunnel.custom] -# start_command = "bore local {port} --to bore.pub" -# url_pattern = "https://" # regex to extract URL from stdout -# health_url = "http://localhost:4040/api/tunnels" # optional -``` - -The tunnel starts automatically with `zeroclaw gateway` and prints the public URL. - ## Configuration Config: `~/.zeroclaw/config.toml` (created by `onboard`) @@ -275,17 +168,6 @@ enabled = false # opt-in: 1000+ OAuth apps via composio.dev | `/pair` | POST | `X-Pairing-Code` header | Exchange one-time code for bearer token | | `/webhook` | POST | `Authorization: Bearer ` | Send message: `{"message": "your prompt"}` | -### Random Port Mode - -Use `--port 0` for OS-assigned random ephemeral ports (security hardening against port scanning): - -```bash -zeroclaw gateway --port 0 -# Output: 🦀 ZeroClaw Gateway listening on http://127.0.0.1:54321 (random port) -``` - -The actual port is printed on startup and passed to the tunnel system automatically. - ## Commands | Command | Description | @@ -300,10 +182,6 @@ The actual port is printed on startup and passed to the tunnel system automatica | `tools test ` | Test a tool directly | | `integrations list` | List all 50+ integrations | -## Documentation Index - -Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt - ## Development ```bash @@ -317,113 +195,6 @@ cargo fmt # Format cargo test --test memory_comparison -- --nocapture ``` -### Test Coverage - -| Module | Tests | Covers | -|--------|-------|--------| -| **Memory (SQLite)** | 100+ | FTS5, vector search, hybrid merge, embeddings, chunker, SQL injection, unicode | -| **Security (Policy)** | 50+ | Path traversal, null bytes, forbidden dirs, workspace scoping, symlink escapes | -| **Security (Pairing)** | 20+ | Code generation, token issuance, constant-time comparison, replay prevention | -| **Gateway** | 20+ | Port 0, random port allocation, header extraction, port conflicts | -| **Config** | 30+ | Serde roundtrip, backward compat, secure defaults, gateway config | -| **Providers** | 30+ | Factory, custom URLs, auth styles | -| **Tools** | 20+ | Schema validation, tool specs, serde | -| **Integrations** | 15+ | Registry completeness, status functions, categories | -| **Tunnel** | 20+ | Factory, constructors, async behavior | - -## Project Structure - -``` -src/ -├── main.rs # CLI (clap) — 9 subcommands -├── lib.rs # Library exports (7 modules) -├── agent/ # Agent loop + memory context injection -│ ├── mod.rs -│ └── loop_.rs -├── channels/ # Channel trait + 7 implementations -│ ├── traits.rs # Channel trait definition -│ ├── cli.rs # Local terminal -│ ├── telegram.rs # Telegram Bot API -│ ├── discord.rs # Discord bot -│ ├── slack.rs # Slack bot -│ ├── matrix.rs # Matrix protocol -│ ├── imessage.rs # macOS iMessage -│ └── mod.rs # System prompt builder -├── config/ # TOML config schema -│ ├── schema.rs # All config structs + defaults -│ └── mod.rs -├── cron/ # Scheduled tasks -├── gateway/ # HTTP gateway (raw TCP + tokio) -│ └── mod.rs # /health, /pair, /webhook endpoints -├── heartbeat/ # Periodic task engine -│ ├── engine.rs -│ └── mod.rs -├── integrations/ # 50+ integration registry -│ ├── registry.rs # All integrations across 9 categories -│ └── mod.rs -├── memory/ # Memory trait + hybrid search engine -│ ├── traits.rs # Memory trait definition -│ ├── sqlite.rs # SQLite + FTS5 + vector embeddings -│ ├── markdown.rs # Append-only markdown -│ ├── embeddings.rs # EmbeddingProvider trait + OpenAI + Noop -│ ├── vector.rs # Cosine similarity + serialization + hybrid merge -│ ├── chunker.rs # Markdown-aware document splitting -│ └── mod.rs # Factory -├── observability/ # Observer trait + 3 backends -│ ├── traits.rs -│ ├── noop.rs -│ ├── log.rs -│ └── multi.rs -├── onboard/ # Interactive setup wizard -│ └── wizard.rs -├── providers/ # Provider trait + 22+ providers -│ ├── traits.rs # Provider trait definition -│ ├── openrouter.rs # OpenRouter (default) -│ ├── anthropic.rs # Anthropic direct -│ ├── openai.rs # OpenAI direct -│ ├── ollama.rs # Local Ollama -│ ├── compatible.rs # OpenAI-compatible adapter (18+ providers) -│ └── mod.rs # Factory -├── runtime/ # RuntimeAdapter trait + Native -│ ├── traits.rs -│ └── native.rs -├── security/ # Security policy + gateway pairing + secrets -│ ├── policy.rs # SecurityPolicy, path validation, rate limiting -│ ├── pairing.rs # PairingGuard, OTP, bearer tokens -│ ├── secrets.rs # Encrypted secret store (XOR + local key file) -│ └── mod.rs -├── skills/ # Skill loader (TOML manifests) -│ └── mod.rs -├── tools/ # Tool trait + 7 tools -│ ├── traits.rs # Tool trait definition -│ ├── shell.rs # Shell command execution -│ ├── file_read.rs # Sandboxed file reading -│ ├── file_write.rs # Sandboxed file writing -│ ├── memory_store.rs # Store to memory -│ ├── memory_recall.rs # Search memory -│ ├── memory_forget.rs # Delete from memory -│ ├── composio.rs # Composio OAuth tools (optional) -│ └── mod.rs # Registry -└── tunnel/ # Tunnel trait + 5 implementations - ├── none.rs # Local-only (default) - ├── cloudflare.rs # Cloudflare Zero Trust - ├── tailscale.rs # Tailscale serve/funnel - ├── ngrok.rs # ngrok - ├── custom.rs # Bring your own - └── mod.rs # Factory - -examples/ -├── custom_provider.rs -├── custom_channel.rs -├── custom_tool.rs -└── custom_memory.rs - -tests/ -└── memory_comparison.rs # SQLite vs Markdown benchmark -``` - -**64 source files · 17,800+ lines of Rust · 1,017 tests · 0 clippy warnings** - ## License MIT — see [LICENSE](LICENSE)