This document outlines the security posture, threat model, and safe usage expectations for claw-cli-agent. This project prioritizes a "security-first" approach to autonomous agent execution.

The primary threat this agent is designed to mitigate is unintended action execution resulting from a compromised or "hallucinating" Large Language Model (LLM).

• Adversary: The LLM planner is treated as an untrusted source of commands. While a powerful tool, it can be manipulated via prompt injection or may generate unsafe instructions.
• Goal: The agent's security goal is to prevent the LLM from executing arbitrary commands, reading sensitive data, or causing any unintended system modification.
• Attack Vectors: The model assumes attack vectors originate from the LLM's output, such as a plan containing:
  • Unauthorized shell commands (e.g., rm -rf /).
  • Attempts to read sensitive files (e.g., ~/.ssh/id_rsa).
  • Unauthorized network connections to malicious endpoints.

The cornerstone of this agent's security is its "fail-closed" philosophy.

• Explicit Allowance: No action is ever implicitly trusted. Only capabilities that are explicitly defined in the Policy module are candidates for execution.
• Strict Validation: Every proposed action and its arguments are rigorously validated against a predefined schema. Any deviation results in immediate rejection of the entire plan.
• Halt on Violation: A single policy violation halts the agent's execution loop, preventing it from proceeding with a potentially unsafe plan.

This is not a general-purpose shell agent. It is a task-specific executor that operates under a highly restrictive and auditable security policy.

To maintain a clear security boundary, claw-cli-agent is NOT designed for:

• Arbitrary Shell Execution: The agent is fundamentally incapable of executing raw shell commands.
• Self-Modification: The agent cannot alter its own security policies or source code.

For the ClawCloud managed service, additional layers of security are implemented:

• Rate Limiting: All API endpoints are protected by rate limiting to prevent abuse and denial-of-service attacks.
• Security Headers (Helmet): Standard security headers are enforced to mitigate common web vulnerabilities like XSS, clickjacking, and others.
• Input Sanitization & Validation: All user inputs to the ClawCloud API are rigorously sanitized and validated using strong schemas (zod).
• Authentication (JWT): User access to protected endpoints is secured using JSON Web Tokens.
• Multi-Tenancy Isolation: Agent execution for each user is designed to be isolated, preventing cross-tenant data access or interference. (Detailed implementation in server/).
• Data Encryption: Sensitive data at rest (e.g., user database) and in transit (HTTPS) is encrypted.
• Auditable Logging: Comprehensive logs are maintained for all server actions, agent executions, and security events.

The security model of claw-cli-agent relies on the following assumptions:

• Trusted User (Local CLI): The user operating the local CLI is trusted.
• Secure Host: The machine running the agent is not already compromised.
• Policy Review: The user is expected to understand the capabilities defined in the policy files. This is the definitive source of truth for what the agent can and cannot do.
• ClawCloud Users: ClawCloud users are authenticated and operate within their defined quotas and access policies.

If you discover a security vulnerability, please report it responsibly by opening a security advisory on the GitHub repository.