mmaraya / ipforensics

PCAP-based IPv6 migration reporting tool

ipforensics

ipforensics is a network administration utility that conducts a passive inventory of IPv4 and IPv6 devices on your local network segment by either capturing live packets off the network or reading previously recorded packet capture files. It can be used to perform passive network enumeration and assist in IPv4 to IPv6 migrations by displaying the number of network devices detected that have only IPv4, have only IPv6 or are dual-stacked IPv4 and IPv6.

Supported Platforms

ipforensics runs under Linux, Mac OS X, and Windows.

Download

Precompiled binaries for the latest version of ipforensics can be downloaded from https://github.com/mmaraya/ipforensics/releases/tag/v1.0.

Usage

ipforensics [-hv] [-d device] [-f filename] [-n packets]
-h: display usage
-v: verbose display
-i interface: packet capture device to use (admin needed)
-c count: number of packets to read or capture
-r in file: read packets from pcap file
-w out file: write summary report to file, or append if the file exists

To read all packets from a pcap file named mycap.cap, use:

ipforensics -r mycap.cap

To read the first 100 packets from a pcap file named mycap.cap, use:

ipforensics -r mycap.cap -c 100

To read the first 250 packets from network device eth0, use:

sudo ipforensics -i eth0 -c 250

To read the first 125 packets from network device eth0 and write or append results to out.txt, use:

sudo ipforensics -i eth0 -c 125 -w out.txt

Sample Output

MAC Address       IPv4 Address    IPv6 Address
================= =============== =======================================
00:23:be:bf:22:ec 192.168.1.102
00:25:00:ef:54:69 192.168.1.4
00:26:bb:21:ad:40 192.168.1.9     fe80::226:bbff:fe21:ad40
00:7f:28:cf:e9:19 108.160.163.43
6c:c2:6b:22:89:c3 192.168.1.2
a4:d1:d2:3e:31:f8 192.168.1.6     fe80::841:557d:84c6:a048
ac:16:2d:bd:36:ec 192.168.1.12    fe80::ae16:2dff:febd:36ec
dc:2b:61:69:51:e0 192.168.1.3     fe80::104e:a2c9:540:5ba2
f4:5f:d4:34:a5:ee 192.168.1.100
=========================================================================
Hosts: 9; IPv4 only: 5; IPv6 only: 0; dual-stack: 4; migrated: 44%

License

Please see the file named LICENSE.

Issues

Please submit questions, comments, bugs, enhancement requests at https://github.com/mmaraya/ipforensics/issues.

Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ipforensics's Issues

Write results to a user-specified filename

Add a "-w filename" option to the command-line arguments and write the host summary report to the file. If the file already exists, return an error before reading any packets. The ability to append results to an existing file will be covered in another issue under this milestone.

Coverity 48513 Uninitialized scalar variable

The initial Coverity scan reveals the following:
48513 Uninitialized scalar variable
The variable will contain an arbitrary value left from earlier computations.
In IPForensics::​load_from_device(): Use of an uninitialized variable CWE-457.

ipforensics/src/ip4and6.cpp

Line 311 in f1bb5f0

load_hosts(device);

Append results if user-specified output file exists

If the "-w filename" command-line option specifies a file that exists, perform the following steps:

1. verify read/write permissions on the file
2. read the file to see if it is a valid ipforensics output file
3. load host information from the file into memory
4. read or capture packets
5. replace the contents of the output file in its entirety using the existing output mechanism

std::regex not fully implemented in gcc 4.8

Running the program under Ubuntu 14.04 with gcc 4.8.2 returns a std::regex_error. Upon further investigation, it appears that gcc will not fully support c++ regex until version 4.9. In order to preserve cross-platform compatibility for ipforensics until gcc 4.9 is released, a different method for determining whether an output file is valid or not is needed. The code in question can be found in:
https://github.com/mmaraya/ipforensics/blob/master/src/ip46file.cpp#L58
The regular expression being used can be found in https://github.com/mmaraya/ipforensics/blob/master/include/ipforensics/ip4and6.h#L335-336

