Building a High Performance Port Scanner with Golang

I've written about building a port scanner several times before; and this implementation is the fastest one I've been able to create thus far. Utilizing the multi-threaded runtime and the baked-in concurrency model provided by Golang, asynchronous I/O performance is just beautiful.👌

What does that end up looking like to actually code, and how fast does it go?

📦 Assembling our Package

Like any other language, we'll pull in some libraries that have encapsulated the stuff we're interested in orchestrating into a useful program.

In the world of Golang, we'll import a bunch of packages — and at the very top of our script, we'll declare it as our "main" package.

package main

import (
    "context"
    "fmt"
    "net"
    "os/exec"
    "strconv"
    "strings"
    "sync"
    "time"
    "golang.org/x/sync/semaphore"
)
// more code ...

Unlike object-orientated languages, there's no concept of a class wherein we add methods inside of. Instead, we can just attach functions to any type, ultimately giving us a method.

So, let's make a type called PortScanner which will be struct type containing two fields: ip and lock.

type PortScanner struct {
    ip   string
    lock *semaphore.Weighted
}

The ip will be the IP address of the host on the network we're interested in scanning. The lock will act as a threshold that will limit the number of go routines that will be running at any given time.

To set our lock based on the limits of the operating system, we may opt to use the value of the ulimit command. This can be captured to be parsed using the os/exec package.

To abstract that whole process away of getting the value from the command-line, I decided to put it in a function called Ulimit.

func Ulimit() int64 {
    out, err := exec.Command("ulimit", "-n").Output()
    if err != nil {
        panic(err)
    }
    s := strings.TrimSpace(string(out))
    i, err := strconv.ParseInt(s, 10, 64)
    
    if err != nil {
        panic(err)
    }
    return i
}

Since we're building a port scanner, we're going to need another function that can actually, ya' know, scan the port. The net package includes a convenient method to make a connection with an allotted timeout value.

func ScanPort(ip string, port int, timeout time.Duration) {
    target := fmt.Sprintf("%s:%d", ip, port)
    conn, err := net.DialTimeout("tcp", target, timeout)
    
    if err != nil {
        if strings.Contains(err.Error(), "too many open files") {
            time.Sleep(timeout)
            ScanPort(ip, port, timeout)
        } else {
            fmt.Println(port, "closed")
        }
        return
    }
    
    conn.Close()
    fmt.Println(port, "open")
}

As you probably noticed, most of the ScanPort function deals with the err from net.DialTimeout. This is because, as with any port scanner, we have some errors to juggle:

🤹🏻‍♂️ Three Essential Errors to Juggle:

Based on the result of the error for the connection attempt, if the attempt failed as a result of too many files being open on the system, we'll delay the execution of that port scan. Once the delay returns, we can again retry it until the connections fails because of a timeout or, better yet, a successful connection.

To use the ScanPort method for a range of ports, we'll implement a method on the PortScanner struct that will scan a given range of ports (from the first f to the last one l) along with a Duration to use as a timeout. We'll call this function Start, as it will kick-off the actual connection attempts later on.

func (ps *PortScanner) Start(f, l int, timeout time.Duration) {
    wg := sync.WaitGroup{}
    defer wg.Wait()
    
    for port := f; port <= l; port++ {       
        wg.Add(1)
        ps.lock.Acquire(context.TODO(), 1)
        go func(port int) {
            defer ps.lock.Release(1)
            defer wg.Done()
            ScanPort(ps.ip, port, timeout)
        }(port)
    }
}

Limiting Go Routines for Performance

While it is be easy to just spawn off a new go routine for every connection attempt, this isn't the most efficient way of utilizing our computer's resources. Instead, it's much better to bound our connections attempts to a set size based on our shell's limits. The lock in our port scanner "locks down" the concurrent connection attempts, and thus wastes significantly less time by not trying to exceed its threshold.

The Main Function

All that's left is to write our program's main function to use the code we just implemented to scan all of the ports on our local host.

func main() {
    ps := &PortScanner{
        ip:   "127.0.0.1",
        lock: semaphore.NewWeighted(Ulimit()),
    }
    ps.Start(1, 65535, 500*time.Millisecond)
}

🔨 Compiling the Program

Compiling our port scanner is as trivial as running the following command:

$ go build port_scanner.go

Which provides us with a binary which we can execute to perform our port scan now:

$ ./port_scanner

But, how fast does it go? Let's use the time command on unix-like systems to give us a quick benchmark for an idea:

$ time ./port_scanner
...
real    0m31.384s
user    0m4.766s
sys     0m7.653s

Let's do the math on that: 65535 ports / 31 seconds is about 2000 ports a second. That's incredibly fast, and 2x faster than the single-threaded Ruby version I've made before! 🚀

📃 Source Code

Below is the full source code for the scanner (copy+paste friendly for testing):

package main

import (
    "context"
    "fmt"
    "net"
    "os/exec"
    "strconv"
    "strings"
    "sync"
    "time"
    "golang.org/x/sync/semaphore"
)

type PortScanner struct {
    ip   string
    lock *semaphore.Weighted
}

func Ulimit() int64 {
    out, err := exec.Command("ulimit", "-n").Output()
    if err != nil {
        panic(err)
    }
    s := strings.TrimSpace(string(out))
    i, err := strconv.ParseInt(s, 10, 64)
    
    if err != nil {
        panic(err)
    }
    return i
}

func ScanPort(ip string, port int, timeout time.Duration) {
    target := fmt.Sprintf("%s:%d", ip, port)
    conn, err := net.DialTimeout("tcp", target, timeout)
    
    if err != nil {
        if strings.Contains(err.Error(), "too many open files") {
            time.Sleep(timeout)
            ScanPort(ip, port, timeout)
        } else {
            fmt.Println(port, "closed")
        }
        return
    }
    
    conn.Close()
    fmt.Println(port, "open")
}

func (ps *PortScanner) Start(f, l int, timeout time.Duration) {
    wg := sync.WaitGroup{}
    defer wg.Wait()
    
    for port := f; port <= l; port++ {       
        wg.Add(1)
        ps.lock.Acquire(context.TODO(), 1)
        go func(port int) {
            defer ps.lock.Release(1)
            defer wg.Done()
            ScanPort(ps.ip, port, timeout)
        }(port)
    }
}

func main() {
    ps := &PortScanner{
        ip:   "127.0.0.1",
        lock: semaphore.NewWeighted(Ulimit()),
    }
    ps.Start(1, 65535, 500*time.Millisecond)
}

👋 Conclusion

The multi-threaded runtime in Golang coupled with an asynchronous design allows for some incredible performance for a simple port scanner. Feel free to hack on it some more or let me know where it could be improved.

Until next time, that's all folks!