ullaakut/nmap Go Library

Use nmap.NewScanner with functional options to configure your scan, then call scanner.Run(ctx) to execute it synchronously. This method blocks until the scan is complete or the context is canceled.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/Ullaakut/nmap/v4"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()

	// Equivalent to `/usr/local/bin/nmap -p 80,443,843 google.com facebook.com youtube.com`,
	// with a 5-minute timeout.
	scanner, err := nmap.NewScanner(
		nmap.WithTargets("scanme.nmap.org"),
		nmap.WithPorts("80,443,843"),
	)
	if err != nil {
		log.Fatalf("creating nmap scanner: %v", err)
	}

	result, err := scanner.Run(ctx)
	if err != nil {
		log.Fatalf("running network scan: %v", err)
	}

	warnings := result.Warnings()
	if len(warnings) > 0 {
		log.Printf("warning: %v\n", warnings) // Warnings are non-critical errors from nmap.
	}

	// Use the results to print an example output
	for _, host := range result.Hosts {
		if len(host.Ports) == 0 || len(host.Addresses) == 0 {
			continue
		}

		fmt.Printf("Host %q:\n", host.Addresses[0])

		for _, port := range host.Ports {
			fmt.Printf("\tPort %d/%s %s %s\n", port.ID, port.Protocol, port.State, port.Service.Name)
		}
	}

	fmt.Printf("Nmap done: %d hosts up scanned in %.2f seconds\n", len(result.Hosts), result.Stats.Finished.Elapsed)
}

You can monitor scan progress using nmap.WithProgress(interval, callback).

Important Notes:

• This feature relies on terminal escape sequences and only works when the process is attached to a TTY.
• Progress is not guaranteed to increase monotonically; nmap may revise its time estimates, causing the reported percentage to decrease.

package main

import (
	"context"
	"log"
	"time"

	"github.com/Ullaakut/nmap/v4"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	defer cancel()

	scanner, err := nmap.NewScanner(
		nmap.WithTargets("scanme.nmap.org"),
		nmap.WithPorts("1-1024"),
		nmap.WithTimingTemplate(nmap.TimingAggressive),
		nmap.WithProgress(time.Second, handleProgress),
	)
	if err != nil {
		log.Fatalf("creating nmap scanner: %v", err)
	}

	_, err = scanner.Run(ctx)
	if err != nil {
		log.Fatalf("running network scan: %v", err)
	}
}

func handleProgress(p nmap.TaskProgress) {
	log.Println("Current progress: ", p.Percent)
}

For non-blocking scans, use scanner.RunAsync(ctx). This returns four channels: stdout, stderr, resultCh, and an err value. You can use a select statement to process real-time output from nmap while waiting for the final result.

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/Ullaakut/nmap/v4"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
	defer cancel()

	scanner, err := nmap.NewScanner(
		nmap.WithTargets("scanme.nmap.org"),
		nmap.WithPorts("1-1024"),
	)
	if err != nil {
		log.Fatalf("creating nmap scanner: %v", err)
	}

	stdout, stderr, resultCh, err := scanner.RunAsync(ctx)
	if err != nil {
		log.Fatalf("running network scan: %v", err)
	}

	for {
		select {
		case <-ctx.Done():
			log.Fatalf("scan timed out: %v", ctx.Err())
		case out := <-stdout:
			fmt.Printf("nmap output: %s\n", out)
		case errOut := <-stderr:
			fmt.Printf("nmap error output: %s\n", errOut)
		case result := <-resultCh:
			if result.Err != nil {
				log.Fatalf("running network scan: %v", result.Err)
			}

			fmt.Printf("Nmap done: %d hosts up\n", len(result.Result.Hosts))
			return
		}
	}
}