A simple set of tools to announce Suricata alerts into a Redis pubsub channel and subscribe to those events with an exabgp client program.
The publisher can also publish into a channel subscribed by a logstash instance, e.g. to insert alerts into an elasticsearch cluster.
Publisher.pl binds and listens to a unix socket to which Suricata will connect and transmit events. Upon receiving each event, the publisher will construct an appropriate message encoded in JSON and publish it in a Redis pubsub channel.
Subscriber.pl listens on the previously mentioned Redis channel for alert messages. Upon receiving each alert, it will write an appropriate exabgp control message in its standard output, announcing the source IP of the alert to be routed to an appropriate target (most typically a blackhole). At the same time, a countdown is initiated for that source and when it reaches zero the source is withdrawn with an appropriate exabgp message. The incoming messages can be filtered by signature, source IP prefix or severity.
As the subscriber will usually run as a client program under exabgp, it may be a little difficult to figure out what it is doing. So, the program can output informational and debug messages in a separate file. This is done via Log::Log4Perl. Look at the log4j-compatible logger configuration file under the lib/ directory. The default logger configuration tries to output info messages to /var/log/subscriber.log. If exabgp is running as a non-root user (most probable), make sure to adjust the permissions so that the subscriber can actually write to that file!.
At present, documentation is sparse as the options are being worked on. Please review the two scripts for available cli parameters.
- -d
-
Run in debug mode, debug messages are printed in the standard error.
- -r|--redis redis server
-
Connect to redis server and publish events. This is required and does not have a default value.
- -u|--user userid
-
Drop privileges to user userid. Defaults to nobody for the publisher. This means that the publisher will try to drop privileges by default. The subscriber on the other hand will only try to change uid if this option is present. For usage as an exabgp client program, this option will probably won't be too useful, as exabgp usually runs as a non privileged user already. Which basically means that trying to change uid will invariably fail.
- -s|--sock socket
-
Listen for suricata events in UNIX socket socket. Default value is /var/run/suricata.sock. You should configure your suricata to use that socket. Here is a very simple example fragment:
- eve-log: enabled: yes filetype: unix_stream filename: /var/run/suricata.sock types: - alert: - -c|--channel channel_name
-
Publish events in Redis channel named channel_name. The event schema is in flux currently. However, it is guaranteed that the subscriber and the publisher code will move in lockstep across changes in this repo.
- --logstash
-
Also publish in channel logstash-channel_name (see -c option above). This is assumed to be a channel where a logstash instance has subscribed. The JSON posted in this channel is flat. Nested objects are not forbidden in elasticsearch and logstash, but may present some difficulties. See elastic/kibana#5411 and elastic/kibana#1084.
- -r|--redis_host redis server
-
Connect to redis server and subscribe to an event channel.
- -p|--redis_port redis port
-
Redis server port, defaults to 6379.
- -u|--user userid
-
Drop privileges to userid, defaults to nobody.
- -t|--tick interval
-
Update timers every interval seconds. When an IP is announced, its internal time to live timer is set to a predefined value (see --duration). As time passes, the time to live decreases and when it reaches 0, the IP is withdawn. The tick value defines how often the TTLs will be updated.
- --dest global_destination
-
Announce the next hop to be global_destination. Defaults to 'self'.
- --severity-thres threshold
-
Do not process events with alert severity of more than threshold. Defaults to 1, meaning that events of severity 2 and above will be ignored.
- --exclude-sig signature [ --exclude-sig signature ] ...
-
Exclude alerts of signature id from processing. The option can be used multiple times.
- --exclude-source CIDR source [ --exclude-source CIDR source ] ...
-
Exclude alerts with source IP CIDR source. Multiple sources are allowed.
- --exclude-destination CIDR destination [ --exclude-destination CIDR destination ] ...
-
Exclude alerts with destination IP CIDR destination. Multiple destinations are allowed.
- --exclude-dest-port destination port [ --exclude-destination CIDR destination ] ...
-
Exclude alerts with destination port destination port. Multiple destination ports are allowed.
- --exclude-src-port source port [ --exclude-src-port source port ] ...
-
Exclude alerts with source port source port. Multiple source ports are allowed.
- --duration duration
-
Time to live of a BGP announcement. After duration seconds elapse, the BGP annoucement is withdrawn.
- -c|--channel channel_name
-
Name of channel to subscribe, defaults to 'suricata'.
publisher.pl -r redis_server -u nobody -s suricata.sock
--channel suricata --logstashsubscriber.pl --redis_host redis_server --tick 5
--exclude-sig=2013357 --exclude-sig=2013360
--exclude-source=10.10.0.0/16 --severity-thres 2
--exclude-dest-port 9103The publisher puts a [@metadata][time] field inside the published event. In order to make use of it from logstash, one may use a logstash.conf that contains something like:
filter {
if [@metadata][time] {
date {
match => [ '[@metadata][time]' , 'ISO8601' ]
}
}
}Please note that in logstash, the @metadata structure is handled by the internal pipeline but is not included in the event when it is being output, e.g. in ElasticSearch.
Optionally, one may elect to also remove the timestamp field from the event by putting an additional
remove_field => 'timestamp'after the match statement.
Athanasios Douitsis, aduitsis@cpan.org
Please file a bug in github, many thanks in advance.
Please install these modules in order for this software to work:
AnyEvent
AnyEvent::Redis
JSON
Data::Printer
Sub::Install (for the IPv6::Address to work)
The IPv6::Address is a separate Perl module, writen also by me (see https://github.com/aduitsis/IPv6-Address, but I have included a local copy inside this package to make things easier. It might become required to install that module in the future.
Copyright (c) 2016 Athanasios Douitsis. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.