Packets from network capture device are not being stored or displayed

libpcap appears to be reading packets but the packets aren't being stored or displayed

Coverity 48512 Not restoring ostream format

CID 48512 (#1 of 1): Not restoring ostream format (STREAM_FORMAT_STATE)

1. format_changed: hex changes the format state of out for category base field. (packet.cpp:122)
2. format_changed: setfill changes the format state of out for category fill. (packet.cpp:122)
3. end_of_path: Changing format state of stream out for categories basefield, fill without later restoring it. (packet.cpp:134)

48512 Not restoring ostream format
The next output operation may not expect the stream format state being altered, resulting in incorrectly formatted output.
In operator <<(std::​basic_ostream<char, std::​char_traits> &, Packet const&): Not restoring the stream format state of an ostream

Coverity 48514 Uninitialized scalar field

48514 Uninitialized scalar field
The field will contain an arbitrary value left over from earlier computations.
In Device::​Device(IPForensics *): A scalar field is not initialized by the constructor (CWE-457)

CID 48514 (#1 of 1): Uninitialized scalar field (UNINIT_CTOR)
2. uninit_member: Non-static class member loopback_ is not initialized in this constructor nor in any functions that it calls.

device.cpp:37

Add continuous integration for Windows builds

Consider using http://www.appveyor.com for Windows builds.

Add flag to ignore local-link IPv6 addresses

Add a command-line argument to ignore any local-link IPv6 addresses.

Coverity 19674 Uncaught exception

19674 Uncaught exception
If the exception is ever thrown, the program will crash.
In main: A C++ exception is thrown but never caught (CWE-248)

CID 19674 (#2-1 of 2): Uncaught exception (UNCAUGHT_EXCEPT)
root_function: In function main(int, char **) an exception of type std::runtime_error is thrown and never caught.

main.cpp:42

Network address and mask for packet capture

When reading packets from a packet capture file, allow the user to provide command-line parameters for IPv4 network address and mask so we can remove broadcast and multicast hosts from the output.

Malformed command-line parameters produce a runtime error

bin/ipforensics -c produces the following error instead of providing a useful message

libc++abi.dylib: terminating with uncaught exception of type std::runtime_error: : 
No such device exists (BIOCSETIF failed: Device not configured)

Coverity 48511 Not restoring ostream format

CID 48511 (#1 of 1): Not restoring ostream format (STREAM_FORMAT_STATE)

1. format_changed: left changes the format state of out for category adjust field. (host.cpp:118)
2. end_of_path: Changing format state of stream out for category adjustfield without later restoring it. (host.cpp:122)

48511 Not restoring ostream format
The next output operation may not expect the stream format state being altered, resulting in incorrectly formatted output.
In operator <<(std::​basic_ostream<char, std::​char_traits> &, Host const&): Not restoring the stream format state of an ostream

MAC address exclusion

A network administrator may want to exempt some hosts from an IPv4 to IPv6 migration and not count them towards their migration percentage. Add a command-line parameter, "-x filename" where filename contains a list of MAC addresses to exclude delimited by a comma, space, carriage return, line feed, etc. The program should be able to determine the delimiter from the contents of the exclusion file.

Coverity 48510 Dereference before null check

CID 48510 (#1 of 1): Dereference before null check (REVERSE_INULL)
check_after_deref: Null-checking this->ip_ suggests that it may be null, but it has already been dereferenced on all paths leading to the check.

48510 Dereference before null check
There may be a null pointer dereference, or else the comparison against null is unnecessary.
In IP46File::​valid(): All paths that lead to this null pointer comparison already dereference the pointer earlier (CWE-476)

ip46file.cpp:45

Display non-local link IPv6 if multiple addresses

If a node has multiple IPv6 addresses, display the non-local link address in the report