NAME

Fwctl::Report - Generates reports from fwctllog output.

SYNOPSIS

    use Fwctl::Report;

    my $report = new Fwctl::Report( options ... );

    my $src_alias_sum = $report->src_alias_summary_report;

    foreach my $r ( @$src_alias_sum ) {
        print $r->{host_ip}, " = ", $r->{count}, "\n";
    }

DESCRIPTION

The Fwctl::Report(3) module can be used to generate various reports from the output of the fwctllog program.

This module generates two kinds of report summary and <report>. The summary compiles the number of occurence for an item (source, destination, service, etc.). The report methods will returns all the log entry that shares the same key ( source, destination, service, etc.)

CREATING A NEW REPORT OBJECT

    Ex. my $report = new Fwctl::Report( start  => 'yesterday',
                                        period => '1 day',
                                        files  => [ 'log' ] );

PARAMETERS

The new method accepts the following parameter :

files

Specifies the file from which to read the fwctllog output. It is an array of file handle or file names. If this parameter is not specified the records will be read from STDIN.

start

Sets the start of the report's period. If the Date::Manip(3) module is installed, you can use any format that this module can parse. If that module is'nt installed you must use the following format YYYY-MM-DD HH:MM:SS or any meaningful subset of that format.

If this option is not used, the report will start with the first record.

end

Sets the end of the report's period. If the Date::Manip(3) module is installed, you can use any format that this module can parse. If that module is'nt installed you must use the following format YYYY-MM-DD HH:MM:SS or any meaningful subset of that format.

If this option is not used, the report will end with the last record.

period

Sets the length of the report's period. This length is interpreted relative to the report's start. This option has priority over the end option.

If you have the Date::Manip module installed, you can use any format that this module can parse. If that module isn't available, you can use a subset of the following format X weeks X days X hours X mins X secs.

threshold

This option will removed records identical in protocol, destination ports, source addresses and destination addressesses that appears in the time window specified by the threshold parameters. Defaults is 120 (2 minutes). Use 0 to generates reports for all the packets.

limit

This parameter can be used to restrict the records over which the report is generated. It is an expression which will be used to select a subset of all the records. You can use the following fields : src_ip, dst_ip, src_host, dst_host, action, device, src_port, dst_port, src_serv, dst_serv, proto, proto_name, and the following operator =, !=, <, >, <=, >=, /regex/, /regex/i. Those operators have the same meaning as in perl. You can also use parentheses and the following logic operator : or, and, not .

METHODS

start()

Return the start of the report in seconds since epoch.

end()

Returns the end of the report in seconds since epoch.

period()

Returns the length of the report's period ( $report->end() - $report->start() )

records()

Returns an array reference to all the records read and which makes the report's sample.

RECORD FIELDS

Each record is an array ref. You can accessed the individual fields of the record by using the following constants. (Those can be imported by using the :fields import tag.)

TIME

The epoch time of the log entry.

ACTION

The resulting action (ACCEPT,DENY,REJECT).

DEVICE

The physical device on which the packet was logged.

IF

The Fwctl(3) interface to which this device is related.

CHAIN

The kernel chain on which that packet was logged.

PROTO

The protocol number.

PROTO_NAME

The name of the protocol.

SRC_IP

The source address of the packet.

SRC_HOST

The source hostname.

SRC_IF

The Fwct(3) interface related to the source address.

SRC_ALIAS

The Fwctl(3) alias associated to the source address.

SRC_PORT

The source port of the logged packet.

SRC_SERV

The service name associated to the logged packet.

DST_IP

The destination IP of the packet.

DST_HOST

The destination hostname.

DST_IF

The Fwctl(3) interface associated with the destination address.

DST_ALIAS

The Fwctl(3) alias related to the destination address.

DST_PORT

The destination port number.

DST_SERV

The service name of the the destination port.

REPORTS

The following report generation methods are available :

service_summary_report()

    my $r = $report->service_summary_report();

Generates a report that shows the number of log entries for each services.

The resulting report is an array ref of hash reference. Each report record's has the following fields.

proto

The protocol number.

proto_name

The protocol name.

dst_port

The destination port.

dst_serv

The destination service's name.

src_port

If the protocol is not UDP or TCP, the source port.

src_serv

If the protocol is not UDP or TCP, the service name associated to the source port.

count

The number of log entries matching the service.

first

The epoch time of the first occurence.

last

