claude-mpm 2.1.1__py3-none-any.whl → 3.0.1__py3-none-any.whl

claude_mpm/schemas/README_SECURITY.md

@@ -0,0 +1,92 @@
+# Agent Schema Security Guide
+
+## Critical Security Notice
+
+**This schema is a SECURITY BOUNDARY.** Any changes to agent_schema.json must be carefully reviewed for security implications.
+
+## Security Controls in agent_schema.json
+
+### 1. Field Validation
+- **agent_id**: Pattern `^[a-z][a-z0-9_]*$` prevents path traversal and command injection
+- **version fields**: Semantic versioning pattern prevents version injection
+- **enums**: All enums are allowlists preventing arbitrary values
+
+### 2. Size Limits
+- **instructions**: 8000 char max prevents memory exhaustion
+- **name**: 50 char max prevents UI breaking
+- **description**: 200 char max prevents storage abuse
+- **tags**: max 10 items prevents array bombing
+
+### 3. Resource Limits by Tier
+```
+intensive:    memory: 4096-8192MB, cpu: 60-100%, timeout: 600-3600s
+standard:     memory: 2048-4096MB, cpu: 30-60%,  timeout: 300-1200s  
+lightweight:  memory: 512-2048MB,  cpu: 10-30%,  timeout: 30-600s
+```
+
+### 4. Tool Security Matrix
+
+| Tool Combination | Risk Level | Security Impact |
+|-----------------|------------|-----------------|
+| Bash + Write | CRITICAL | Arbitrary code execution |
+| docker + kubectl | HIGH | Container escape potential |
+| aws + gcloud + azure | HIGH | Multi-cloud attack surface |
+| WebFetch + Write | MEDIUM | Data exfiltration risk |
+| Read + network_access | MEDIUM | Information disclosure |
+
+### 5. Required Security Reviews
+
+Any PR modifying agent_schema.json MUST include:
+1. Security impact assessment
+2. Validation that no new fields bypass security controls
+3. Test cases for new validation rules
+4. Update to this security guide if needed
+
+### 6. Security Checklist for Schema Changes
+
+- [ ] No new fields allow arbitrary string input without validation
+- [ ] All new arrays have maxItems limits
+- [ ] All new strings have maxLength limits
+- [ ] New enum values are reviewed for security impact
+- [ ] Resource limits maintain tier boundaries
+- [ ] No new fields can bypass additionalProperties: false
+- [ ] Pattern validations prevent injection attacks
+- [ ] Default values follow principle of least privilege
+
+## Common Security Mistakes to Avoid
+
+1. **Never** add fields that accept arbitrary file paths without validation
+2. **Never** increase resource limits without security review
+3. **Never** add tools that bypass the enum list
+4. **Never** remove pattern validation from ID fields
+5. **Never** set additionalProperties to true
+6. **Always** default network_access to false
+7. **Always** validate new tool combinations for security impact
+
+## Security Testing
+
+Run these tests after any schema change:
+```bash
+# Validate schema structure
+python scripts/validate_agent_schema.py
+
+# Test security boundaries
+python tests/test_agent_security_boundaries.py
+
+# Check for injection vulnerabilities
+python tests/test_agent_validation_security.py
+```
+
+## Incident Response
+
+If a security vulnerability is found in the schema:
+1. Immediately add validation in agent_validator.py as a hotfix
+2. Update schema to prevent the vulnerability
+3. Audit all existing agents for exploitation
+4. Document the vulnerability and fix in security log
+
+## Security Contacts
+
+- Security reviews: security-team@company.com
+- Vulnerability reports: security@company.com
+- Emergency response: security-oncall@company.com

claude_mpm/schemas/agent_schema.json

@@ -1,37 +1,71 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.2.0",
   "title": "Claude MPM Agent Schema",
-  "description": "Schema definition for Claude MPM agent templates",
+  "description": "Schema definition for Claude MPM agent templates. This schema enforces the structure and validation rules for all agent configurations in the Claude MPM system.",
   "type": "object",
-  "required": ["id", "version", "metadata", "capabilities", "instructions"],
+  "required": [
+    "schema_version",  // Required: Must match the schema version this agent was built for
+    "agent_id",        // Required: Unique identifier for the agent type
+    "agent_version",   // Required: Semantic version of this specific agent template
+    "agent_type",      // Required: Categorizes the agent's primary function
+    "metadata",        // Required: Human-readable information about the agent
+    "capabilities",    // Required: Technical specifications and resource requirements
+    "instructions"     // Required: System prompt that defines agent behavior
+  ],
   "properties": {
-    "id": {
+    "schema_version": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9_]*$",
-      "description": "Unique agent identifier (lowercase, alphanumeric with underscores)",
-      "examples": ["research", "engineer", "qa", "security"]
+      "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"]
     },
