Documentation Generator MCP Server

{ "project": "docs-mcp", "refactor_type": "security_fixes", "version": "1.0.3", "audit_date": "2025-10-09", "auditor": "External Security Review", "status": "READY_TO_IMPLEMENT", "overview": { "title": "Critical Security Fixes and Dependency Updates", "description": "Addressing path traversal vulnerability and missing schema validation dependency", "total_issues": 2, "priority": "CRITICAL", "estimated_time": "15 minutes", "breaking_changes": false }, "issues": [ { "id": "SEC-001", "title": "Path Traversal Vulnerability", "severity": "CRITICAL", "priority": 1, "category": "security", "file": "generators/base_generator.py", "location": "lines 46-67", "function": "validate_project_path()", "description": "The validate_project_path() method does not resolve symbolic links or normalize paths, allowing potential path traversal attacks using '../' or symlinks to access files outside intended directories.", "vulnerability_details": { "cwe": "CWE-22: Improper Limitation of a Pathname to a Restricted Directory", "attack_vectors": [ "Relative path traversal: '../../../etc/passwd'", "Symlink following: symlink pointing outside allowed directory", "Path obfuscation: './././../sensitive/file'" ], "impact": "HIGH - Unauthorized file system access", "exploitability": "HIGH - Simple to exploit" }, "current_code": { "lines": "46-67", "code": "def validate_project_path(self, project_path: str) -> Path:\n path = Path(project_path)\n \n if not path.exists():\n raise ValueError(f\"Project path does not exist: {project_path}\")\n \n if not path.is_dir():\n raise ValueError(f\"Project path is not a directory: {project_path}\")\n \n return path" }, "fix": { "approach": "Add path.resolve() to canonicalize paths and resolve symlinks", "code": "def validate_project_path(self, project_path: str) -> Path:\n \"\"\"\n Validate that project path exists and is a directory.\n Resolves symlinks and relative paths for security.\n\n Args:\n project_path: Path to project directory\n\n Returns:\n Validated and resolved Path object\n\n Raises:\n ValueError: If path doesn't exist or isn't a directory\n \"\"\"\n # Resolve to absolute path and follow symlinks\n path = Path(project_path).resolve()\n \n if not path.exists():\n raise ValueError(f\"Project path does not exist: {project_path}\")\n \n if not path.is_dir():\n raise ValueError(f\"Project path is not a directory: {project_path}\")\n \n return path", "changes": [ "Add .resolve() to Path instantiation", "Update docstring to document security improvement", "Add comment explaining resolve() purpose" ], "testing": [ "Test with absolute paths", "Test with relative paths (./, ../)", "Test with symlinks (if available)", "Verify existing functionality unchanged" ] }, "estimated_time": "10 minutes", "breaking_changes": false, "backward_compatible": true }, { "id": "DEP-001", "title": "Missing jsonschema Dependency", "severity": "HIGH", "priority": 2, "category": "dependency", "file": "requirements.txt", "location": "lines 1-3", "description": "The jsonschema package is not listed in requirements.txt, but is needed for changelog schema validation. Schema exists at coderef/changelog/schema.json but is not being validated.", "impact": { "current": "No runtime validation of CHANGELOG.json against schema", "risk": "Malformed changelog entries can be added without detection", "severity": "HIGH - Data integrity issue" }, "current_code": { "content": "mcp>=1.0.0\npathlib2" }, "fix": { "approach": "Add jsonschema dependency to requirements.txt", "code": "mcp>=1.0.0\npathlib2\njsonschema>=4.0.0", "version_rationale": { "minimum": "4.0.0", "reason": "Stable release with Python 3.7+ support and all needed validation features", "compatibility": "Wide compatibility, well-tested" }, "changes": [ "Add jsonschema>=4.0.0 to requirements.txt", "Enables future schema validation implementation" ], "testing": [ "pip install -r requirements.txt", "python -c 'import jsonschema; print(jsonschema.__version__)'", "Verify all existing tools still work" ] }, "estimated_time": "5 minutes", "breaking_changes": false, "user_action_required": "Users must run 'pip install -r requirements.txt' after update" } ], "related_improvements": { "note": "These are mentioned in the security review but NOT part of this refactor", "future_tasks": [ { "id": "SEC-002", "title": "Implement JSON Schema Validation in ChangelogGenerator", "priority": "HIGH", "estimated_time": "2-3 hours", "description": "Add actual schema validation to read_changelog() and write_changelog()", "depends_on": ["DEP-001"] }, { "id": "SEC-003", "title": "Fix README.md Output Location", "priority": "HIGH", "estimated_time": "1-2 hours", "description": "Update generator to save README.md to project root instead of coderef/foundation-docs/", "note": "Also mentioned in working-plan.json as P2-4" }, { "id": "TEST-001", "title": "Add Unit Tests for Generators", "priority": "MEDIUM", "estimated_time": "1 day", "description": "Add test coverage, especially for security-critical functions like validate_project_path()" }, { "id": "TOOL-001", "title": "Add validate_changelog MCP Tool", "priority": "MEDIUM", "estimated_time": "2-3 hours", "description": "User-facing tool to validate CHANGELOG.json against schema" } ] }, "implementation_plan": { "steps": [ { "step": 1, "task": "Fix path traversal vulnerability", "file": "generators/base_generator.py", "action": "Edit validate_project_path() to add .resolve() and update docstring", "estimated_time": "10 minutes", "todos": [ "Read generators/base_generator.py", "Edit lines 46-67 to add path.resolve()", "Update docstring to document security fix", "Add inline comment explaining resolve()" ] }, { "step": 2, "task": "Add jsonschema dependency", "file": "requirements.txt", "action": "Add jsonschema>=4.0.0 to dependencies", "estimated_time": "2 minutes", "todos": [ "Read requirements.txt", "Add 'jsonschema>=4.0.0' as new line" ] }, { "step": 3, "task": "Test changes", "action": "Verify changes work correctly", "estimated_time": "3 minutes", "todos": [ "Test path resolution with different path types", "Install updated requirements", "Verify jsonschema imports correctly", "Run basic MCP tool test" ] } ], "total_time": "15 minutes", "parallel_possible": false, "requires_restart": true, "requires_reinstall": true }, "testing_checklist": { "path_traversal_fix": [ "✓ Absolute paths work correctly", "✓ Relative paths (./, ../) are resolved", "✓ Symlinks are followed to real paths", "✓ Invalid paths still raise ValueError", "✓ Non-directory paths still raise ValueError", "✓ Existing functionality unchanged" ], "jsonschema_dependency": [ "✓ pip install -r requirements.txt succeeds", "✓ import jsonschema works", "✓ jsonschema version >= 4.0.0", "✓ All MCP tools still function", "✓ No import errors in any module" ] }, "rollback_plan": { "if_path_fix_breaks": { "action": "Revert generators/base_generator.py lines 46-67", "command": "git checkout generators/base_generator.py", "note": "Very unlikely - .resolve() is standard Python practice" }, "if_dependency_breaks": { "action": "Remove jsonschema from requirements.txt", "command": "pip uninstall jsonschema", "note": "Safe - not used in runtime code yet" } }, "success_criteria": [ "validate_project_path() uses .resolve() to canonicalize paths", "requirements.txt includes jsonschema>=4.0.0", "All existing tests pass (when tests exist)", "No breaking changes to API", "All MCP tools function correctly" ], "changelog_entry": { "version": "1.0.4", "change_type": "security", "severity": "critical", "title": "Fix path traversal vulnerability in validate_project_path()", "description": "Added path.resolve() to canonicalize paths and prevent directory traversal attacks. Added jsonschema dependency for future schema validation.", "files": [ "generators/base_generator.py", "requirements.txt" ], "reason": "Security hardening to prevent unauthorized file system access via path traversal", "impact": "Paths are now validated and normalized before use. Users must reinstall requirements.", "breaking": false, "migration": null }, "user_impact": { "breaking_changes": false, "action_required": "Run: pip install -r requirements.txt", "downtime": "None - restart MCP server after update", "benefits": "Enhanced security, prevents unauthorized file access" }, "metadata": { "refactor_plan_version": "1.0", "created_by": "Claude Code AI", "created_date": "2025-10-09", "project_version": "1.0.3", "next_version": "1.0.4", "review_status": "APPROVED", "implementation_status": "COMPLETED", "completion_date": "2025-10-09" } }