The epoch time of the last occurence.

service_report()

    my $r = $report->service_report();

Generates a report that sort the log entries by service.

The report is an array of arrays. Each elements of the report is an array of records which shares the same service.

service_alias_summary_report()

    my $r = $report->service_alias_summary_report();

Generates a report that shows the number of log entries for each destination aliases / service.

The resulting report is an array ref of hash reference. Each report record's has the following fields.

proto

The protocol number.

proto_name

The protocol name.

host_alias

The alias of the destination hosts.

dst_port

The destination port.

dst_serv

The destination's service name.

src_port

If the protocol is not UDP or TCP, the source port.

src_serv

If the protocol is not UDP or TCP, the service name associated to the source port.

count

The number of log entries.

first

The epoch time of the first occurence.

last

The epoch time of the last occurence.

service_alias_report()

    my $r = $report->service_alias_report();

Generates a report that sort the log entries by destination alias and service.

The report is an array of arrays. Each elements of the report is an array of records which shares the same destination alias and service.

service_host_summary_report()

    my $r = $report->service_host_summary_report();

Generates a report that shows the number of log entries for each destination aliases / service.

The resulting report is an array ref of hash reference. Each report record's has the following fields.

proto

The protocol number.

proto_name

The protocol name.

host_ip

The destination host ip address.

host_name

The destination host name.

host_alias

The alias of that host.

dst_port

The destination port.

dst_serv

The destination service's name.

src_port

If the protocol is not UDP or TCP, the source port.

src_serv

If the protocol is not UDP or TCP, the service name associated to the source port.

count

The number of log entries.

first

The epoch time of the first occurence.

last

The epoch time of the last occurence.

service_host_report()

    my $r = $report->service_host_report();

Generates a report that sort the log entries by destination host and service.

The report is an array of arrays. Each elements of the report is an array of records which shares the same destination host and service.

src_alias_summary_report()

    my $r = $report->service_alias_summary_report();

Generates a report that shows the number of log entries for each source aliases.

The resulting report is an array ref of hash reference. Each report record's has the following fields.

host_alias

The source alias.

count

The number of log entries.

first

The epoch time of the first occurence.

last

The epoch time of the last occurence.

src_alias_report()

    my $r = $report->src_alias_report();

Generates a report that sort the log entries by source alias.

The report is an array of arrays. Each elements of the report is an array of records which shares the same source alias.

src_host_summary_report()

    my $r = $report->src_host_summary_report();

Generates a report that shows the number of log entries for each source host.

The resulting report is an array ref of hash reference. Each report record's has the following fields.

host_ip

The source host ip address.

host_name

The source host name.

host_alias

The alias of the source host.

count

The number of log entries.

first

The epoch time of the first occurence.

last

The epoch time of the last occurence.

src_host_report()

    my $r = $report->src_host_report();

Generates a report that sort the log entries by source host.

The report is an array of arrays. Each elements of the report is an array of records which shares the same source host.

dst_alias_summary_report()

    my $r = $report->dst_alias_summary_report();

Generates a report that shows the number of log entries for each destination aliases.

The resulting report is an array ref of hash reference. Each report record's has the following fields.

host_alias

The destination alias.

count

The number of log entries.

first

The epoch time of the first occurence.

last

The epoch time of the last occurence.

dst_alias_report()

    my $r = $report->dst_alias_report();

Generates a report that sort the log entries by destination alias.

The report is an array of arrays. Each elements of the report is an array of records which shares the same destination alias.

src_host_summary_report()

    my $r = $report->src_host_summary_report();

Generates a report that shows the number of log entries for each destination hosts.

The resulting report is an array ref of hash reference. Each report record's has the following fields.

host_ip

The destination host ip address.

host_name

The destination host name.

host_alias

The alias of the destination hosts.

count

The number of log entries.

first

The epoch time of the first occurence.

last

The epoch time of the last occurence.

dst_host_report()

    my $r = $report->dst_host_report();

Generates a report that sort the log entries by destination host.

The report is an array of arrays. Each elements of the report is an array of records which shares the same destination host.

AUTHOR

Francis J. Lacoste <francis.lacoste@iNsu.COM>

COPYRIGHT

Copyright (c) 2000 iNsu Innovations Inc. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

SEE ALSO

Fwctl(3) Fwctl::RuleSet(3) fwctl(8) fwctllog(8) Fwctl::Report(3) Date::Manip(3).