# Security

ZeroClaw implements a multi-layered security stack designed to provide defense-in-depth for autonomous agent operations. This system ensures that agents operate within defined boundaries, protect sensitive credentials, and provide a verifiable audit trail of all actions.

***

## SecurityPolicy

The `SecurityPolicy` is the central enforcement mechanism for all tool and command executions. It defines the agent's level of independence and the specific constraints on its operating environment.

### Autonomy Levels

Autonomy is categorized into three distinct levels, controlling the baseline behavior of the agent:

```rust
pub enum AutonomyLevel {
    /// Read-only: can observe but not act
    ReadOnly,
    /// Supervised: acts but requires approval for risky operations
    Supervised,
    /// Full: autonomous execution within policy bounds
    Full,
}
```

### Risk Classification

Commands and operations are classified by their potential impact:

```rust
pub enum CommandRiskLevel {
    Low,
    Medium,
    High,
}

pub enum ToolOperation {
    Read,
    Act,
}
```

***

## Action Tracker

ZeroClaw uses a sliding-window rate limiter to prevent automated abuse or runaway processes. It maintains a 1-hour window of all side-effecting actions.

```rust
pub struct ActionTracker {
    /// Timestamps of recent actions (kept within the last hour).
    actions: Mutex<Vec<Instant>>,
}

impl ActionTracker {
    pub fn record(&self) -> usize {
        let mut actions = self.actions.lock();
        let cutoff = Instant::now()
            .checked_sub(std::time::Duration::from_secs(3600))
            .unwrap_or_else(Instant::now);
        actions.retain(|t| *t > cutoff);
        actions.push(Instant::now());
        actions.len()
    }
}
```

***

## Command Allowlist

ZeroClaw employs a deny-by-default strategy for shell execution. Only explicitly listed commands are permitted, and they are subjected to rigorous parsing to prevent bypasses.

### Default Allowed Commands
`git`, `npm`, `cargo`, `ls`, `cat`, `grep`, `find`, `echo`, `pwd`, `wc`, `head`, `tail`, `date`.

### Default Forbidden Paths
The system blocks access to 14 system directories (e.g., `/etc`, `/root`, `/usr`, `/bin`, `/proc`) and 4 sensitive dotfile locations (`~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.config`) even if workspace confinement is disabled.

### Shell Parsing Logic
To prevent command injection via chained operators or environment variables, ZeroClaw uses a quote-aware shell segment splitter and environment assignment stripper:

```rust
fn skip_env_assignments(s: &str) -> &str {
    // Strips 'FOO=bar' from 'FOO=bar cmd args'
}

fn split_unquoted_segments(command: &str) -> Vec<String> {
    // Splits on ';', '|', '&&', '||', and newlines
    // Respects quotes to allow literal separators in arguments
}
```

***

## Path Validation

The `is_path_allowed()` function implements multiple layers of protection to enforce workspace confinement and prevent directory traversal.

### Validation Logic

```rust
pub fn is_path_allowed(&self, path: &str) -> bool {
    // 1. Null-byte injection guard
    if path.contains('\0') { return false; }

    // 2. Directory traversal detection
    if Path::new(path).components().any(|c| matches!(c, Component::ParentDir)) {
        return false;
    }

    // 3. URL-encoding detection (..%2f)
    let lower = path.to_lowercase();
    if lower.contains("..%2f") || lower.contains("%2f..") {
        return false;
    }

    // 4. Tilde expansion guard (blocks ~user forms)
    if path.starts_with('~') && path != "~" && !path.starts_with("~/") {
        return false;
    }

    // 5. Absolute path block and forbidden prefix match
    let expanded = expand_user_path(path);
    if self.workspace_only && expanded.is_absolute() { return false; }
    // ... (forbidden path checks)
}
```

***

## Sandboxing

ZeroClaw supports multiple isolation backends via a unified `Sandbox` trait, allowing for varied levels of process and filesystem isolation.

- **Landlock**: Linux-native LSM for fine-grained filesystem restriction.
- **Bubblewrap**: Unprivileged sandboxing utility (used by Flatpak).
- **Docker**: Containerized isolation for high-risk environments.
- **Firejail**: SUID-based sandbox for easy desktop application isolation.

### Landlock Implementation snippet:

```rust
fn apply_restrictions(&self) -> std::io::Result<()> {
    let mut ruleset = Ruleset::default()
        .handle_access(AccessFs::ReadFile | AccessFs::WriteFile | AccessFs::ReadDir | ...)
        .and_then(|ruleset| ruleset.create())?;

    // Grant access only to workspace and necessary system paths (/usr, /bin)
    if let Some(ref workspace) = self.workspace_dir {
        ruleset = ruleset.add_rule(PathBeneath::new(workspace_fd, ...))?;
    }
    ruleset.restrict_self()
}
```

***

## Secret Management

The `SecretStore` protects API keys and credentials using authenticated encryption (ChaCha20-Poly1305).

```rust
pub struct SecretStore {
    key_path: PathBuf, // ~/.zeroclaw/.secret_key (mode 0600)
    enabled: bool,
}
```

Encryption ensures that secrets are never stored in plaintext in configuration files, preventing accidental exposure via `grep`, `git log`, or file sharing.

***

## Audit Logging

Every security-relevant event is recorded in a structured JSONL format. This provides a forensic trail of what was executed, by whom, and whether it was permitted by policy.

```rust
pub struct AuditEvent {
    pub timestamp: DateTime<Utc>,
    pub event_type: AuditEventType,
    pub actor: Option<Actor>,
    pub action: Option<Action>,
    pub result: Option<ExecutionResult>,
    pub security: SecurityContext,
}
```

***

## Emergency Stop (E-Stop)

The `EstopManager` provides a "big red button" capability to immediately halt or restrict agent activity.

- **Levels**: `KillAll`, `NetworkKill`, `DomainBlock`, `ToolFreeze`.
- **Fail-Closed**: If the state file is corrupt or unreadable, the system defaults to `KillAll`.
- **OTP Requirement**: Resuming operations after an E-Stop engagement can be configured to require a One-Time Password (TOTP) to ensure human authorization.

***

## Relevance to Luna

Luna currently lacks a security framework. Adopting ZeroClaw's security stack is critical before enabling tool execution in non-trusted environments.

### Prioritized Adoption Order

1. **Filesystem Guards + Workspace Scoping**: Implement `is_path_allowed()` to prevent Luna from escaping its designated project directory.
2. **Command Allowlist**: Restrict shell tools to a known-safe subset with defined autonomy levels.
3. **Path Validation**: Integrate component-aware path checking in all file-handling tools.
4. **Secret Store**: Migrate Luna's configuration to use ChaCha20-Poly1305 for API keys.
5. **Audit Logging**: Implement structured event logging for all tool invocations.
6. **Sandboxing**: Introduce Landlock or Docker backends for executing untrusted code.

See also: [[Core]], [[Skills]], [[Configuration]].