<!-- source: https://deepwiki.com/qhkm/zeptoclaw/6.4-shell-security -->

# Shell Security

- 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

Shell Security encompasses ZeptoClaw's defense mechanisms against command injection, arbitrary code execution, and server-side request forgery (SSRF) attacks when executing shell commands or fetching web resources. This page covers shell escaping, command validation (allowlist/blocklist), path security, and secret encryption strategies.

For broader security architecture including agent mode policies and approval gates, see [Security Architecture](https://github.com/qhkm/zeptoclaw/blob/2c743d31/Security Architecture) For container-level isolation mechanisms, see [6.5 Container Isolation](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.5 Container Isolation)

## Shell Command Validation

ZeptoClaw validates shell commands through specialized logic in `src/security/shell.rs`. The validation occurs before any command execution in tools that spawn shell processes, such as the `shell` tool or LLM-generated custom commands.

### Shell Validation Data Flow

```

```

**Sources:** [src/kernel/gate.rs131-154](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/kernel/gate.rs#L131-L154) [src/security/shell.rs49-98](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L49-L98) [src/security/shell.rs107-158](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L107-L158) [src/security/shell.rs161-175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L161-L175)

### Blocklist Patterns

The blocklist prevents dangerous command patterns regardless of agent mode. It uses regex-based pattern matching to prevent bypass attacks. This is considered a defense-in-depth measure, as the primary security boundary is container isolation [src/security/shell.rs103-106](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L103-L106)

**Key Blocked Patterns:**

- Piped Execution: Detects curl | bash or wget | sh patterns src/security/shell.rs 109-111
- Reverse Shells: Blocks nc -e , /dev/tcp/ , and interactive bash redirects src/security/shell.rs 113-116
- Destructive Operations: Blocks rm -rf / and disk formatting commands like mkfs or dd to device nodes src/security/shell.rs 118-123
- Indirect Execution: Prevents bypasses via base64 --decode , python -c , perl -e , and eval . The Python pattern specifically accounts for intervening flags (e.g., python3 -P -c ) to mitigate GHSA-5wp8-q9mx-8jx8 src/security/shell.rs 131-144
- Sensitive Files: Literal blocks for /etc/shadow , /etc/passwd , ~/.ssh/ , and ZeptoClaw's own config files src/security/shell.rs 162-175
- Destructive Git: Blocks git push --force , git reset --hard , and git clean -f src/security/shell.rs 151-158

### Git Command Normalization

To prevent bypasses like `git -C /tmp push --force`, ZeptoClaw implements `normalize_git_command` [src/security/shell.rs49-52](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L49-L52) This function strips global options (like `-C`, `-c`, `--git-dir`, `--work-tree`) and global boolean flags (like `--bare`, `--no-pager`) so that the subcommand appears immediately after `git` for regex matching [src/security/shell.rs13-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L13-L39) [src/security/shell.rs63-93](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L63-L93)

**Sources:** [src/security/shell.rs13-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L13-L39) [src/security/shell.rs49-98](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L49-L98)

## Path and Mount Security

ZeptoClaw enforces strict path validation to prevent directory traversal and symlink-based workspace escapes.

### Workspace Validation

The `validate_path_in_workspace` function ensures that file operations remain within the designated workspace [src/security/path.rs70-71](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L70-L71)

1. Traversal Check: Rejects paths containing suspicious patterns like .. using contains_traversal_pattern src/security/path.rs 72-84
2. Symlink Escape Detection: The check_symlink_escape function iterates through every component of a path and uses symlink_metadata (lstat) to ensure no component resolves to a location outside the workspace src/security/path.rs 140-184

### Mount Allowlisting

When running in containerized modes, additional host mounts are validated against a `MountAllowlist` [src/security/mount.rs39-44](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L39-L44)

- Blocked Patterns: Mounts are rejected if they contain sensitive keywords defined in DEFAULT_BLOCKED_PATTERNS , such as .ssh , .aws , or id_rsa src/security/mount.rs 12-27 src/security/mount.rs 198-215
- Hardlink Protection: On Unix systems, validate_no_hardlink_alias prevents mounting files that have multiple hard links, mitigating certain alias-based bypasses src/security/mount.rs 84-103

**Sources:** [src/security/path.rs39-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L39-L130) [src/security/mount.rs165-215](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L165-L215)

## Secret Encryption at Rest

ZeptoClaw protects sensitive configuration values (API keys, tokens) using symmetric AEAD encryption via the `SecretEncryption` utility [src/security/encryption.rs1-4](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L1-L4)

### Encryption Format

Encrypted values use the format: `ENC[version:salt:nonce:ciphertext]` [src/security/encryption.rs7-13](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L7-L13)

- Algorithm: XChaCha20-Poly1305 src/security/encryption.rs 19
- KDF: Argon2id (m=64MB, t=3 iterations, p=1) src/security/encryption.rs 176-180

### Secret Management Flow

```

```

**Sources:** [src/security/encryption.rs44-104](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/encryption.rs#L44-L104) [src/cli/secrets.rs14-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L14-L19) [src/cli/secrets.rs135-173](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/secrets.rs#L135-L173)

## Tool Chain Monitoring

While blocklists prevent immediate danger, ZeptoClaw also monitors tool execution sequences for suspicious behavior through the `ChainTracker`.

### Dangerous Tool Chains

The system tracks tool names across a session and logs warnings for patterns that may indicate a multi-step attack [src/safety/chain_alert.rs1-5](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L1-L5):

- Write-then-Execute: filesystem_write followed by shell_execute (possible code injection) src/safety/chain_alert.rs 13-16
- Execute-then-Fetch: shell_execute followed by web_fetch (possible data exfiltration) src/safety/chain_alert.rs 17-20
- Memory-then-Execute: longterm_memory followed by shell_execute (possible memory poisoning) src/safety/chain_alert.rs 21-24

**Sources:** [src/safety/chain_alert.rs9-25](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L9-L25) [src/safety/chain_alert.rs61-83](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L61-L83)

## Summary of Security Components

Shell security is a mandatory layer that precedes [6.5 Container Isolation](https://github.com/qhkm/zeptoclaw/blob/2c743d31/6.5 Container Isolation) Even if a command is permitted by the shell security logic, it remains subject to the restrictions of the active runtime (e.g., Landlock or Bubblewrap).

**Sources:** [src/security/shell.rs1-175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/shell.rs#L1-L175) [src/security/path.rs1-184](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/path.rs#L1-L184) [src/security/mount.rs1-215](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/security/mount.rs#L1-L215) [src/safety/chain_alert.rs1-102](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/safety/chain_alert.rs#L1-L102)