-    "version": {
+    "agent_id": {
       "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Semantic version of the agent template",
+      "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": {
+      "type": "string",
+      "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": {
+      "type": "string",
+      "description": "Type of agent that determines its primary function and default capabilities. This categorization helps in agent discovery and capability matching.",
+      "enum": [
+        "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": {
       "type": "object",
-      "required": ["name", "description", "category", "tags"],
+      "required": [
+        "name",         // Human-readable name for UI display
+        "description",  // Brief explanation of agent's purpose
+        "tags"          // Searchable tags for agent discovery
+      ],
       "properties": {
         "name": {
           "type": "string",
-          "minLength": 3,
-          "maxLength": 50,
-          "description": "Human-readable agent name"
+          "minLength": 3,      // Minimum 3 characters for meaningful names
+          "maxLength": 50,     // Maximum 50 characters to prevent UI overflow
+          "description": "Human-readable agent name displayed in UI and logs. Should be concise but descriptive."
         },
         "description": {
           "type": "string",
-          "minLength": 10,
-          "maxLength": 200,
-          "description": "Brief description of agent purpose"
+          "minLength": 10,     // Minimum 10 characters to ensure meaningful descriptions
+          "maxLength": 200,    // Maximum 200 characters for conciseness
+          "description": "Brief description of agent purpose and capabilities. Used in agent selection and documentation."
         },
         "category": {
           "type": "string",
@@ -42,12 +76,12 @@
           "type": "array",
           "items": {
             "type": "string",
-            "pattern": "^[a-z][a-z0-9-]*$"
+            "pattern": "^[a-z][a-z0-9-]*$"  // Lowercase letters, numbers, and hyphens only
           },
-          "minItems": 1,
-          "maxItems": 10,
-          "uniqueItems": true,
-          "description": "Tags for agent discovery"
+          "minItems": 1,        // At least one tag required for discovery
+          "maxItems": 10,       // Maximum 10 tags to prevent over-tagging
+          "uniqueItems": true,  // No duplicate tags allowed
+          "description": "Tags for agent discovery and categorization. Used by the agent registry for searching and filtering."
         },
         "author": {
           "type": "string",
@@ -67,66 +101,99 @@
     },
     "capabilities": {
       "type": "object",
-      "required": ["model", "tools", "resource_tier"],
+      "required": [
+        "model",          // Claude model version to use
+        "tools",          // Array of allowed tools for the agent
+        "resource_tier"   // Resource allocation category
+      ],
       "properties": {
         "model": {
           "type": "string",
           "enum": [
+            // 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-opus-20240229",
             "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"
           ],
-          "description": "Claude model to use for this agent"
+          "description": "Claude model to use for this agent. Choose based on task complexity and performance requirements."
         },
         "tools": {
           "type": "array",
           "items": {
             "type": "string",
             "enum": [
-              "Read", "Write", "Edit", "MultiEdit",
-              "Grep", "Glob", "LS", "Bash",
-              "WebSearch", "WebFetch",
-              "NotebookRead", "NotebookEdit",
-              "TodoWrite", "ExitPlanMode",
-              "git", "docker", "kubectl", "terraform",
-              "aws", "gcloud", "azure"
+              // 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
             ]
           },
-          "uniqueItems": true,
-          "description": "Available tools for the agent"
+          "uniqueItems": true,  // Each tool can only be listed once
+          "description": "Available tools for the agent. Tools determine what operations the agent can perform."
         },
         "resource_tier": {
           "type": "string",
-          "enum": ["intensive", "standard", "lightweight"],
-          "description": "Resource allocation tier"
+          "enum": [
+            "basic",         // Default resources for simple tasks
+            "standard",      // Medium resources for typical operations
+            "intensive",     // High resources for complex tasks
+            "lightweight"    // Minimal resources for quick operations
+          ],
+          "description": "Resource allocation tier that determines memory, CPU, and timeout limits. See definitions section for specific limits."
         },
         "max_tokens": {
           "type": "integer",
-          "minimum": 1000,
-          "maximum": 200000,
-          "default": 8192,
-          "description": "Maximum tokens for response"
+          "minimum": 1000,      // Minimum for meaningful responses
+          "maximum": 200000,    // Maximum supported by Claude models
+          "default": 8192,      // Default suitable for most tasks
+          "description": "Maximum tokens for response generation. Higher values allow longer responses but increase cost and latency."
         },
         "temperature": {
           "type": "number",
-          "minimum": 0,
-          "maximum": 1,
-          "default": 0.7,
-          "description": "Model temperature setting"
+          "minimum": 0,         // 0 = deterministic, focused
+          "maximum": 1,         // 1 = creative, varied
+          "default": 0.7,       // Balanced default
+          "description": "Model temperature setting controlling response randomness. Lower values for consistency, higher for creativity."
         },
         "timeout": {
           "type": "integer",
-          "minimum": 30,
-          "maximum": 3600,
-          "default": 300,
-          "description": "Operation timeout in seconds"
+          "minimum": 30,        // Minimum 30 seconds for basic operations
+          "maximum": 3600,      // Maximum 1 hour for long-running tasks
+          "default": 300,       // Default 5 minutes
+          "description": "Operation timeout in seconds. Should align with resource_tier settings."
         },
         "memory_limit": {
           "type": "integer",
@@ -159,14 +226,24 @@
               "description": "Allowed write paths"
             }
           }
+        },
+        "allowed_tools": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Glob patterns for allowed file paths. Restricts which files the agent can access (e.g., 'tests/**' for test files only)."
+        },
+        "disallowed_tools": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Tool names to explicitly disallow, overriding the tools array. Use for security restrictions (e.g., 'Bash' to prevent shell access)."
         }
       }
     },
     "instructions": {
       "type": "string",
-      "minLength": 100,
-      "maxLength": 8000,
-      "description": "Agent system instructions (8000 character limit)"
+      "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."
     },
     "knowledge": {
       "type": "object",
@@ -305,8 +382,10 @@
       }
     }
   },
-  "additionalProperties": false,
+  "additionalProperties": false,  // Strict validation - no extra properties allowed
   "definitions": {
+    // Resource tier definitions provide guidance for resource allocation
+    // These are not enforced by the schema but used by the runtime
     "resource_tier_limits": {
       "intensive": {
         "memory_limit": {"min": 4096, "max": 8192},

claude_mpm/schemas/agent_schema_security_notes.md

@@ -0,0 +1,165 @@
+# 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

claude_mpm/services/agent_capabilities_generator.py

@@ -47,7 +47,6 @@ class AgentCapabilitiesGenerator:
                 total_agents=len(deployed_agents)
             )
             
-            logger.info(f"Generated capabilities section for {len(deployed_agents)} agents")
             return content
             
         except Exception as e: