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

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CREATING A NEW REPORT OBJECT

PARAMETERS

METHODS

start()

end()

period()

records()

RECORD FIELDS

REPORTS

service_summary_report()

service_report()

service_alias_summary_report()

service_alias_report()

service_host_summary_report()

service_host_report()

src_alias_summary_report()

src_alias_report()

src_host_summary_report()

src_host_report()

dst_alias_summary_report()

dst_alias_report()

src_host_summary_report()

dst_host_report()

AUTHOR

COPYRIGHT

SEE ALSO

Module Install Instructions