Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The server defines 3 tools with explicit schemas and descriptions visible in server.py. However, execution handler code is truncated mid-function, preventing verification of actual error handling, validation, and recovery guidance implementation. Tool naming follows verb_noun conventions (nmap_scan, gobuster_scan, get_scan_events), descriptions are present (60-75 chars each, below the optimal 100-200 char range for LLM optimization), and input schemas are formally declared with JSON Schema. Critical gaps: (1) Output schemas are completely undocumented, responses are not defined, preventing LLMs from knowing what to expect and plan downstream calls; (2) Parameter descriptions lack constraint details (e.g., no format for 'targets', no range for 'timeout', no clarification of port format); (3) Error handling strategy is invisible, handler code is truncated before `handle_call_tool` implementation; (4) No validation guidance, LLMs will hallucinate invalid inputs; (5) No security annotations or permission gating despite tools executing arbitrary external commands (nmap, gobuster). The truncation is critical, without seeing the tool implementations, we cannot assess whether error messages guide recovery (per pattern:recovery-guide), whether inputs are validated, or whether dangerous operations have safeguards.
Tools (3)
get_scan_eventsread onlysource verified50/100
Retrieve events from completed scans
gobuster_scanread onlysource verified55/100
Execute Gobuster directory/file brute-force scans for web application enumeration
nmap_scanread onlysource verified58/100
Execute Nmap network scans for port discovery, service detection, and OS fingerprinting
Parameter descriptions lack constraint details (no format, no min/max, no valid enum values for enums). 'targets' has no format spec, 'timeout' unbounded, 'event_type' filter has no valid values listed.
Tool execution handler code is truncated mid-function (at 'if name == "nmap_s'). Cannot verify error handling, input validation, recovery guidance, or security gating.
nmap_scangobuster_scanget_scan_events
Recommendations
Add detailed output schema for each tool in the list_tools response. Specify the structure of 'nmap_scan' results (fields: ports, services, os_guess, raw_output?), 'gobuster_scan' results (found_paths, status_codes, response_sizes?), and 'get_scan_events' (event structure with timestamp, event_type, payload, scan_id). Include example JSON structures.
Enhance parameter descriptions with explicit constraints: (1) 'targets': specify format, 'CIDR notation (e.g., 192.168.1.0/24), single host (10.0.0.1), or hostname (example.com)'; (2) 'ports': clarify format, 'Comma-separated ports (80,443), range (1-1000), or Nmap preset (top-ports 1000)'; (3) 'timeout': add bounds, 'Integer, 10-86400 seconds (default 3600)'; (4) 'event_type': document valid enum, 'Valid values: port_open, service_detected, os_match, directory_found, file_found. Omit to retrieve all events'.
Implement and document error recovery guidance in the handler (currently truncated code). For each error, return structured error with: (1) error code (INVALID_TARGET, NMAP_TIMEOUT, WORDLIST_NOT_FOUND), (2) actionable message ('Target "invalid!@#" is not valid CIDR or hostname. Try: 192.168.1.1 or example.com'), (3) retry hint ('Retryable: yes'). Example: {'error': 'WORDLIST_NOT_FOUND', 'message': 'Wordlist /path/to/list.txt not found. Check file exists and is readable.', 'retryable': false}.
Add security annotations and permission gating. Declare tool scopes: nmap_scan requires 'admin:network_scan' (dangerous, can detect/fingerprint external systems); gobuster_scan requires 'admin:web_enum' (can trigger WAF/IDS alerts). Return permission denied if caller lacks scope. Add confirmation step for scans against unfamiliar targets: implement a dry_run parameter that returns the nmap/gobuster command without executing it, letting LLM show user before proceeding.
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
No permission gating or security annotations for tools that execute external commands (nmap, gobuster). These tools trigger network activity and can be legally/operationally risky. No scope declarations (read:network? admin:scan?), no dry-run option, no audit trail hints.
Tool descriptions are below optimal LLM-guidance range (38-66 chars vs recommended 100-200 chars). Lack actionable WHEN/WHY guidance, prerequisites, side effects, and dependency hints.
'get_scan_events' has no pagination support (offset, cursor, or next_token). No indication of max result size or whether large event logs are capped. Without pagination, unbounded results risk context window exhaustion.
get_scan_events
Add pagination to 'get_scan_events': (1) accept 'offset' (0-indexed) and 'limit' (1-100, default 20) parameters; (2) return {events: [...], total_count: N, offset: M, has_more: bool}. Document: 'Maximum 100 events per call. Use offset to retrieve subsequent batches.'
Expand tool descriptions to 100-200 char range with WHEN/WHY/HOW guidance. Example: nmap_scan → 'Execute network reconnaissance scans (port discovery, service identification, OS detection). Call this first during reconnaissance phase to map target infrastructure. Returns open ports, service versions, and OS hints. Requires network access to target. Side effect: scans are logged by target firewalls and may trigger alerts.'
Document expected behavior for edge cases: What if nmap times out? (Return partial results + timeout error.) What if gobuster wordlist is missing? (Return error: file not found, with suggestion to use default.) What if get_scan_events is called before any scans? (Return empty events list, not error.) Add these to handler implementation and describe in tool documentation.
Consider adding a batch variant or multi-scan tool (e.g., 'run_sequential_scans' accepting array of scan configs) to reduce token overhead when agents need to scan multiple targets. Baseline shows batch tools reduce multi-call token waste.
Ensure tool names clearly differentiate when semantically related. Current names are clear (nmap_scan vs gobuster_scan are distinct tools for different purposes). No change needed here.