/ 
Check-SuricataFlows-0.2.0
River stage zero No dependents
/ Check::SuricataFlows

NAME

Check::SuricataFlows - Make sure Suricata is seeing data via reading the Suricata flows json

VERSION

Version 0.2.0

SYNOPSIS

This reads the Suricata EVE JSON flow data file.

.timestamp :: Used for double checking to make sure we don't read farther
    back than we need to.

If the following is found, the entry is checked.

.dest_ip
.src_ip
.flow.pkts_toclient
.flow.pkts_toserver

Bi-directional is when .flow.pkts_toclient and .flow.pkts_toserver are both greater than zero.

Uni-directional is when only .flow.pkts_toclient or .flow.pkts_toserver is greater than zero and the other is zero.

If all entries found are uni-directional then it is safe to assume the monitored span is misconfigured.

If sensor_names is used, then each of the specified sensors is checked for. It is checked from .host in the JSON and the variable for setting that in the Suricata config is .sensor-name .

Example...

use Check::SuricataFlows;
use Data::Dumper;

my $flow_checker;
eval {
    $flow_checker = Check::SuricataFlows->new(
        max_lines      => $max_lines,
        read_back_time => $read_back_time,
        warn_count     => $warn_count,
        alert_count    => $alert_count,
        flow_file      => $flow_file,
    );
};
if ($@) {
    print 'Failed to call Check::SuricataFlows->new... ' . $@ . "\n";
    exit 3;
}

my $results;
eval { $results = $flow_checker->run; };
if ($@) {
    print 'Failed to call $flow_checker->run... ' . $@ . "\n";
    exit 3;
}

print $results->{status};
exit $results->{status_code};

METHODS

new

Initiates the object.

- max_lines :: Maximum distance to read back. The sizing of this should be large enough to
       ensure you get enought data that has bidirectional flow info. Likely need to increase for
       very noisy networks.
    default :: 500

- read_back_time :: How far back to read in seconds. Set to 0 to disable.
    default :: 300

- warn_count :: Warn if it is less then this for bidirectional traffic.
    default :: 20

- alert_count :: Alert if it is less than this for bidirectional traffic.
    default :: 10

- flow_file :: The location json file containing the flow data.
      default :: /var/log/suricata/flows/current/flow.json

- sensor_names :: A array of sensor names to check for. If specified each of these need to be above
          warn/alert count. If empty or undef, only no checking is done for sensor names, just totals.
      default :: []

- ignore_IPs :: A array of IPs to ignore.
      default :: []

Example...

my $flow_checker;
eval {
    $flow_checker = Check::SuricataFlows->new(
        max_lines      => $max_lines,
        read_back_time => $read_back_time,
        warn_count     => $warn_count,
        alert_count    => $alert_count,
        flow_file      => $flow_file,
    );
};
if ($@) {
    print 'Failed to call Check::SuricataFlows->new... ' . $@ . "\n";
    exit 3;
}

run

This method runs the check.

Possible fatal errors such as the flow file not existing or being readable results in a status_code of 3 being set and a description set in status.

This returns a hash ref. The keys are as below.

- status :: Status string for the results.

- status_code :: Nagios style int. 0=OK, 1=WARN, 2=ALERT, 3=UNKNOWN/ERROR

- lines_read :: Number of lines read.

- lines_parsed :: Number of lines successfully parsed.

- lines_get_errored :: Number of lines that resulted in fetch errors.

- lines_get_errors :: A array of strings of errors encountered when getting the next flow entry to process.

- bi_directional_count :: Count of bi-directional flows.

- uni_directional_count :: Count of uni-directional flows.

- ip_ignored_lines :: Lines ignored thanks to src/dest IP.

- ip_parse_errored :: Lines in which the src/dest IP could not be parsed.

- ip_parse_errors :: Array containing error info on src/dest IP c parsing issues.

Example...

my $results;
eval { $results = $flow_checker->run; };
if ($@) {
    print 'Failed to call $flow_checker->run... ' . $@ . "\n";
    exit 3;
}

print $results->{status};
exit $results->{status_code};

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

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

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Check::SuricataFlows

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The GNU General Public License, Version 2, June 1991