Security MCP Server

# Masscan Tool Implementation - Meticulous Review & Execution Plan ## Analysis Summary **Current State:** - ✅ Class structure, enums, and configuration (complete) - ✅ Privilege checking and validation (complete) - ✅ Argument parsing and rate limiting (complete) - ✅ XML parsing started (complete) - ⚠️ JSON parsing INCOMPLETE (cuts off at line 591: `if 'ip'`) - ❌ List format parsing (missing) - ❌ Template support methods (missing) - ❌ Tool info override (missing) - ❌ Utility helpers (missing) **Missing Components:** 1. **Complete `_parse_json_output`** - Cuts off mid-implementation 2. **Add `_parse_list_output`** - Default masscan output format 3. **Add `_get_template_args`** - Template to arguments mapping 4. **Add `run_with_template`** - Template execution method 5. **Add `get_tool_info`** - Masscan-specific tool information 6. **Add `_get_timestamp`** - Timestamp helper (used in error contexts) 7. **Add common port constants** - For template definitions 8. **Add validation helpers** - Configuration validation, cache clearing ## Execution Plan ### Phase 1: Analysis & Design ✅ - [x] Review incomplete code structure - [x] Identify missing methods and their dependencies - [x] Map out masscan output formats (XML, JSON, list) - [x] Design template argument mappings - [x] Validate security controls are complete ### Phase 2: Core Parsing (Priority 1) - [ ] Complete `_parse_json_output` with full JSON structure handling - [ ] Implement `_parse_list_output` with regex pattern for default format - [ ] Add error resilience to all parsing methods - [ ] Test parsing with sample outputs ### Phase 3: Template System (Priority 2) - [ ] Define common port sets as class constants - [ ] Implement `_get_template_args` for all 5 templates - [ ] Implement `run_with_template` async method - [ ] Ensure rate limits match template definitions ### Phase 4: Utility Methods (Priority 3) - [ ] Add `_get_timestamp` helper - [ ] Override `get_tool_info` with masscan specifics - [ ] Add `validate_configuration` method - [ ] Add `clear_privilege_cache` method ### Phase 5: Integration & Polish (Priority 4) - [ ] Verify all imports present - [ ] Ensure all error paths covered - [ ] Add missing docstrings - [ ] Final security review ### Phase 6: Validation ✅ - [ ] All referenced methods exist - [ ] All async methods use await properly - [ ] Type hints complete - [ ] Follows NmapTool patterns - [ ] Security controls verified - [ ] No orphaned references ## Design Decisions **1. Output Format Detection:** ```python # Order: XML → JSON → List (default) if "<nmaprun" in output or "<host" in output: # XML format (-oX) elif '"ip":' in output or '[' in output: # JSON format (-oJ) else: # List format (default) ``` **2. Template Rate Limits:** ```python QUICK: 100 pps (safe, under MAX_RATE_SAFE) STANDARD: 500 pps (safe, under MAX_RATE_SAFE) THOROUGH: 1000 pps (safe, at MAX_RATE_SAFE) WEB_SERVICES: 200 pps (safe, conservative) COMMON_SERVICES: 300 pps (safe, moderate) ``` **3. Port Sets for Templates:** ```python TOP_100_PORTS = "..." # Most common 100 TCP ports TOP_1000_PORTS = "..." # Top 1000 ports WEB_PORTS = "80,443,8080,8443,8008,8888,3000,5000" COMMON_PORTS = "21,22,23,25,53,80,110,143,443,445,3306,3389,5432,8080" ``` **4. JSON Structure Handling:** Masscan JSON can be: - Array of objects: `[{"ip": "...", "ports": [...]}]` - Line-delimited JSON: Multiple JSON objects separated by newlines - Single object: `{"ip": "...", "ports": [...]}` **5. Error Resilience:** - All parsing methods return empty list on error (don't fail execution) - Log warnings for parse failures - Preserve raw output in metadata ## Pre-Implementation Validation **Security Review:** - ✅ Rate limiting multi-tier system correct - ✅ Privilege checking comprehensive - ✅ Network size limits enforced - ✅ Policy-based controls for intrusive operations - ✅ Absolute maximum rate enforced (100,000 pps emergency brake) - ✅ No shell injection vulnerabilities **Consistency Review:** - ✅ Follows MCPBaseTool patterns - ✅ Uses ErrorContext for all errors - ✅ Proper async/await usage - ✅ Configuration integration matches NmapTool - ✅ Logging structured with key=value pairs **Completeness Review:** - ✅ All `_FLAGS_REQUIRE_VALUE` flags handled - ✅ All `allowed_flags` validated - ✅ All error paths return ToolOutput - ⚠️ Missing `_get_timestamp` (used in multiple places) - ⚠️ Missing template implementation ## Implementation Ready ✅ The plan is validated and ready for implementation. The code will be: 1. **Drop-in compatible** - No changes to existing complete methods 2. **Complete** - All missing methods implemented 3. **Tested patterns** - Based on working NmapTool implementation 4. **Secure** - All safety controls preserved and enhanced 5. **Production-ready** - Comprehensive error handling and logging **Proceed with implementation?** The complete code will be provided in the next response as a single, ready-to-use file.