operant-mcp

Instructions

Implementation Reference

• src/tools/pcap.ts:186-220 (handler)

  The 'pcap_detect_scan' tool is registered and implemented within 'src/tools/pcap.ts'. It uses tshark to count SYN packets (no ACK) per IP to identify potential port scanning activity.

  server.tool(
    "pcap_detect_scan",
    "Detect port scans by analyzing SYN packets without ACK. Returns scanners (ip + syn_count), top_scanned_ports, and a hint. Read-only file analysis.",
    {
      pcap_path: z.string().describe("Path to the PCAP file"),
    },
    async ({ pcap_path }) => {
      requireTool("tshark");
      const pcap = validatePcap(pcap_path);
  
      const synBySrc = await runShell(
        `tshark -r '${pcap}' -Y 'tcp.flags.syn == 1 && tcp.flags.ack == 0' -T fields -e ip.src 2>/dev/null | sort | uniq -c | sort -rn | head -20`
      );
  
      const topPorts = await runShell(
        `tshark -r '${pcap}' -Y 'tcp.flags.syn == 1 && tcp.flags.ack == 0' -T fields -e tcp.dstport 2>/dev/null | sort | uniq -c | sort -rn | head -30`
      );
  
      const scanners: Array<{ ip: string; syn_count: number }> = [];
      for (const line of parseLines(synBySrc.stdout)) {
        const parts = line.trim().split(/\s+/);
        if (parts.length >= 2) {
          scanners.push({ ip: parts[1], syn_count: parseInt(parts[0], 10) });
        }
      }
  
      const result = {
        scanners,
        top_scanned_ports: parseLines(topPorts.stdout).slice(0, 30),
        hint: "IPs with >100 SYN packets are likely scanning. Check top ports for targeted services.",
      };
  
      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
    }
  );