nmap_advanced_scan
Execute comprehensive network reconnaissance scans to identify open ports, services, and vulnerabilities for security assessments and penetration testing.
Instructions
Execute advanced Nmap scan with comprehensive options for bug bounty hunting.
Args: target: Target IP or hostname scan_type: Scan technique (-sS, -sT, -sU, etc.) ports: Port specification timing: Timing template (-T0 to -T5) scripts: NSE scripts to run os_detection: Enable OS detection service_detection: Enable service version detection aggressive: Enable aggressive scan mode stealth: Enable stealth scan options additional_args: Additional arguments
Returns: Advanced scan results
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| additional_args | No | ||
| aggressive | No | ||
| os_detection | No | ||
| ports | No | ||
| scan_type | No | -sS | |
| scripts | No | ||
| service_detection | No | ||
| stealth | No | ||
| target | Yes | ||
| timing | No | -T4 |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/mcp_server/app.py:191-242 (handler)Primary MCP handler and registration for the 'nmap_advanced_scan' tool. Defines the tool schema via function signature and proxies execution to the REST API backend.
@mcp.tool() def nmap_advanced_scan( target: str, scan_type: str = "-sS", ports: str = "", timing: str = "-T4", scripts: str = "", os_detection: bool = False, service_detection: bool = True, aggressive: bool = False, stealth: bool = False, additional_args: str = "", ) -> dict[str, Any]: """Execute advanced Nmap scan with comprehensive options for bug bounty hunting. Args: target: Target IP or hostname scan_type: Scan technique (-sS, -sT, -sU, etc.) ports: Port specification timing: Timing template (-T0 to -T5) scripts: NSE scripts to run os_detection: Enable OS detection service_detection: Enable service version detection aggressive: Enable aggressive scan mode stealth: Enable stealth scan options additional_args: Additional arguments Returns: Advanced scan results """ data = { "target": target, "scan_type": scan_type, "ports": ports, "timing": timing, "scripts": scripts, "os_detection": os_detection, "service_detection": service_detection, "aggressive": aggressive, "stealth": stealth, "additional_args": additional_args, } logger.info(f"🎯 Starting advanced Nmap scan on {target}") result = api_client.safe_post("api/nmap-advanced", data) if result.get("success"): logger.info(f"✅ Advanced Nmap scan completed on {target}") else: logger.error("❌ Advanced Nmap scan failed") return result - Backend REST API handler 'execute_nmap_advanced' for nmap-advanced tool, implementing the core Nmap execution, command construction, output parsing, and finding extraction.
@tool(name="nmap-advanced", required_fields=["target"]) def execute_nmap_advanced(): """Execute advanced Nmap scans with clean structured output.""" data = request.get_json() logger.info("Executing advanced Nmap scan on %s", data["target"]) scan_type = data.get("scan_type", "-sS").strip() if scan_type == "-sS" and not os.geteuid() == 0: data["scan_type"] = "-sT" logger.info("Switched to -sT due to non-root privileges") command = _build_nmap_advanced_command(data) execution_result = execute_command(command, timeout=1800) if not execution_result["success"]: error_message = ( execution_result.get("stderr") or execution_result.get("error") or "Nmap execution failed" ) error_response, status_code = create_error_response( error_message, stage="exec", details={ "return_code": execution_result.get("return_code"), "command": execution_result.get("command", command), }, status_code=500, ) return jsonify(error_response), status_code stdout = execution_result.get("stdout", "") with open("/tmp/nmap_advanced_raw_output.log", "w") as f: f.write(stdout) findings, duplicates = _collect_findings(stdout) stats = create_stats( len(findings), duplicates, len(stdout.encode("utf-8")), ) return { "findings": findings, "stats": stats, } - Helper function to construct the Nmap command line based on advanced scan parameters.
def _build_nmap_advanced_command(params: dict[str, Any]) -> str: cmd_parts: list[str] = ["nmap"] scan_type = params.get("scan_type", "-sS").strip() if scan_type: cmd_parts.extend(scan_type.split()) ports = params.get("ports", "").strip() if ports: cmd_parts.extend(["-p", ports]) if params.get("stealth", False): cmd_parts.extend(["-T2", "-f", "--mtu", "24"]) else: timing = params.get("timing", "T4").lstrip("-") if timing: cmd_parts.append(f"-{timing}") if params.get("os_detection", False): cmd_parts.append("-O") if params.get("service_detection", True) or params.get("version_detection", False): cmd_parts.append("-sV") if params.get("aggressive", False): cmd_parts.append("-A") script_param = params.get("nse_scripts") or params.get("scripts") if script_param: cmd_parts.extend(["--script", script_param]) elif not params.get("aggressive", False): cmd_parts.extend(["--script", "default,discovery,safe"]) cmd_parts.extend(["-oX", "-"]) additional_args = params.get("additional_args", "") if additional_args: cmd_parts.extend(shlex.split(additional_args)) cmd_parts.append(params["target"]) return " ".join(shlex.quote(part) for part in cmd_parts) - Helper function to parse Nmap XML output, deduplicate findings, and standardize evidence and tags.
def _collect_findings(stdout: str) -> tuple[list[dict[str, Any]], int]: findings = parse_nmap_output(stdout) duplicates = 0 unique: list[dict[str, Any]] = [] seen: set[tuple[str, Any, Any]] = set() for finding in findings: if finding["type"] == "port": key = ( finding["target"], finding["evidence"].get("port"), finding["evidence"].get("protocol"), ) else: key = (finding["type"], finding["target"], None) if key in seen: duplicates += 1 continue seen.add(key) evidence = finding.get("evidence", {}) evidence["discovered_by"] = "nmap-advanced" finding["evidence"] = evidence tags = finding.get("tags", []) if "nmap-advanced" not in tags: tags.append("nmap-advanced") finding["tags"] = tags unique.append(finding) return unique, duplicates - src/rest_api_server/tools/__init__.py:21-22 (registration)Import registration that triggers auto-registration of the nmap_advanced tool handler via the @tool decorator.
from .nmap import nmap as nmap from .nmap_advanced import nmap_advanced as nmap_advanced