Bug Bounty MCP Server

Instructions

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
• src/rest_api_server/tools/nmap_advanced/nmap_advanced.py:102-146 (handler)

  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, }
• src/rest_api_server/tools/nmap_advanced/nmap_advanced.py:21-62 (helper)

  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)
• src/rest_api_server/tools/nmap_advanced/nmap_advanced.py:65-100 (helper)

  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