domap

Domain map

Overview

Program uses the linux utility nmap to collect data about the local domain, and help identify serives that have gone off-line or new services that have started on the local network.

It can either display the list of current services to the screen or email the list to a selected email account. It is expected usually to be run as a ron job and mail its output.

The mail header includes an MD5 hash of the output. This is to make it easy to quickly identiofy when the output changes, without having to make a detailed search of the output only to determine that no change has occured. If a change does occur, then one might run a difference program to on the output to determine exactly where the differences are.

When the program is running in background (detached from any terminal) then the progress messages are sent to the syslog.

The program only supports IPv4 addresses and will not look at IPv6 addresses.

Execution

The command formats are:

domap.rb show

This will display the map to the screen (or whatever is attached to STDOUT)

domap.rb mail <email address>

This will cause the output to be emailed to the address specified in the <email address>

Environment

Operating system

This application only works on the Linux operating system.

Required system utilities

The following linux system utilities are required to be installed (and available in the PATH) for the application run:

• nmap
• ip

And, since the application is written in ruby you will also need to install a ruby interpreter.

Required gems

The following ruby gems are required to be installed for the application run:

• json
• xmlsimple
• net/smtp
• net/ping
• yaml
• digest
• syslog
• socket
• pathname
• ipaddr
• resolv
• etc

Output

The output is a YAML file that will be sent in an email (or displayed on the screen).

The following is an example of a possible output:

---
start_time: 2021-06-17 23:05:35.800808128 Z
finish_time: 2021-06-17 23:09:14.670143078 Z
elapsed_time: '00:03:38'
ip_count: 3
pings:
    up: 2
    down: 1
port_count: 3
dns:
- 192.168.1.10
hash: wzrUUzasznK8iVVVSqr8/g
ip_address:
    192.168.1.10:
      mac:
      - b8:27:eb:96:16:c4
      names:
      - dns1.sample
      ping_ok: true
      ports:
        22:
          portid: '22'
          protocol: tcp
          service:
            cpe:
            - cpe:/a:openbsd:openssh:7.9p1
            - cpe:/o:linux:linux_kernel
            extrainfo: protocol 2.0
            name: ssh
            ostype: Linux
            product: OpenSSH
            version: 7.9p1 Raspbian 10+deb10u2+rpt1
          state: open
        53:
          portid: '53'
          protocol: tcp
          service:
            cpe:
            - cpe:/a:thekelleys:dnsmasq:2.80
            name: domain
            product: dnsmasq
            version: '2.80'
          state: open
      prefix_len: 24
    192.168.1.101:
      mac:
      - ac:84:c6:2f:51:2b
      names:
      - router1.sample
      ping_ok: true
      ports:
        80:
          portid: '80'
          protocol: tcp
          service:
            cpe:
            - cpe:/h:tp-link:td-w8968
            devicetype: WAP
            name: http
            product: TP-LINK TD-W8968 http admin
          state: open
      prefix_len: 24
    192.168.122.181:
      mac:
      - 52:55:80:26:17:9a
      ping_ok: false
      prefix_len:

The hash value (which, if the report is emailed, will be included on the subject line o the emil) is a hash created to be able to quickly identify if two runs have the same output. Thus, if you know that the first run is correct, and the second run has the same hash, then you can be sure that the second run was also correct without having to investigate further.

If you do need to investigate a change in the local network, the output will always list items in the same order, so you can quickly use a diff style utility to search line by line to see which item has changed.

Most changes detected will either be:
1. a temporary blip (e.g. in the example above, the third mac address cannot be pinged, even though a mac address can be determined for it - this will almost certainly correct itself on the next run).
2. an upgrade of the software on the server (e.g. the dns server is using dnsmasq version 2.0, but if this the server is upgraded to dnsmasq version 2.1 then this will cause a change in the report).