Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: A Loopback Port Scanner

Build a small TCP connect scanner in Node.js that scans only 127.0.0.1: open, closed and filtered logic, concurrency, timeouts and banner reading, to see how Nmap -sT works.

The best way to understand a port scanner is to build a tiny one. In this project you write a TCP connect scanner in Node.js. It does what nmap -sT does: it asks the operating system to connect to each port and records the answer. To keep everything safe and legal, the scanner is locked to 127.0.0.1, your own computer. The example starts its own servers so there is always something to find.

The scanner below refuses any address except 127.0.0.1. Do not remove that check to scan other computers. Scanning systems without permission can be illegal. See Legal and Ethical Scanning.

How a connect scan decides the state

The operating system's connect() call has three common outcomes:

What happens Meaning Nmap state
Connection succeeds A service is listening open
Connection refused (RST) Nothing is listening closed
No answer before the timeout A firewall dropped the probe filtered

On loopback there is no firewall, so you will mostly see open and closed. The timeout path exists so the scanner works on real networks too, and we will test it with a simulated slow target.

flowchart TD
    A["connect(host, port)"] --> B{"Result"}
    B -->|"connected"| O["open: read banner,<br/>close socket"]
    B -->|"ECONNREFUSED"| C["closed"]
    B -->|"timeout"| F["filtered"]

The three outcomes of a TCP connect probe.

Step 1: probe one port

The function below returns the state, and for open ports it waits briefly for a banner. It rejects non-loopback hosts at the start.

Step 2: scan a range with limited concurrency

Scanning ports one after another is slow. Opening thousands of sockets at once can exhaust resources. A small worker pool runs a limited number of probes at the same time. Here it is in full, together with a lab that starts three servers on loopback.

Node.js A loopback-only connect scanner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The output uses offsets from a base port, because the base is chosen by your operating system and changes each run. Open ports show their banner, closed ones were refused, and the guard rejects any other address.

Step 3: timeouts and the filtered state

On loopback nothing is filtered, so test the timeout logic with a simulated target. The function below imitates three kinds of ports with delays, using the same decision rules, without any networking.

Node.js Model of open, closed and filtered outcomes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

With the short timeout, port 8080 is reported as filtered even though it would have answered: exactly the accuracy loss discussed in Timing and Performance Tuning.

What real Nmap adds

Your scanner is a connect scan. Nmap's default SYN scan (-sS) sends the first packet of the handshake itself and never completes the connection, which is faster and leaves fewer log entries on the target application. It needs raw sockets and privileges, which Node's net module does not provide. Nmap also adds:

  • adaptive timing based on measured round-trip times and packet loss,
  • hundreds of ports in parallel with congestion control,
  • UDP and other scan types, IPv6, host discovery and OS fingerprinting,
  • service probes, scripts and many output formats.

Writing your own scanner remains valuable for learning and for small checks on your own hosts, such as "is my dev server listening on the right port".

Exercises

  1. Add a --ports argument parser that accepts 22,80,8000-8010.
  2. Show a count of closed ports instead of listing them, like Nmap's "Not shown: 990 closed".
  3. Add a JSON output option and compare it with the XML structure from Parsing XML Output.
  4. Make the scanner identify the three lab servers by matching the banner text, as in Banner Grabbing and Probes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does ECONNREFUSED tell the connect scanner?

    A refused connection means the target's stack answered with RST because no service listens on that port.
  2. 2. Why does the scanner use a worker pool?

    Sequential scanning is slow, unlimited concurrency can overload the machine or network. A fixed pool balances speed and safety.
  3. 3. What would a too-short timeout cause on a real network?

    If the reply arrives after the timeout, the scanner has already given up and marked the port filtered.
  4. 4. What is a SYN scan's main difference from the connect scan built here?

    Nmap -sS crafts packets and stops after the SYN/ACK. A normal program using connect() lets the OS complete the handshake.

Summary

  • A connect scan asks the OS to connect: success is open, refusal is closed, silence is filtered.
  • A worker pool gives speed with limited resources; timeouts balance speed against accuracy.
  • Lock teaching scanners to loopback, and never aim them at systems you may not test.
  • Nmap adds raw packets, adaptive timing, detection and scripting on top of this simple core.

Next: Project: A Scan Report