Automatically monitoring your home network

The Watcher

Article from Issue 169/2014
Author(s):

To discover possibly undesirable arrivals and departures on their networks, a Perl daemon periodically stores the data from Nmap scans and passes them on to Nagios via a built-in web interface.

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.

Listing 1

nmap-server

01 #!/usr/local/bin/perl -w
02 ###########################################
03 # nmap-server - Nmap scanning daemon
04 # Mike Schilli, 2014 (m@perlmeister.com)
05 ###########################################
06 use strict;
07 use NmapServer;
08 use App::Daemon qw( daemonize );
09
10 daemonize();
11
12 my $nmap = NmapServer->new(
13   scan_range =>
14     [ "192.168.14.1/24",
15       "192.168.27.1/24" ] );
16
17 $nmap->start();
18
19 my $cv = AnyEvent->condvar();
20 $cv->recv();

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.

Listing 2

NmapServer.pm

001 ###########################################
002 package NmapServer;
003 ###########################################
004 # Daemon running nmap periodically and
005 # serving JSON data via a web interface
006 # Mike Schilli, 2014 (m@perlmeister.com)
007 ###########################################
008 use strict;
009 use warnings;
010 use Log::Log4perl qw(:easy);
011 use AnyEvent;
012 use AnyEvent::HTTPD;
013 use JSON qw( to_json );
014 use File::Temp qw( tempfile );
015 use XML::Simple;
016
017 ###########################################
018 sub new {
019 ###########################################
020   my( $class, %options ) = @_;
021
022   my( $fh, $tmp_file ) =
023      tempfile( UNLINK => 1 );
024
025   my $self = {
026     xml_file   => $tmp_file,
027     fork       => undef,
028     json       => "",
029     child      => undef,
030     scan_range => [],
031     %options,
032   };
033
034   bless $self, $class;
035 }
036
037 ###########################################
038 sub start {
039 ###########################################
040   my( $self ) = @_;
041
042   $self->{ timer } = AnyEvent->timer(
043     after    => 0,
044     interval => 3600,
045     cb => sub {
046       if( defined $self->{ fork } ) {
047           DEBUG "nmap already running";
048           return 1;
049       }
050       $self->nmap_spawn();
051     },
052   );
053
054   $self->httpd_spawn();
055 }
056
057 ###########################################
058 sub nmap_spawn {
059 ###########################################
060   my( $self ) = @_;
061
062   $self->{ fork } = fork();
063
064   if( !defined $self->{ fork } ) {
065     LOGDIE "Waaaah, failed to fork!";
066   }
067
068   if( $self->{ fork } ) {
069       # parent
070     $self->{ child } = AnyEvent->child(
071       pid => $self->{ fork },
072       cb  => sub {
073         my $data =
074           XMLin( $self->{ xml_file });
075         $self->{ json } =
076          to_json( $data, { pretty => 1 } );
077         $self->{ fork } = undef;
078       } );
079   } else {
080       # child
081     exec "nmap", "-oX",
082       $self->{ xml_file },
083       @{ $self->{ scan_range } },
084   }
085 }
086
087 ###########################################
088 sub httpd_spawn {
089 ###########################################
090   my( $self ) = @_;
091
092   $self->{ httpd } =
093     AnyEvent::HTTPD->new( port => 9090 );
094
095   $self->{ httpd }->reg_cb (
096     '/' => sub {
097       my ($httpd, $req) = @_;
098
099       $req->respond({ content =>
100         ['text/json', $self->{ json } ],
101       });
102     },
103   );
104 }
105
106 1;

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.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy Linux Magazine

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Nmap Scripting

    Nmap is rolling out a new scripting engine to automatically investigate vulnerabilities that turn up in a security scan. We’ll show you how to protect your network with Nmap and NSE.

  • Nmap Workshop

    In "The Matrix Reloaded," Trinity uses Nmap to hack into the power grid to pave Neo's way to the architect of the virtual world. However, the port scanner is also ideal for more mundane purposes – such as discovering vulnerabilities in your domestic network.

  • Nmap Methods

    How does the popular Nmap scanner identify holes in network security? In this article, we examine some Nmap analysis techniques.

  • Charly's Column

    Many tools keep growing with each new version, but Nmap 4.00 has lost weight thanks to the Diet-Nmap project. The latest incarnation of Nmap is not only quicker, it is also more frugal with memory.

  • Nmap 4.75 recognizes iPhones and visualizes networks

    "If we are going to call Nmap the 'Network Mapper', it should at least be able to draw you a map of the network! " writes developer Fyodor in announcing the newest version 4.75 of the Nmap security scanner.

comments powered by Disqus

Direct Download

Read full article as PDF:

Price $2.95

News

njobs Europe
What:
Where:
Country:
Njobs Netherlands Njobs Deutschland Njobs United Kingdom Njobs Italia Njobs France Njobs Espana Njobs Poland
Njobs Austria Njobs Denmark Njobs Belgium Njobs Czech Republic Njobs Mexico Njobs India Njobs Colombia