claude-mpm 3.3.0__py3-none-any.whl → 3.4.0__py3-none-any.whl

claude_mpm/schemas/agent_schema_documentation.md

@@ -1,181 +0,0 @@
-# Agent Schema Documentation
-
-This document preserves the inline documentation from the agent_schema.json file. The JSON Schema itself must remain comment-free for proper parsing.
-
-## Schema Version 1.2.0
-
-### Required Fields
-
-- **schema_version**: Must match the schema version this agent was built for
-- **agent_id**: Unique identifier for the agent type
-- **agent_version**: Semantic version of this specific agent template
-- **agent_type**: Categorizes the agent's primary function
-- **metadata**: Human-readable information about the agent
-- **capabilities**: Technical specifications and resource requirements
-- **instructions**: System prompt that defines agent behavior
-
-### Field Descriptions
-
-#### schema_version
-- **Pattern**: `^\d+\.\d+\.\d+$` (Enforces semantic versioning format X.Y.Z)
-- **Description**: Schema version for the agent template format. This ensures compatibility between the agent template and the schema validator. Must be updated when breaking changes are made to the schema.
-- **Examples**: "1.0.0", "1.2.0"
-
-#### agent_id
-- **Pattern**: `^[a-z][a-z0-9_]*$` (Must start with lowercase letter, followed by lowercase letters, numbers, or underscores)
-- **Description**: Unique agent identifier used for agent discovery and loading. This ID must be unique across all agents in the system and follows snake_case naming convention.
-- **Examples**: "research_agent", "engineer_agent", "qa_agent", "security_agent"
-
-#### agent_version
-- **Pattern**: `^\d+\.\d+\.\d+$` (Enforces semantic versioning for agent templates)
-- **Description**: Semantic version of the agent template itself (not the schema). Increment major for breaking changes, minor for new features, patch for bug fixes.
-- **Examples**: "1.0.0", "2.1.3"
-
-#### agent_type
-- **Description**: Type of agent that determines its primary function and default capabilities. This categorization helps in agent discovery and capability matching.
-- **Enum values**:
-  - `base`: Generic agent with no specialization
-  - `engineer`: Code implementation and development
-  - `qa`: Quality assurance and testing
-  - `documentation`: Documentation creation and maintenance
-  - `research`: Code analysis and research
-  - `security`: Security analysis and vulnerability detection
-  - `ops`: Operations and infrastructure management
-  - `data_engineer`: Data pipeline and ETL development
-  - `version_control`: Git and version control operations
-
-### Metadata Object
-
-#### Required metadata fields:
-- **name**: Human-readable name for UI display
-- **description**: Brief explanation of agent's purpose
-- **tags**: Searchable tags for agent discovery
-
-#### Metadata field constraints:
-- **name**: 
-  - minLength: 3 (Minimum 3 characters for meaningful names)
-  - maxLength: 50 (Maximum 50 characters to prevent UI overflow)
-- **description**:
-  - minLength: 10 (Minimum 10 characters to ensure meaningful descriptions)
-  - maxLength: 200 (Maximum 200 characters for conciseness)
-- **tags**:
-  - Pattern: `^[a-z][a-z0-9-]*$` (Lowercase letters, numbers, and hyphens only)
-  - minItems: 1 (At least one tag required for discovery)
-  - maxItems: 10 (Maximum 10 tags to prevent over-tagging)
-  - uniqueItems: true (No duplicate tags allowed)
-
-### Capabilities Object
-
-#### Required capabilities fields:
-- **model**: Claude model version to use
-- **tools**: Array of allowed tools for the agent
-- **resource_tier**: Resource allocation category
-
-#### Model Options
-Available Claude models grouped by performance tier:
-
-**Haiku models** (fastest, most cost-effective):
-- claude-3-haiku-20240307
-- claude-3-5-haiku-20241022
-
-**Sonnet models** (balanced performance):
-- claude-3-sonnet-20240229
-- claude-3-5-sonnet-20241022
-- claude-3-5-sonnet-20240620
-- claude-sonnet-4-20250514
-- claude-4-sonnet-20250514
-
-**Opus models** (highest capability):
-- claude-3-opus-20240229
-- claude-opus-4-20250514
-- claude-4-opus-20250514
-
-#### Available Tools
-Tools are grouped by functionality:
-
-**File operations**:
-- `Read`: Read file contents
-- `Write`: Write new files
-- `Edit`: Edit existing files
-- `MultiEdit`: Multiple edits in one operation
-
-**Search and navigation**:
-- `Grep`: Search file contents
-- `Glob`: Find files by pattern
-- `LS`: List directory contents
-
-**System operations**:
-- `Bash`: Execute shell commands
-
-**Web operations**:
-- `WebSearch`: Search the web
-- `WebFetch`: Fetch web content
-
-**Notebook operations**:
-- `NotebookRead`: Read Jupyter notebooks
-- `NotebookEdit`: Edit Jupyter notebooks
-
-**Workflow operations**:
-- `TodoWrite`: Manage task lists
-- `ExitPlanMode`: Exit planning mode
-
-**CLI tools** (future expansion):
-- `git`: Git operations
-- `docker`: Docker commands
-- `kubectl`: Kubernetes operations
-- `terraform`: Infrastructure as code
-- `aws`: AWS CLI
-- `gcloud`: Google Cloud CLI
-- `azure`: Azure CLI
-
-#### Resource Tiers
-Resource allocation tiers determine memory, CPU, and timeout limits:
-
-- **basic**: Default resources for simple tasks
-- **standard**: Medium resources for typical operations
-- **intensive**: High resources for complex tasks
-- **lightweight**: Minimal resources for quick operations
-
-#### Capability Constraints
-
-**max_tokens**:
-- minimum: 1000 (Minimum for meaningful responses)
-- maximum: 200000 (Maximum supported by Claude models)
-- default: 8192 (Default suitable for most tasks)
-
-**temperature**:
-- minimum: 0 (0 = deterministic, focused)
-- maximum: 1 (1 = creative, varied)
-- default: 0.7 (Balanced default)
-
-**timeout**:
-- minimum: 30 (Minimum 30 seconds for basic operations)
-- maximum: 3600 (Maximum 1 hour for long-running tasks)
-- default: 300 (Default 5 minutes)
-
-### Instructions Field
-- **minLength**: 100 (Minimum to ensure meaningful instructions)
-- **maxLength**: 8000 (Maximum to fit within context limits)
-- **Description**: Agent system instructions that define behavior, approach, and constraints. This becomes the agent's system prompt.
-
-### Additional Properties
-- **additionalProperties**: false (Strict validation - no extra properties allowed)
-
-## Resource Tier Definitions
-
-These definitions provide guidance for resource allocation (not enforced by schema but used by runtime):
-
-### Intensive Tier
-- memory_limit: 4096-8192 MB
-- cpu_limit: 60-100%
-- timeout: 600-3600 seconds
-
-### Standard Tier
-- memory_limit: 2048-4096 MB
-- cpu_limit: 30-60%
-- timeout: 300-1200 seconds
-
-### Lightweight Tier
-- memory_limit: 512-2048 MB
-- cpu_limit: 10-30%
-- timeout: 30-600 seconds

