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

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

claude_mpm/schemas/examples/standard_workflow.json

@@ -1,505 +0,0 @@
-{
-  "schema_version": "1.0.0",
-  "workflow_id": "standard_workflow",
-  "workflow_version": "1.0.0",
-  "metadata": {
-    "name": "Standard Ticket Workflow",
-    "description": "Default workflow for general ticket management with clear status-resolution separation",
-    "workflow_type": "standard",
-    "author": "Claude MPM Team",
-    "created_at": "2025-01-28T00:00:00Z",
-    "updated_at": "2025-01-28T00:00:00Z",
-    "tags": ["default", "general", "support"]
-  },
-  "status_states": {
-    "states": [
-      {
-        "id": "open",
-        "name": "Open",
-        "description": "Ticket has been created but not yet assigned or started",
-        "category": "initial",
-        "is_default": true,
-        "color": "#9E9E9E",
-        "icon": "circle-o",
-        "sla_hours": 24
-      },
-      {
-        "id": "in_progress",
-        "name": "In Progress",
-        "description": "Ticket is actively being worked on by an assignee",
-        "category": "active",
-        "color": "#2196F3",
-        "icon": "spinner",
-        "sla_hours": 48
-      },
-      {
-        "id": "pending",
-        "name": "Pending",
-        "description": "Ticket is waiting for external input, dependencies, or customer response",
-        "category": "waiting",
-        "color": "#FF9800",
-        "icon": "clock-o"
-      },
-      {
-        "id": "resolved",
-        "name": "Resolved",
-        "description": "Work is complete and solution has been implemented",
-        "category": "terminal",
-        "color": "#4CAF50",
-        "icon": "check-circle"
-      },
-      {
-        "id": "closed",
-        "name": "Closed",
-        "description": "Ticket is closed and no further action is required",
-        "category": "terminal",
-        "color": "#607D8B",
-        "icon": "archive"
-      },
-      {
-        "id": "reopened",
-        "name": "Reopened",
-        "description": "Previously closed ticket has been reopened for additional work",
-        "category": "active",
-        "color": "#9C27B0",
-        "icon": "refresh"
-      },
-      {
-        "id": "on_hold",
-        "name": "On Hold",
-        "description": "Work is temporarily suspended due to blockers or priorities",
-        "category": "waiting",
-        "color": "#795548",
-        "icon": "pause-circle"
-      },
-      {
-        "id": "escalated",
-        "name": "Escalated",
-        "description": "Ticket has been escalated to higher priority or management attention",
-        "category": "active",
-        "color": "#F44336",
-        "icon": "exclamation-triangle",
-        "sla_hours": 4
-      },
-      {
-        "id": "canceled",
-        "name": "Canceled",
-        "description": "Ticket has been canceled before completion",
-        "category": "terminal",
-        "color": "#E91E63",
-        "icon": "times-circle"
-      }
-    ],
-    "default_status": "open"
-  },
-  "resolution_types": {
-    "types": [
-      {
-        "id": "fixed",
-        "name": "Fixed/Resolved",
-        "description": "Issue was successfully fixed or request was fulfilled",
-        "category": "successful",
-        "requires_comment": false,
-        "color": "#4CAF50",
-        "icon": "check"
-      },
-      {
-        "id": "wont_fix",
-        "name": "Won't Fix",
-        "description": "Deliberate decision made not to address the issue",
-        "category": "unsuccessful",
-        "requires_comment": true,
-        "color": "#F44336",
-        "icon": "ban"
-      },
-      {
-        "id": "duplicate",
-        "name": "Duplicate",
-        "description": "Issue is a duplicate of another existing ticket",
-        "category": "invalid",
-        "requires_comment": true,
-        "color": "#9E9E9E",
-        "icon": "copy"
-      },
-      {
-        "id": "cannot_reproduce",
-        "name": "Cannot Reproduce",
-        "description": "Issue cannot be reproduced or verified",
-        "category": "invalid",
-        "requires_comment": true,
-        "color": "#FF9800",
-        "icon": "question-circle"
-      },
-      {
-        "id": "works_as_designed",
-        "name": "Works as Designed",
-        "description": "Reported behavior is intentional and not a bug",
-        "category": "invalid",
-        "requires_comment": false,
-        "color": "#3F51B5",
-        "icon": "info-circle"
-      },
-      {
-        "id": "incomplete",
-        "name": "Incomplete",
-        "description": "Insufficient information provided to proceed",
-        "category": "unsuccessful",
-        "requires_comment": true,
-        "color": "#795548",
-        "icon": "file-text-o"
-      },
-      {
-        "id": "user_error",
-        "name": "User Error",
-        "description": "Issue was due to user error or misunderstanding",
-        "category": "invalid",
-        "requires_comment": true,
-        "color": "#607D8B",
-        "icon": "user-times"
-      },
-      {
-        "id": "configuration",
-        "name": "Configuration",
-        "description": "Issue was resolved through configuration changes only",
-        "category": "successful",
-        "requires_comment": false,
-        "color": "#00BCD4",
-        "icon": "cog"
-      },
-      {
-        "id": "workaround",
-        "name": "Workaround",
-        "description": "A workaround has been provided as an alternative solution",
-        "category": "successful",
-        "requires_comment": true,
-        "color": "#CDDC39",
-        "icon": "lightbulb-o"
-      },
-      {
-        "id": "documentation",
-        "name": "Documentation",
-        "description": "Issue was resolved by updating or providing documentation",
-        "category": "successful",
-        "requires_comment": false,
-        "color": "#009688",
-        "icon": "book"
-      }
-    ]
-  },
-  "transitions": {
-    "rules": [
-      {
-        "from_status": "open",
-        "to_status": "in_progress",
-        "name": "Start Work",
-        "description": "Begin working on the ticket",
-        "required_fields": ["assignee"],
-        "auto_assign": true
-      },
-      {
-        "from_status": "open",
-        "to_status": "escalated",
-        "name": "Escalate",
-        "description": "Escalate ticket for immediate attention",
-        "permissions": ["escalate_ticket"]
-      },
-      {
-        "from_status": "open",
-        "to_status": "canceled",
-        "name": "Cancel",
-        "description": "Cancel ticket without starting work",
-        "required_fields": ["resolution"]
-      },
-      {
-        "from_status": "in_progress",
-        "to_status": "pending",
-        "name": "Wait for Input",
-        "description": "Pause work to wait for external input"
-      },
-      {
-        "from_status": "in_progress",
-        "to_status": "on_hold",
-        "name": "Put on Hold",
-        "description": "Temporarily suspend work"
-      },
-      {
-        "from_status": "in_progress",
-        "to_status": "resolved",
-        "name": "Resolve",
-        "description": "Mark work as complete",
-        "required_fields": ["resolution"]
-      },
-      {
-        "from_status": "in_progress",
-        "to_status": "escalated",
-        "name": "Escalate",
-        "description": "Escalate active ticket",
-        "permissions": ["escalate_ticket"]
-      },
-      {
-        "from_status": "pending",
-        "to_status": "in_progress",
-        "name": "Resume Work",
-        "description": "Resume work after receiving input"
-      },
-      {
-        "from_status": "on_hold",
-        "to_status": "in_progress",
-        "name": "Resume Work",
-        "description": "Resume work from hold status"
-      },
-      {
-        "from_status": "resolved",
-        "to_status": "closed",
-        "name": "Close",
-        "description": "Close resolved ticket"
-      },
-      {
-        "from_status": "resolved",
-        "to_status": "reopened",
-        "name": "Reopen",
-        "description": "Reopen resolved ticket for additional work"
-      },
-      {
-        "from_status": "closed",
-        "to_status": "reopened",
-        "name": "Reopen",
-        "description": "Reopen closed ticket",
-        "permissions": ["reopen_ticket"]
-      },
-      {
-        "from_status": "reopened",
-        "to_status": "in_progress",
-        "name": "Start Rework",
-        "description": "Begin working on reopened ticket",
-        "required_fields": ["assignee"]
-      },
-      {
-        "from_status": "escalated",
-        "to_status": "in_progress",
-        "name": "De-escalate",
-        "description": "Return to normal priority",
-        "permissions": ["escalate_ticket"]
-      },
-      {
-        "from_status": "escalated",
-        "to_status": "resolved",
-        "name": "Resolve",
-        "description": "Resolve escalated ticket",
-        "required_fields": ["resolution"]
-      },
-      {
-        "from_status": "*",
-        "to_status": "canceled",
-        "name": "Force Cancel",
-        "description": "Cancel ticket from any state",
-        "permissions": ["admin_ticket"],
-        "required_fields": ["resolution"]
-      }
-    ],
-    "allow_self_transitions": false
-  },
-  "status_resolution_mapping": {
-    "mappings": [
-      {
-        "status_id": "resolved",
-        "allowed_resolutions": [
-          "fixed",
-          "configuration",
-          "workaround",
-          "documentation"
-        ],
-        "requires_resolution": true,
-        "default_resolution": "fixed"
-      },
-      {
-        "status_id": "closed",
-        "allowed_resolutions": [
-          "fixed",
-          "wont_fix",
-          "duplicate",
-          "cannot_reproduce",
-          "works_as_designed",
-          "incomplete",
-          "user_error",
-          "configuration",
-          "workaround",
-          "documentation"
-        ],
-        "requires_resolution": true
-      },
-      {
-        "status_id": "canceled",
-        "allowed_resolutions": [
-          "duplicate",
-          "wont_fix",
-          "incomplete",
-          "user_error",
-          "works_as_designed"
-        ],
-        "requires_resolution": true,
-        "default_resolution": "wont_fix"
-      },
-      {
-        "status_id": "open",
-        "allowed_resolutions": [],
-        "requires_resolution": false
-      },
-      {
-        "status_id": "in_progress",
-        "allowed_resolutions": [],
-        "requires_resolution": false
-      },
-      {
-        "status_id": "pending",
-        "allowed_resolutions": [],
-        "requires_resolution": false
-      },
-      {
-        "status_id": "on_hold",
-        "allowed_resolutions": [],
-        "requires_resolution": false
-      },
-      {
-        "status_id": "escalated",
-        "allowed_resolutions": [],
-        "requires_resolution": false
-      },
-      {
-        "status_id": "reopened",
-        "allowed_resolutions": [],
-        "requires_resolution": false
-      }
-    ]
-  },
-  "business_rules": {
-    "auto_close": {
-      "enabled": true,
-      "days_after_resolved": 7,
-      "excluded_resolutions": ["workaround"]
-    },
-    "reopen_rules": {
-      "allow_reopen": true,
-      "from_statuses": ["resolved", "closed"],
-      "max_reopen_count": 3,
-      "reopen_window_days": 30
-    },
-    "escalation_rules": [
-      {
-        "name": "High Priority SLA",
-        "condition": {
-          "status": "open",
-          "hours_in_status": 4,
-          "priority": "high"
-        },
-        "action": {
-          "change_status": "escalated",
-          "notify": ["manager", "on_call"]
-        }
-      },
-      {
-        "name": "Critical Priority SLA",
-        "condition": {
-          "status": "open",
-          "hours_in_status": 1,
-          "priority": "critical"
-        },
-        "action": {
-          "change_status": "escalated",
-          "change_priority": "critical",
-          "notify": ["director", "manager", "on_call"]
-        }
-      },
-      {
-        "name": "Stale In Progress",
-        "condition": {
-          "status": "in_progress",
-          "hours_in_status": 168
-        },
-        "action": {
-          "notify": ["assignee", "manager"]
-        }
-      }
-    ]
-  },
-  "ui_configuration": {
-    "status_display_order": [
-      "open",
-      "in_progress",
-      "pending",
-      "on_hold",
-      "escalated",
-      "reopened",
-      "resolved",
-      "closed",
-      "canceled"
-    ],
-    "resolution_display_order": [
-      "fixed",
-      "configuration",
-      "workaround",
-      "documentation",
-      "duplicate",
-      "cannot_reproduce",
-      "works_as_designed",
-      "user_error",
-      "incomplete",
-      "wont_fix"
-    ],
-    "quick_transitions": [
-      {
-        "from_status": "open",
-        "to_status": "in_progress",
-        "button_label": "Start Work",
-        "button_style": "primary"
-      },
-      {
-        "from_status": "in_progress",
-        "to_status": "resolved",
-        "button_label": "Resolve",
-        "button_style": "success"
-      },
-      {
-        "from_status": "in_progress",
-        "to_status": "pending",
-        "button_label": "Wait for Input",
-        "button_style": "warning"
-      },
-      {
-        "from_status": "resolved",
-        "to_status": "closed",
-        "button_label": "Close",
-        "button_style": "secondary"
-      },
-      {
-        "from_status": "resolved",
-        "to_status": "reopened",
-        "button_label": "Reopen",
-        "button_style": "danger"
-      }
-    ]
-  },
-  "metrics": {
-    "cycle_time_statuses": {
-      "start": ["in_progress", "reopened"],
-      "end": ["resolved", "closed", "canceled"]
-    },
-    "resolution_metrics": [
-      {
-        "name": "Success Rate",
-        "resolution_ids": ["fixed", "configuration", "workaround", "documentation"],
-        "metric_type": "success_rate"
-      },
-      {
-        "name": "Invalid Rate",
-        "resolution_ids": ["duplicate", "cannot_reproduce", "works_as_designed", "user_error"],
-        "metric_type": "invalid_rate"
-      },
-      {
-        "name": "Incomplete Rate",
-        "resolution_ids": ["incomplete", "wont_fix"],
-        "metric_type": "incomplete_rate"
-      }
-    ]
-  }
-}