Security

Design Principle: Safe by default, powerful by opt-in. Follow the VS Code workspace trust model — confine operations locally, alert on escalation, and let users unlock capabilities when they understand the implications.

Philosophy

AcaClaw targets scientists who are not security experts. The security model must be:

1. Invisible when safe — Standard local usage should feel seamless
2. Loud when escalating — Any action that increases the attack surface must produce a visible alert
3. Opt-in, never opt-out — Dangerous capabilities are disabled by default
4. Layered, not binary — Security is a stack of independent controls that users can tune
5. Follow VS Code’s lead — The Workspace Trust model is well-understood and sufficient

Two Dimensions of Safety

Security Tiers

AcaClaw provides three tiers, progressing from most convenient to most isolated.

┌────────────────────────────────────────────────────────────────┐
│  Tier 3: Docker Sandbox (opt-in)                                │
│  Container isolation, network=none, dropped caps, seccomp      │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Tier 2: Remote Access (opt-in, alert required)          │  │
│  │  Gateway exposed beyond loopback, TLS required,          │  │
│  │  auth token mandatory                                    │  │
│  │  ┌──────────────────────────────────────────────────┐    │  │
│  │  │  Tier 1: Local Workspace (DEFAULT)               │    │  │
│  │  │  workspaceOnly, tool deny-list, backup,          │    │  │
│  │  │  credential scrubbing, audit log                 │    │  │
│  │  └──────────────────────────────────────────────────┘    │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

Summary by Tier

Tier 1 — Local Workspace (Default)

All operations are confined to the local workspace. No network exposure. No Docker required.

What is enforced

When Tier 1 is sufficient

• Writing papers, analyzing personal data, managing citations
• Student homework, coursework
• Literature search, reference management
• Any workflow where all data is trusted and the user is the sole operator

Tier 2 — Remote Access (Opt-In)

Remote access means exposing the gateway beyond 127.0.0.1. AcaClaw treats this as a significant security escalation.

Enabling remote access

1. Security alert displayed explaining implications
2. Explicit confirmation required
3. Event logged to audit trail
4. TLS enforced — plaintext HTTP blocked for non-loopback
5. Auth token required

Bind modes

Tier 3 — Docker Sandbox (Opt-In)

Container isolation for all tool execution — the strongest security posture.

When to use Tier 3

Docker security hardening

Protection Layers

How tool calls are processed

AI decides to call a tool
   │
   ▼
┌─ AcaClaw Policy Layer (before_tool_call) ────────┐
│  @acaclaw/backup: copy file before modification   │
│  @acaclaw/security: check command policy           │
│  @acaclaw/security: log to audit trail             │
│  @acaclaw/security: block if policy violation      │
└──────────────────────┬───────────────────────────┘
                       │ allowed
                       ▼
┌─ OpenClaw Tool Policy Layer ─────────────────────┐
│  workspaceOnly, tool allow/deny, exec policy      │
└──────────────────────┬───────────────────────────┘
                       │ allowed
                       ▼
┌─ OpenClaw Execution Layer ───────────────────────┐
│  Standard: host (workspace-only)                  │
│  Maximum:  Docker container                       │
└──────────────────────────────────────────────────┘

Credential scrubbing

12 patterns are stripped from LLM output:

• OpenAI keys (sk-*)
• GitHub PATs (ghp_*, gho_*)
• AWS access keys (AKIA*)
• JWTs (eyJ*.eyJ*.*)
• PEM private keys
• And 7 more patterns

Prompt injection detection

8 patterns are flagged (not blocked) with a warning:

• “ignore all previous instructions”
• “you are now a …”
• “override all instructions”
• And 5 more patterns

Flagged but not blocked to avoid false positives — a researcher discussing prompt injection in a security paper should not be constantly interrupted.

Network Policy

Academic domain allowlist

All outbound network requests from tools are checked against a curated list:

Users can add custom domains via config:

{
  "plugins": {
    "acaclaw-security": {
      "customAllowedDomains": [
        "my-university-api.edu"
      ]
    }
  }
}

Audit & Logging

What is logged

What is NOT logged

• Message content (user-agent conversation)
• File contents (only paths)
• Credential values (only match count)
• Personal information

Logs are stored at ~/.acaclaw/audit/YYYY-MM-DD.jsonl — outside the workspace, not exposed to AI tools. Default retention: 90 days.

Comparison with OpenClaw Upstream