/ 
Net-P0f-0.02
River stage zero No dependents
/ Net::P0f

NAME

Net::P0f - Perl wrapper for the P0f utility

VERSION

Version 0.02

SYNOPSIS

    use Net::P0f;

    my $p0f = Net::P0f->new(interface => 'eth0', promiscuous => 1);
    $p0f->loop(callback => \&process_packet);

    sub process_packet {
        # do stuff with packet information
	# see the documentation for more details
    }

DESCRIPTION

This module (and its associated helper modules) is a Perl interface to the P0f utility. P0f is a passive operating system fingerprinting: it identifies the operating system of network devices by passively looking at specific patterns in their TCP/IP packets. Therefore, contrary to others tools like Nmap, P0f does not send any packet and stays completly stealth. For more information on P0f, please see http://lcamtuf.coredump.cx/p0f.shtml

METHODS

Lookup methods

The following methods are class methods, which can of course also be used as object methods.

lookupdev()

Returns the name of a network device that can be used for operating.

Note: this function may require administrator privileges on some operating systems.

findalldevs()

Returns a list of all network devices that can be used for operating. If the corresponding fonction is not available in the version of Net::Pcap installed on the system (it appeared in version 0.05), it will print a warning and return the result of lookupdev().

Note: this function may require administrator privileges on some operating systems.

Packet analysis methods

new()

Create and returns a new objects. The following options are accepted.

Engine options

  • backend - selects the back-end. Accepted values are "cmd", "socket" and "xs" to select, respectively, the command line front-end, the socket version and the XS version. If not specified, defaults to "cmd".

  • chroot_as - chroot and setuid to this user. Accepted value is any valid user name. Default is not to chroot.

  • fingerprints_file - read fingerpints from the given file.

Input options

Only one the following options must be used.

  • interface - selects the network device. Accepted values are any interface name that the system can recognize. Remember that such names are usualy not portable. For example, you can check if the interface name belongs to the list returned by Net::P0f-findalldevs>.

  • dump_file - reads from the given dump file, as created by tcpdump(1) with the -w file option.

Detection options

  • detection_mode - selects the detection mode. Accepted values are 0 for the SYN mode, 1 for the SYN+ACK mode, and 2 for the RST+ACK mode. Default value is 0.

  • fuzzy - activates the fuzzy matching (do not combine with the RST+ACK detection mode). Value can be 0 (fuzzy matching disabled) or 1 (activated). Default value is 0.

  • promiscuous - switches the network device to promiscuous mode. Value can be 0 (normal mode) or 1 (promiscuous mode activated). Default value is 0.

  • filter - pcap-style BPF expression.

  • masquerade_detection - activates the masquerade detection. Value can be 0 (masquerade detection disabled) or 1 (enabled). Default value is 0.

  • masquerade_detection_threshold - sets the masquerade detection threshold. Value can be any integer between 1 and 200. Default value is 100.

  • resolve_names - activates the IP to names resolution. Value can be 0 (do not resolve names) or 1 (resolve names). Default value is 0.

Example

Common use under Linux:

my $p0f = new Net::P0f interface => 'eth0';

The same, in a more portable way:

my $p0f = new Net::P0f interface => Net::P0f->lookupdev;
loop()

This method launches the execution of the P0f engine.

Options

  • callback - sets the callback function that will be called for each received packets. This option is required. See "CALLBACK" for more information.

  • count - wait for this number of packets, then stop. If set to zero, run until a SIGINT signal is received. This option is required.

Example

# process 10 packets, giving them to the packet_handler() function
$p0f->loop(callback => \&packet_handler, count => 10);

CALLBACK

A callback function has the following signature:

    sub callback {
        my($self,$header,$os_info,$link_info) = @_;
	# do something ...
    }

where the parameters have the following meaning:

  • $self is the Net::P0f object

  • $header is a hashref with the following keys:

    • ip_src is the source IP address

    • name_src is the source DNS name (if any)

    • port_src is the source port

    • ip_dest is the destination IP address

    • name_dest is the destination DNS name (if any)

    • port_dest is the destination port

  • $os_info is a hashref with the following keys:

    • genre is the generic genre of the operating system (like "Linux" or "Windows")

    • details gives more information on the operating system, like its version

    • uptime indicates the uptime of the host

  • $link_info is a hashref with the following keys:

    • distance is the distance to the host

    • link_type is the type of the connection

SIGNALS

sighandler()

This function is a signal handler for the SIGINT, SIGTERM and SIGQUIT signals. Its main purpose is to tell all the instancied Net::P0f objects to cleanly stop their engine.

BACKENDS

Command-line version

XXX

Socket version

XXX

XS version

XXX

DIAGNOSTICS

These messages are classified as follows (listed in increasing order of desperation):

  • (W) A warning, usually caused by bad user data.

  • (E) An error caused by external code.

  • (F) A fatal error caused by the code of this module.

Both 'interface' and 'dump_file' have been set. 'dump_file' prevails.

(F) As the message says, you defined two input sources by setting both interface and dump_file.

Net::Pcap error: %s

(E) The Net::Pcap module returned the following error.

No input source was defined. Please set one of 'interface' or 'dump_file'.

(F) As the message says, you didn't define an input source by setting one of interface or dump_file before calling loop().

Option '%s' was not set.

(F) A mandatory option wasn't set, hence preventing the program to work.

This function is not available with this version of Net::Pcap

(W) As the message says, the function findalldevs() is not available. This is most probably because you have Net::Pcap version 0.04 or earlier, and Net::Pcap version 0.05 is needed.

Unknown option '%s'

(W) You called an accesor which does not correspond to a known option.

Unknown value for option 'backend': %s

(F) The value for the option "backend" was not given a valid value. This is a fatal error because this option is needed to build the object.

SEE ALSO

p0f(1)

Net::P0f::Backend::CmdFE, Net::P0f::Backend::Socket, Net::P0f::Backend::XS for backend specific details

Net::Pcap

AUTHOR

Sébastien Aperghis-Tramoni <sebastien@aperghis.net>

BUGS

Please report any bugs or feature requests to bug-net-p0f@rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-P0f. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2004 Sébastien Aperghis-Tramoni, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.