<!-- source: https://deepwiki.com/qhkm/zeptoclaw/6.1-security-architecture -->

# Security Architecture

- AGENTS.md
- CLAUDE.md
- src/audit.rs
- src/cli/secrets.rs
- src/kernel/gate.rs
- src/safety/chain_alert.rs
- src/safety/mod.rs
- src/security/encryption.rs
- src/security/mod.rs
- src/security/mount.rs
- src/security/path.rs
- src/security/shell.rs

## Purpose and Scope

This page provides an architectural overview of ZeptoClaw's defense-in-depth security model, including the six security layers, their integration points, and the threat model they address. ZeptoClaw treats security as a multi-stage pipeline where both LLM-generated tool calls and external client requests (via MCP) are subjected to the same rigorous validation.

The core of the security system is the `execute_tool` function in `src/kernel/gate.rs`, which serves as the mandatory bottleneck for all tool activity, ensuring that safety scanning, taint checks, and audit logging are applied consistently across the `AgentLoop`, `McpServer`, and embedded `ZeptoAgent` contexts.

**Sources:** [src/security/mod.rs1-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mod.rs#L1-L21) [src/kernel/gate.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L1-L11) [src/kernel/gate.rs131-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L139)

## Threat Model

ZeptoClaw's security architecture defends against the following threat classes:

**Sources:** [src/safety/mod.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L1-L11) [src/safety/chain_alert.rs12-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L12-L25) [src/security/shell.rs107-158](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L107-L158)

## Defense-in-Depth Overview

ZeptoClaw implements six security layers that execute sequentially. Tool execution is gated by `execute_tool`, which applies safety and taint checks regardless of whether the call originated from the `AgentLoop` or an external `McpServer` [src/kernel/gate.rs131-139](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L139)

### Security Orchestration Flow

```

```

**Sources:** [src/kernel/gate.rs131-182](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L182) [src/safety/mod.rs117-134](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L117-L134) [src/safety/chain_alert.rs55-58](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L55-L58)

## Layer 1: Input Validation & Policy Engine

The `SafetyLayer` orchestrates the `ContentValidator`, `LeakDetector`, and `PolicyEngine` to scan tool inputs [src/safety/mod.rs95-104](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L95-L104)

### Field-Aware Scanning

For sensitive tools like `write_file` or `edit_file`, the system performs field-aware scanning in `scan_tool_input`. Paths receive full policy checks, while file bodies suppress `shell_injection` rules to avoid false positives on legitimate code snippets [src/kernel/gate.rs75-117](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L75-L117)

### Policy Rules

The `PolicyEngine` enforces rules including system file access prevention, SQL injection detection, and shell injection prevention. It is complemented by the `ShellSecurityConfig` which manages `ShellAllowlistMode` [src/security/mod.rs21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mod.rs#L21-L21)

**Sources:** [src/kernel/gate.rs65-74](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L65-L74) [src/safety/mod.rs155-180](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L155-L180) [src/kernel/gate.rs23-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L23-L24)

## Layer 2: Taint Tracking (Data-Flow Awareness)

The `TaintEngine` implements data-flow tracking by labeling data provenance [src/safety/taint.rs1-8](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/taint.rs#L1-L8)

- Sources: Tools like web_fetch or web_search automatically label their output based on tool name and content during the output phase of execute_tool src/kernel/gate.rs 181-190
- Sinks: Sensitive tools (sinks) like shell or write_file block inputs containing tainted content via engine.check_sink src/kernel/gate.rs 157-168

**Sources:** [src/kernel/gate.rs157-168](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L157-L168) [src/safety/mod.rs43-45](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L43-L45) [src/kernel/gate.rs34-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L34-L41)

## Layer 3: Agent Mode & Category Permissions

Tools are governed by `AgentMode`, which defines `CategoryPermission` for various tool groups [src/security/mod.rs6-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mod.rs#L6-L13)

- Modes: Observer , Assistant , and Autonomous modes control the level of human intervention required src/security/agent_mode.rs 1-10 Fresh configs default to assistant mode with approvals enabled CLAUDE.md 3-4
- Permissions: ModePolicy maps tool categories to specific permission levels, determining if a tool call requires explicit user approval src/security/mod.rs 13

**Sources:** [src/security/mod.rs6-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mod.rs#L6-L13) [src/security/agent_mode.rs1-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/agent_mode.rs#L1-L20) [CLAUDE.md3-4](https://github.com/qhkm/zeptoclaw/blob/2c743d31/CLAUDE.md?plain=1#L3-L4)

## Layer 4: Output Sanitization & Leak Detection

Post-execution, the `LeakDetector` scans results for sensitive data patterns, including API keys and private keys [src/safety/mod.rs182-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L182-L183)

- Blocking: Critical leaks (e.g., detected PEM keys or cloud credentials) trigger an immediate SafetyResult with blocked: true src/safety/mod.rs 185-193
- Sanitization: The SanitizedOutput is passed back to the LLM only after passing these checks. Length checks also truncate excessive output (default 100KB) to prevent context flooding src/safety/mod.rs 53

**Sources:** [src/safety/mod.rs181-205](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L181-L205) [src/kernel/gate.rs180-190](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L180-L190) [src/safety/mod.rs156-166](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/mod.rs#L156-L166)

## Layer 5: Runtime Isolation

ZeptoClaw supports multiple backends to isolate tool execution, including Docker, Landlock, Firejail, and Bubblewrap [src/runtime/mod.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/runtime/mod.rs)

### Filesystem Security

The `SafePath` type and `validate_path_in_workspace` function ensure that filesystem tools cannot escape the defined workspace via symlinks or directory traversal. It includes `check_symlink_escape` to verify that components within the workspace do not point to sensitive host files [src/security/path.rs140-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L140-L183)

### Mount Validation

Additional runtime mounts are validated in `validate_extra_mounts` against an allowlist to prevent exposure of sensitive host paths like `.ssh`, `.aws`, or `/etc/shadow` [src/security/mount.rs165-215](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L165-L215) It also rejects Unix regular-file mounts with multiple hard links to prevent alias attacks [src/security/mount.rs84-103](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L84-L103)

**Sources:** [src/security/path.rs70-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L70-L130) [src/security/mount.rs12-27](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L12-L27) [src/security/path.rs17-31](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L17-L31)

## Layer 6: Loop Guards & Tool Chain Alerts

The `ChainTracker` monitors tool call sequences for dangerous patterns across a session [src/safety/chain_alert.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L1-L5)

### Dangerous Patterns

**Sources:** [src/safety/chain_alert.rs9-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L9-L25) [src/audit.rs31-32](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L31-L32)

## Secret Encryption at Rest

ZeptoClaw provides `SecretEncryption` using XChaCha20-Poly1305 AEAD with Argon2id key derivation for configuration secrets [src/security/encryption.rs1-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L1-L13)

### Key Management

- Master Key: Derived from a passphrase using Argon2id (m=64MB, t=3, p=1) or provided as raw bytes src/security/encryption.rs 173-183
- Envelopes: Secrets are stored as ENC[1:salt:nonce:ciphertext] src/security/encryption.rs 101-103
- CLI Commands: Managed via zeptoclaw secrets encrypt|decrypt|rotate src/cli/secrets.rs 14-20

**Sources:** [src/security/encryption.rs75-104](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L75-L104) [src/cli/secrets.rs135-173](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L135-L173)

## Audit Logging

All security-sensitive events are recorded via the `audit` module, which maintains a tamper-evident, in-memory `AuditHashChain` [src/audit.rs1-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L1-L12)

```

```

The `kernel::execute_tool` function records per-call audit entries, classifying them into `ShellExec`, `NetworkAccess`, or `AgentSpawn` based on the tool name [src/kernel/gate.rs34-41](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L34-L41)

**Sources:** [src/audit.rs104-142](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L104-L142) [src/audit.rs147-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/audit.rs#L147-L185) [src/kernel/gate.rs43-47](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L43-L47)

## Summary Table: Security Components

**Sources:** [src/security/mod.rs1-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mod.rs#L1-L21) [src/kernel/gate.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L1-L11) [src/security/shell.rs49-98](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L49-L98)
