Security overview

​

Trust model

​

Security boundaries

​

1. Container isolation (Primary boundary)

• Process isolation - Container processes cannot affect the host
• Filesystem isolation - Only explicitly mounted directories are visible
• Non-root execution - Runs as unprivileged node user (uid 1000)
• Ephemeral containers - Fresh environment per invocation (--rm)

​

2. Mount security

​

External allowlist

• Outside project root
• Never mounted into containers
• Cannot be modified by agents

[
  ".ssh", ".gnupg", ".gpg", ".aws", ".azure", ".gcloud", ".kube", ".docker",
  "credentials", ".env", ".netrc", ".npmrc", ".pypirc", "id_rsa", "id_ed25519",
  "private_key", ".secret"
]

​

Protections

• Symlink resolution before validation (prevents traversal attacks)
• Container path validation (rejects .. and absolute paths)
• nonMainReadOnly option forces read-only for non-main groups

{
  "allowedRoots": [
    {
      "path": "~/projects",
      "allowReadWrite": true,
      "description": "Development projects"
    }
  ],
  "blockedPatterns": ["password", "secret", "token"],
  "nonMainReadOnly": true
}

​

Read-only project root

// Main group mounts (simplified)
mounts = [
  { host: '/path/to/nanoclaw', container: '/workspace/project', readonly: true },
  { host: '/path/to/nanoclaw/groups/main', container: '/workspace/group', readonly: false },
  { host: '/path/to/nanoclaw/data/sessions/main/.claude', container: '/home/node/.claude', readonly: false },
  { host: '/path/to/nanoclaw/data/ipc/main', container: '/workspace/ipc', readonly: false }
]

​

3. Session isolation

• Groups cannot see other groups’ conversation history
• Session data includes full message history and file contents read
• Prevents cross-group information disclosure

​

4. IPC authorization

// Authorization: verify this group can send to this chatJid
const targetGroup = registeredGroups[data.chatJid];
if (
  isMain ||
  (targetGroup && targetGroup.folder === sourceGroup)
) {
  await deps.sendMessage(data.chatJid, data.text);
} else {
  logger.warn(
    { chatJid: data.chatJid, sourceGroup },
    'Unauthorized IPC message attempt blocked',
  );
}

​

5. Sender allowlist

{
  "default": {
    "allow": "*",
    "mode": "trigger"
  },
  "chats": {
    "120363001234567890@g.us": {
      "allow": ["5511999887766@s.whatsapp.net", "5511888776655@s.whatsapp.net"],
      "mode": "trigger"
    },
    "120363009876543210@g.us": {
      "allow": ["5511999887766@s.whatsapp.net"],
      "mode": "drop"
    }
  },
  "logDenied": true
}

• allow: "*" permits all senders (the default when no file exists)
• allow: ["sender1", "sender2"] restricts to specific sender IDs
• Per-chat entries in chats override the default entry
• logDenied (default true) logs denied attempts at debug level
• The file is reloaded on every message cycle — no restart needed
• If the file is missing or contains invalid JSON, all senders are allowed

​

6. Credential handling

// Container has a placeholder token — real credentials injected by proxy
ANTHROPIC_BASE_URL=http://host.docker.internal:3001  // → proxy
CLAUDE_CODE_OAUTH_TOKEN=placeholder                   // → replaced by proxy

​

NOT mounted

• Channel sessions (e.g., store/auth/ for WhatsApp) - host only
• Mount allowlist - external, never mounted
• Any credentials matching blocked patterns

​

7. Diagnostics and telemetry

1. After setup or update completes, the skill writes a JSON payload to a temporary file
2. The full payload is shown to you before anything is sent
3. You choose: Yes (send once), No (skip), or Never ask again (permanently disable)
4. If sent, the payload goes to PostHog’s capture API via a single curl request, then the temp file is deleted

​

8. Log privacy

• Secrets are stripped from the input object before logging
• User prompts are redacted from error logs — only prompt length and session ID are recorded
• Agent output is logged by length, not content
• Full input/output is only included when verbose logging (LOG_LEVEL=debug) is explicitly enabled

​

Privilege comparison

​

Why main group is different

1. Only you can send messages to it
2. It acts as the administrative interface
3. It needs access to manage other groups and the system itself
4. Prompt injection from self is not a threat model

​

Why non-main groups are restricted

1. Other users may attempt prompt injection
2. Malicious users could try to escalate privileges
3. Groups should only affect their own context, not others
4. Defense in depth: even if prompt injection succeeds, damage is limited

​

Security architecture diagram

┌──────────────────────────────────────────────────────────────────┐
│                        UNTRUSTED ZONE                             │
│  Incoming Messages (potentially malicious)                         │
└────────────────────────────────┬─────────────────────────────────┘
                                 │
                                 ▼ Trigger check, input escaping
┌──────────────────────────────────────────────────────────────────┐
│                     HOST PROCESS (TRUSTED)                        │
│  • Message routing                                                │
│  • IPC authorization                                              │
│  • Mount validation (external allowlist)                          │
│  • Container lifecycle                                            │
│  • Secret injection (OneCLI or credential proxy)                    │
└────────────────────────────────┬─────────────────────────────────┘
                                 │
                                 ▼ Explicit mounts only
┌──────────────────────────────────────────────────────────────────┐
│                CONTAINER (ISOLATED/SANDBOXED)                     │
│  • Agent execution                                                │
│  • Bash commands (sandboxed)                                      │
│  • File operations (limited to mounts)                            │
│  • Network access (unrestricted)                                  │
│  • Cannot modify security config                                  │
└──────────────────────────────────────────────────────────────────┘

​

Attack scenarios

​

Prompt injection in non-main group

• Agent only has access to its own group’s session
• Cannot send messages to other groups (IPC authorization)
• Cannot access channel credentials (not mounted)
• Cannot modify mount allowlist (external, never mounted)

​

Container escape attempt

• Container runtime (Docker) provides kernel-level isolation
• Non-root execution limits attack surface
• Ephemeral containers (--rm) ensure no persistence
• Host filesystem only accessible via explicit mounts

​

Symlink traversal

• Symlinks resolved to real path before validation
• Blocked patterns checked against resolved path
• Mount request rejected before container spawns

​

IPC privilege escalation

• IPC watcher validates group identity matches operation target
• Operations for other groups silently ignored
• Each group has isolated IPC namespace

​

Best practices

1. Keep main group private: Never share your main group credentials
2. Review mount allowlist: Before allowing new mounts, verify they don’t contain secrets
3. Use read-only for shared data: Set nonMainReadOnly: true for mounts shared with non-main groups
4. Audit group permissions: Periodically review registered groups and their containerConfig
5. Monitor logs: Check groups/{name}/logs/ for suspicious activity
6. Update regularly: Security fixes may be released in upstream NanoClaw updates

​

Related topics

• Group isolation and per-group contexts
• Container isolation details
• System architecture