nmap_scan

Instructions

Implementation Reference

• src/index.ts:547-631 (handler)

  Handler for the nmap_scan tool. Validates inputs, checks nmap availability, builds nmap command arguments based on scan type, executes db_nmap via msfconsole to scan target and import results into Metasploit database.

  case "nmap_scan": {
    const { target, ports, scanType } = args as {
      target: string;
      ports?: string;
      scanType?: string;
    };
  
    const nmapAvailable = await checkNmapAvailable();
    if (!nmapAvailable) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              success: false,
              error: "nmap not found. Please install nmap.",
              hint: process.platform === "win32"
                ? "Download nmap from https://nmap.org/"
                : "Install with: sudo apt-get install nmap",
            }),
          },
        ],
      };
    }
  
    let nmapArgs: string[] = [];
  
    switch (scanType) {
      case "quick":
        nmapArgs.push("-F");
        break;
      case "stealth":
        nmapArgs.push("-sS");
        break;
      case "full":
        nmapArgs.push("-sV", "-sC");
        break;
      case "udp":
        nmapArgs.push("-sU");
        break;
    }
  
    if (ports) {
      nmapArgs.push("-p", ports);
    }
  
    nmapArgs.push(target);
  
    // Run nmap through msfconsole to automatically import results
    const dbNmapCommand = `db_nmap ${nmapArgs.join(" ")}`;
  
    try {
      const results = await executeMsfCommand([dbNmapCommand]);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                success: true,
                target,
                ports: ports || "default",
                scanType: scanType || "quick",
                results,
              },
              null,
              2
            ),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              success: false,
              error: error.message,
            }),
          },
        ],
      };
    }
  }

• src/index.ts:182-201 (schema)

  Input schema for nmap_scan tool defining parameters: target (required), ports (optional), scanType (optional with enum).

  inputSchema: {
    type: "object",
    properties: {
      target: {
        type: "string",
        description: "Target IP address or CIDR range",
      },
      ports: {
        type: "string",
        description: "Optional: port range or specific ports (e.g., '80,443' or '1-1000')",
      },
      scanType: {
        type: "string",
        enum: ["quick", "stealth", "full", "udp"],
        description: "Optional: type of scan to perform",
        default: "quick",
      },
    },
    required: ["target"],
  },

• src/index.ts:179-202 (registration)

  Registration of the nmap_scan tool in the MCP tools array, including name, description, and input schema.

  {
    name: "nmap_scan",
    description: "Run an nmap scan and import results into Metasploit database",
    inputSchema: {
      type: "object",
      properties: {
        target: {
          type: "string",
          description: "Target IP address or CIDR range",
        },
        ports: {
          type: "string",
          description: "Optional: port range or specific ports (e.g., '80,443' or '1-1000')",
        },
        scanType: {
          type: "string",
          enum: ["quick", "stealth", "full", "udp"],
          description: "Optional: type of scan to perform",
          default: "quick",
        },
      },
      required: ["target"],
    },
  },

• src/index.ts:56-67 (helper)

  Helper function specifically used by nmap_scan to verify nmap is installed and available on the system.

  // Check if nmap is available
  async function checkNmapAvailable(): Promise<boolean> {
    try {
      if (process.platform === "win32") {
        await execAsync("where nmap");
      } else {
        await execAsync("which nmap");
      }
      return true;
    } catch {
      return false;
    }