claude_mpm/schemas/agent_schema_security_notes.md

@@ -1,165 +0,0 @@
-# Security Analysis: Agent Schema and Validation System
-
-## Overview
-This document provides a comprehensive security analysis of the claude-mpm agent validation system, highlighting security features, considerations, and recommendations.
-
-## Schema Security Features (agent_schema.json)
-
-### 1. Input Validation
-- **Strict Type Enforcement**: All fields have explicit types preventing type confusion attacks
-- **Pattern Validation**: Agent IDs use pattern `^[a-z][a-z0-9_]*$` preventing injection attacks
-- **Enum Restrictions**: Tools and models restricted to known safe values
-- **Length Limits**: All string fields have min/max length to prevent memory exhaustion
-  - Instructions: max 8000 characters
-  - Name: max 50 characters
-  - Description: max 200 characters
-
-### 2. Resource Controls
-- **Memory Limits**: 512MB-8192MB range prevents OOM attacks
-- **CPU Limits**: 10%-100% prevents resource hogging
-- **Timeout Limits**: 30s-3600s prevents infinite operations
-- **Token Limits**: 1000-200000 prevents API abuse
-
-### 3. Access Controls
-- **Network Access**: Default false, explicit opt-in required
-- **File Access Paths**: Explicit read/write path restrictions
-- **Tool Access**: Enumerated list prevents arbitrary tool usage
-- **Additional Properties**: Set to false preventing field injection
-
-### 4. Dangerous Tool Combinations
-The schema allows these potentially dangerous combinations:
-- **Bash + Write**: Can create and execute arbitrary scripts
-- **docker + kubectl**: Container escape potential
-- **aws + gcloud + azure**: Multiple cloud access increases attack surface
-
-## Validator Security Features (agent_validator.py)
-
-### 1. File Operation Security
-- **Path Validation**: Checks file exists and is regular file
-- **File Size Limits**: 1MB max prevents memory exhaustion
-- **Symlink Protection**: Skips symlinks to prevent directory traversal
-- **Directory Limits**: Max 100 files per directory prevents DoS
-
-### 2. Business Rule Security
-- **Double Validation**: Schema + business rules for defense in depth
-- **ID Format Checking**: Additional validation beyond schema pattern
-- **Resource Tier Validation**: Ensures limits match tier constraints
-- **Tool Compatibility**: Validates dangerous tool combinations
-
-### 3. Migration Security
-- **Privilege Escalation Prevention**: Flags dangerous tools added during migration
-- **Functionality Preservation**: Ensures security constraints maintained
-- **Instruction Validation**: Prevents loss of security instructions
-
-## Security Recommendations
-
-### 1. Immediate Improvements
-```python
-# Add to validator.py
-def _validate_path_injection(self, path: str) -> bool:
-    """Prevent path traversal attacks"""
-    if '..' in path or path.startswith('/'):
-        return False
-    return True
-
-def _validate_command_injection(self, value: str) -> bool:
-    """Prevent command injection in string values"""
-    dangerous_chars = ['$', '`', ';', '&', '|', '>', '<']
-    return not any(char in value for char in dangerous_chars)
-```
-
-### 2. Schema Enhancements
-```json
-{
-  "capabilities": {
-    "properties": {
-      "sandbox_mode": {
-        "type": "boolean",
-        "default": true,
-        "description": "Run agent in sandboxed environment"
-      },
-      "max_file_size": {
-        "type": "integer",
-        "default": 10485760,
-        "description": "Maximum file size agent can read/write (10MB default)"
-      }
-    }
-  }
-}
-```
-
-### 3. Audit Logging
-```python
-def validate_agent(self, agent_data: Dict[str, Any]) -> ValidationResult:
-    # Add security audit logging
-    audit_log = {
-        "timestamp": datetime.utcnow().isoformat(),
-        "agent_id": agent_data.get("id"),
-        "tools": agent_data.get("capabilities", {}).get("tools", []),
-        "network_access": agent_data.get("capabilities", {}).get("network_access", False),
-        "validation_result": "pending"
-    }
-    # Log to security audit trail
-```
-
-### 4. Runtime Security Checks
-- Implement runtime validation of actual tool usage vs declared tools
-- Monitor resource usage against declared limits
-- Validate file access against declared paths
-- Check for privilege escalation attempts
-
-## Potential Security Issues
-
-### 1. Missing Validations
-- No validation of hook configurations
-- No validation of file path patterns for malicious patterns
-- No rate limiting on validation operations
-- No cryptographic signing of agent configurations
-
-### 2. Information Disclosure
-- Error messages may reveal system paths
-- Schema version in metadata could aid attackers
-- No sanitization of user-provided descriptions
-
-### 3. Trust Boundaries
-- No verification of agent template sources
-- No integrity checking of loaded schemas
-- Migration process trusts old configurations
-
-## Security Best Practices for Agent Authors
-
-1. **Principle of Least Privilege**: Only request tools actually needed
-2. **Avoid Dangerous Combinations**: Don't combine Bash with Write unless essential
-3. **Explicit Path Restrictions**: Always specify file access paths
-4. **Network Isolation**: Only enable network_access when required
-5. **Resource Limits**: Set appropriate limits for agent workload
-6. **Input Sanitization**: Never trust user input in agent instructions
-7. **Secure Defaults**: Start with minimal permissions and add as needed
-
-## Compliance Considerations
-
-### OWASP Top 10 Coverage
-- **A01:2021 Broken Access Control**: ✓ Tool and file access restrictions
-- **A02:2021 Cryptographic Failures**: ⚠️ No encryption of agent configs
-- **A03:2021 Injection**: ✓ Pattern validation, enum restrictions
-- **A04:2021 Insecure Design**: ✓ Defense in depth validation
-- **A05:2021 Security Misconfiguration**: ✓ Secure defaults, explicit opt-in
-- **A06:2021 Vulnerable Components**: ⚠️ No component version checking
-- **A07:2021 Identification and Authentication**: N/A (handled elsewhere)
-- **A08:2021 Software and Data Integrity**: ⚠️ No integrity verification
-- **A09:2021 Security Logging**: ⚠️ Limited security event logging
-- **A10:2021 SSRF**: ✓ Network access controls
-
-## Conclusion
-
-The claude-mpm validation system implements strong security controls through:
-- Strict schema validation with type safety
-- Resource limits preventing DoS attacks
-- Access controls for tools and files
-- Defense in depth with multiple validation layers
-
-Key areas for improvement:
-- Cryptographic signing of configurations
-- Enhanced audit logging
-- Runtime security monitoring
-- Integrity verification