The practical Nmap network scanner is used not only by the bad boys in exciting thrillers to detect intrusion targets [1], it also tells admins what devices are actually reachable on their home networks. If you regularly launch Nmap on your subnets and compare the output, you can keep track of newly added or removed devices and proactively ward off nasty surprises.

The fact that nmap has a -oX option that tells it to output the results in XML format is something I was unaware of until I read an Nmap manual that was recently released as a Kindle book [2]. Because an Nmap scan across multiple networks can take a few minutes, I got the idea of building a daemon that finds all the nodes once an hour, keeps the data in memory, and sends it via a built-in web server to requesting clients, such as a Nagios script.

Lean Script Defines the Search Space

The script in Listing 1 [3] does this, mainly by resorting to the NmapServer module (which is loaded in line 7 and discussed later on) and its start() method. Before the call, it defines the IP range of the home network that nmap needs to scan in the constructor – in this case the subnets are 192.168.14.x and 192.168.27.x.

The /24 notation in the listing indicates that the first three octets (24 bits) define the network mask of the subnet to be scanned. The prepended 1 will later be replaced by Nmap, which substitutes all possible values from 1 through 254. The CPAN App::Daemon module provides the daemonize() method to launch the script with the start parameter:

./nmap-server start

Everything in the script below daemonize() then runs indefinitely in the background after this, although the script returns immediately, and the shell shows the user the next prompt. Even if the user logs out, the daemon will continue undeterred, because – behind the scenes  – the App::Daemon module has ensured that the script is its own session leader and thus also no longer depends on the calling shell. To shut down the daemon, just type

./nmap-server stop

in the same directory because the App::Daemon module stores the process ID (PID) of the daemon process in the nmap-server.pid file.

To discover what the daemon is doing, you can check out the logfile (nmap-server.log); the verbose option -v  on the start command additionally sends the debug messages to the same file. If you want to run the daemon in the foreground, call the script with the -X option, just like an Apache Server.

Events in Loops

The NmapServer module in Listing 2 is implemented with the AnyEvent event framework from CPAN, which usually only runs one thread and one process at any given time, although tasks can run concurrently via collaborative multitasking. The program flow is asynchronous; the various parts of the program only run in a quasi-parallel mode, and they generate and consume the events that an all-controlling event loop manages.

The last two lines in Listing 1 are thus just an AnyEvent gimmick. They use condvar() to define a variable, which relies on recv() to wait for events. Because nobody sends the variable an event, however, the script waits at the end, branches to the event loop, and keeps processing incoming events when it gets there, until someone shuts down the daemon. If the last two lines were missing in nmap-server, the script would say goodbye after line 17 – when the $nmap variable is snapped up by the garbage collector because it has reached the end of its scope in the program.

The NmapServer.pm module in Listing 2 starts an AnyEvent::timer type timer to call the nmap program on an hourly basis, stores its output in a temporary XML file created by File::Temp, then snaps it up from there and keeps it in memory in JSON format.

Virtually in parallel, a web server of the AnyEvent::HTTPD type runs in the code; it is listening on port 9090 and transmits JSON data to requesting clients. Figure 1 shows what happens if a browser connects to it; the display area shows the detailed scan data of the last Nmap run in JSON format.

Figure 1: The JSON output of the Nmap daemon.

Because the external nmap program refuses to cooperate with AnyEvent's event loop and would therefore temporarily halt the server's operations while running, line 62 uses a fork() command to create a child process, which AnyEvent manages in line 70 using the child() method. If the child successfully completes, which means that the nmap run was also successfully completed; the script then jumps to the callback code defined in lines 72-78, processes the XML, and converts it to JSON.

To refresh the internal cache, the code does not even need to set a lock, because it is only running one thread and every assignment is atomic, even if it's a huge mess of data that gets copied. Because the event loop can't take control while this is happening, no other AnyEvent tasks are served in the meantime.

The child process only uses exec() to run the external Nmap program in line 81 and then terminates. By definition, the parent process never returns from its exec()statement, except when something goes wrong with the call.

Built-In Web Server

Because the after parameter is set to a value of 0, the timer in line 42 starts immediately and kicks in again at hourly intervals after the first Nmap scanner run (interval is set to 3600). It is important to store the returned timer reference in an instance variable of the NmapServer object; otherwise, the timer would immediately die after the program flow left the method.

The web server defined in the httpd_spawn function starting in line 88 is listening on port 9090 and keeps running, ticking along with the timer in the event loop. It keeps delivering the JSON data stored in memory on request from web clients, asking for the / path. AnyEvent can run a whole bunch of components  – servers listening on ports or clients accessing the network in the same script  – and let them communicate with one another as well, all in one thread and one process only.