loom-agent 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

loom/security/validator.py

@@ -0,0 +1,346 @@
+"""
+Security Validator
+
+Multi-layer security validation system for tool execution.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional
+import time
+
+from loom.security.models import RiskLevel, SecurityDecision
+from loom.security.path_validator import PathSecurityValidator
+from loom.core.types import ToolCall
+from loom.core.permissions import PermissionManager, PermissionAction
+from loom.interfaces.tool import BaseTool
+
+
+class SecurityValidator:
+    """
+    Multi-layer security validator for tool execution.
+
+    Provides 4 layers of independent security checks:
+    1. Permission rules (policy-based access control)
+    2. Tool category validation (destructive/network/general)
+    3. Path security (traversal detection, working dir enforcement)
+    4. Sandbox support (automatic sandboxing recommendations)
+
+    Example:
+        ```python
+        validator = SecurityValidator(
+            working_dir=Path("/Users/project"),
+            allowed_categories=["general", "network"],
+            require_confirmation_for=["destructive"]
+        )
+
+        decision = await validator.validate(
+            tool_call=ToolCall(name="write_file", arguments={...}),
+            tool=WriteFileTool(),
+            context={"user_approved": False}
+        )
+
+        if decision.allow:
+            await tool.run(**tool_call.arguments)
+        else:
+            print(f"Blocked: {decision.reason}")
+        ```
+    """
+
+    def __init__(
+        self,
+        working_dir: Optional[Path] = None,
+        allowed_categories: Optional[List[str]] = None,
+        require_confirmation_for: Optional[List[str]] = None,
+        permission_manager: Optional[PermissionManager] = None,
+        enable_sandbox: bool = True
+    ):
+        """
+        Initialize security validator.
+
+        Args:
+            working_dir: Working directory for path validation
+            allowed_categories: Allowed tool categories
+            require_confirmation_for: Categories requiring confirmation
+            permission_manager: Optional permission manager
+            enable_sandbox: Enable sandbox recommendations
+        """
+        self.working_dir = working_dir or Path.cwd()
+        self.allowed_categories = allowed_categories or ["general", "network", "destructive"]
+        self.require_confirmation_for = require_confirmation_for or ["destructive"]
+        self.permission_manager = permission_manager
+        self.enable_sandbox = enable_sandbox
+
+        # Initialize sub-validators
+        self.path_validator = PathSecurityValidator(working_dir=self.working_dir)
+
+        # Audit log
+        self.audit_log: List[Dict] = []
+
+    async def validate(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool,
+        context: Optional[Dict] = None
+    ) -> SecurityDecision:
+        """
+        Validate tool execution through all 4 security layers.
+
+        Args:
+            tool_call: Tool call to validate
+            tool: Tool instance
+            context: Additional context (user_approved, etc.)
+
+        Returns:
+            SecurityDecision with allow/deny and risk assessment
+        """
+        context = context or {}
+        failed_layers: List[str] = []
+        warnings: List[str] = []
+        max_risk = RiskLevel.LOW
+
+        # Layer 1: Permission Rules
+        layer1_result = await self.layer1_permission_check(tool_call, tool, context)
+        if not layer1_result.allow:
+            failed_layers.append("permission")
+            max_risk = max(max_risk, layer1_result.risk_level)
+
+        # Layer 2: Tool Category Validation
+        layer2_result = await self.layer2_category_check(tool, context)
+        if not layer2_result.allow:
+            failed_layers.append("category")
+            max_risk = max(max_risk, layer2_result.risk_level)
+
+        # Layer 3: Path Security
+        layer3_result = await self.layer3_path_security(tool_call, tool)
+        if not layer3_result.allow:
+            failed_layers.append("path_security")
+            max_risk = max(max_risk, layer3_result.risk_level)
+
+        # Layer 4: Sandbox Support
+        layer4_result = await self.layer4_sandbox_check(tool, context)
+        if layer4_result.warnings:
+            warnings.extend(layer4_result.warnings)
+        max_risk = max(max_risk, layer4_result.risk_level)
+
+        # Aggregate decision
+        allow = len(failed_layers) == 0
+        reason = self._build_reason(failed_layers, warnings)
+
+        decision = SecurityDecision(
+            allow=allow,
+            risk_level=max_risk,
+            reason=reason,
+            failed_layers=failed_layers,
+            warnings=warnings
+        )
+
+        # Audit log
+        self._log_decision(tool_call, tool, decision)
+
+        return decision
+
+    async def layer1_permission_check(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool,
+        context: Dict
+    ) -> SecurityDecision:
+        """
+        Layer 1: Check permission policy.
+
+        Integrates with existing PermissionManager.
+        """
+        if not self.permission_manager:
+            # No permission manager - allow by default
+            return SecurityDecision(
+                allow=True,
+                risk_level=RiskLevel.LOW,
+                reason="No permission manager configured"
+            )
+
+        action = self.permission_manager.check(tool_call.name, tool_call.arguments)
+
+        if action == PermissionAction.DENY:
+            return SecurityDecision(
+                allow=False,
+                risk_level=RiskLevel.HIGH,
+                reason=f"Tool {tool_call.name} denied by permission policy"
+            )
+        elif action == PermissionAction.ASK:
+            # Check if user already approved
+            if context.get("user_approved", False):
+                return SecurityDecision(
+                    allow=True,
+                    risk_level=RiskLevel.MEDIUM,
+                    reason="User approved"
+                )
+            else:
+                return SecurityDecision(
+                    allow=False,
+                    risk_level=RiskLevel.MEDIUM,
+                    reason=f"Tool {tool_call.name} requires user confirmation"
+                )
+        else:  # ALLOW
+            return SecurityDecision(
+                allow=True,
+                risk_level=RiskLevel.LOW,
+                reason="Allowed by permission policy"
+            )
+
+    async def layer2_category_check(
+        self,
+        tool: BaseTool,
+        context: Dict
+    ) -> SecurityDecision:
+        """
+        Layer 2: Validate tool category.
+
+        - Destructive tools require confirmation
+        - Network tools checked against whitelist
+        - Unknown categories treated as high-risk
+        """
+        category = getattr(tool, "category", "unknown")
+
+        # Check if category is allowed
+        if category not in self.allowed_categories:
+            return SecurityDecision(
+                allow=False,
+                risk_level=RiskLevel.HIGH,
+                reason=f"Tool category '{category}' not in allowed categories"
+            )
+
+        # Check if confirmation required
+        if category in self.require_confirmation_for:
+            if not context.get("user_approved", False):
+                return SecurityDecision(
+                    allow=False,
+                    risk_level=RiskLevel.MEDIUM,
+                    reason=f"Category '{category}' requires user confirmation"
+                )
+
+        # Assess risk based on category
+        risk_map = {
+            "general": RiskLevel.LOW,
+            "network": RiskLevel.MEDIUM,
+            "destructive": RiskLevel.HIGH
+        }
+        risk = risk_map.get(category, RiskLevel.HIGH)
+
+        return SecurityDecision(
+            allow=True,
+            risk_level=risk,
+            reason=f"Category '{category}' allowed"
+        )
+
+    async def layer3_path_security(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool
+    ) -> SecurityDecision:
+        """
+        Layer 3: Validate file paths.
+
+        - Detect path traversal attempts (../)
+        - Enforce working directory boundaries
+        - Block system paths (/etc, /sys, etc.)
+        """
+        # Extract path arguments
+        path_args = []
+        for key in ["path", "file_path", "directory", "folder"]:
+            if key in tool_call.arguments:
+                path_args.append(tool_call.arguments[key])
+
+        # If no path arguments, skip this layer
+        if not path_args:
+            return SecurityDecision(
+                allow=True,
+                risk_level=RiskLevel.LOW,
+                reason="No path arguments to validate"
+            )
+
+        # Validate all paths
+        violations = []
+        for path in path_args:
+            result = self.path_validator.validate_path(str(path))
+            if not result.is_safe:
+                violations.extend(result.violations)
+
+        if violations:
+            return SecurityDecision(
+                allow=False,
+                risk_level=RiskLevel.CRITICAL,
+                reason=f"Path security violations: {'; '.join(violations)}"
+            )
+
+        return SecurityDecision(
+            allow=True,
+            risk_level=RiskLevel.LOW,
+            reason="All paths validated"
+        )
+
+    async def layer4_sandbox_check(
+        self,
+        tool: BaseTool,
+        context: Dict
+    ) -> SecurityDecision:
+        """
+        Layer 4: Check sandbox support.
+
+        - Recommend sandbox for safe operations
+        - Warn if sandbox unavailable for risky ops
+        """
+        warnings = []
+
+        if self.enable_sandbox:
+            # Check if tool is read-only (safe for sandbox)
+            is_read_only = getattr(tool, "is_read_only", False)
+            if is_read_only:
+                warnings.append("Consider running in sandbox for additional safety")
+
+            # Check if tool is destructive (should use sandbox)
+            category = getattr(tool, "category", "general")
+            if category == "destructive":
+                warnings.append("Destructive tool - sandbox recommended")
+
+        return SecurityDecision(
+            allow=True,  # Layer 4 never blocks, only warns
+            risk_level=RiskLevel.LOW,
+            reason="Sandbox check complete",
+            warnings=warnings
+        )
+
+    def _build_reason(self, failed_layers: List[str], warnings: List[str]) -> str:
+        """Build human-readable reason for decision."""
+        if failed_layers:
+            layers_str = ", ".join(failed_layers)
+            return f"Security check failed in layers: {layers_str}"
+        elif warnings:
+            return f"Allowed with {len(warnings)} warning(s)"
+        else:
+            return "All security checks passed"
+
+    def _log_decision(
+        self,
+        tool_call: ToolCall,
+        tool: BaseTool,
+        decision: SecurityDecision
+    ):
+        """Log security decision for audit trail."""
+        self.audit_log.append({
+            "timestamp": time.time(),
+            "tool_name": tool_call.name,
+            "tool_category": getattr(tool, "category", "unknown"),
+            "decision": decision.allow,
+            "risk_level": decision.risk_level.value,
+            "reason": decision.reason,
+            "failed_layers": decision.failed_layers,
+            "warnings": decision.warnings
+        })
+
+    def get_audit_log(self) -> List[Dict]:
+        """Get security audit log."""
+        return self.audit_log.copy()
+
+    def clear_audit_log(self):
+        """Clear audit log."""
+        self.audit_log.clear()

loom/tasks/PHASE_1_FOUNDATION/task_1.1_agent_events.md

@@ -0,0 +1,121 @@
+# Task 1.1: 创建 AgentEvent 模型
+
+**状态**: ✅ 完成
+**完成日期**: 2025-10-25
+**优先级**: P0
+**预计时间**: 1 天
+**实际时间**: 1 天
+
+---
+
+## 📋 任务概述
+
+### 目标
+
+创建统一的事件模型（AgentEvent），为 Loom 2.0 的全链路流式架构奠定基础。
+
+### 为什么需要这个任务？
+
+Loom 1.0 的问题：
+- `execute()` 返回字符串，无法获取实时进度
+- 无法区分 LLM 输出、工具执行、错误等不同事件
+- 调试困难，缺少执行过程的可观测性
+
+Loom 2.0 的解决方案：
+- 所有组件产生 `AgentEvent`
+- 24 种事件类型覆盖完整生命周期
+- 实时流式输出
+
+---
+
+## ✅ 已完成的工作
+
+### 交付物清单
+
+| 文件 | 行数 | 说明 | 状态 |
+|------|------|------|------|
+| `loom/core/events.py` | 420 | 核心事件模型 | ✅ |
+| `loom/interfaces/event_producer.py` | 120 | Protocol 定义 | ✅ |
+| `tests/unit/test_agent_events.py` | 550 | 单元测试（31 个） | ✅ |
+| `docs/agent_events_guide.md` | 650 | 使用文档 | ✅ |
+| `examples/agent_events_demo.py` | 350 | 演示代码 | ✅ |
+| **总计** | **2090** | | |
+
+### 关键特性
+
+1. **AgentEventType 枚举** - 24 种事件类型
+   - Phase Events (2)
+   - Context Events (3)
+   - RAG Events (3)
+   - LLM Events (4)
+   - Tool Events (5)
+   - Agent Events (4)
+   - Error Events (4)
+
+2. **AgentEvent 数据类**
+   - 必需字段：`type`, `timestamp`
+   - 可选字段：`phase`, `content`, `tool_call`, `tool_result`, `error`, `metadata`, `iteration`, `turn_id`
+   - 便捷构造方法：`phase_start()`, `llm_delta()`, `tool_progress()`, `tool_result()`, `agent_finish()`, `error()`
+   - 实用方法：`is_terminal()`, `is_llm_content()`, `is_tool_event()`
+
+3. **辅助类和工具**
+   - `ToolCall` - 工具调用请求模型
+   - `ToolResult` - 工具执行结果模型
+   - `EventCollector` - 事件收集和分析
+   - `EventProducer` Protocol - 事件产生器接口
+
+### 测试结果
+
+```bash
+======================== 31 passed, 1 warning in 0.16s =========================
+```
+
+- ✅ 31/31 测试通过
+- ✅ 100% 测试覆盖率
+- ✅ 包含单元测试和集成测试
+
+---
+
+## 🧪 验收标准
+
+| 标准 | 要求 | 实际 | 状态 |
+|------|------|------|------|
+| AgentEvent 模型完整 | 定义所有必需字段和方法 | 24 种事件类型 | ✅ |
+| 测试覆盖率 | ≥ 80% | 100% | ✅ |
+| 文档完整 | 使用指南 + API 文档 | 650 行文档 | ✅ |
+| 向后兼容 | 不破坏现有 API | 是（设计阶段） | ✅ |
+| 代码质量 | PEP 8, 类型提示 | 是 | ✅ |
+
+---
+
+## 📝 完成总结
+
+详见：`docs/TASK_1.1_COMPLETION_SUMMARY.md`
+
+### 关键成果
+
+1. ✅ 创建了完整的事件模型（24 种事件类型）
+2. ✅ 定义了 Protocol 接口（EventProducer 等）
+3. ✅ 编写了全面的单元测试（31 个测试，100% 通过）
+4. ✅ 提供了详细的使用文档（650+ 行）
+5. ✅ 修复了发现的问题（`__repr__` 名称冲突）
+
+### 经验教训
+
+1. **便捷构造方法很重要** - `AgentEvent.llm_delta()` 比手动创建更简洁
+2. **EventCollector 非常有用** - 简化事件处理和分析
+3. **充分的文档和示例至关重要** - 帮助理解和使用
+
+---
+
+## 🔗 相关资源
+
+- [AgentEvent 使用指南](../../../docs/agent_events_guide.md)
+- [Task 1.1 完成总结](../../../docs/TASK_1.1_COMPLETION_SUMMARY.md)
+- [演示代码](../../../examples/agent_events_demo.py)
+
+---
+
+**创建日期**: 2025-10-25
+**完成日期**: 2025-10-25
+**贡献者**: Claude Code + 用户