Difference between revisions of "Psad2ipt"

From coolscript.org
Jump to navigation Jump to search
 
Line 1: Line 1:
'''DRAFT''' - '''DRAFT'''  - '''DRAFT'''  - '''DRAFT'''  - '''DRAFT''' - '''Coming soon'''
 
 
 
This is an easy and small script to allow customized drop rules on your iptables Firewall to protect against intruders on your network. <br>
 
This is an easy and small script to allow customized drop rules on your iptables Firewall to protect against intruders on your network. <br>
 
The script follows the same approach then [http://coolscript.org/index.php/Syslog_to_Firewall '''Syslog to Firewall'''] but runs on Linux  together with [http://www.netfilter.org/ iptables] and [http://cipherdyne.org/psad/ psad].<br>
 
The script follows the same approach then [http://coolscript.org/index.php/Syslog_to_Firewall '''Syslog to Firewall'''] but runs on Linux  together with [http://www.netfilter.org/ iptables] and [http://cipherdyne.org/psad/ psad].<br>
Line 7: Line 5:
 
=Environment=
 
=Environment=
 
Psad2ipt has been tested on Linux Debian 8 (Jessie) but should run on any other recent Linux Distribution too.
 
Psad2ipt has been tested on Linux Debian 8 (Jessie) but should run on any other recent Linux Distribution too.
=Features=
+
=Basic Features=
 
*Provides a easy [https://en.wikipedia.org/wiki/Intrusion_prevention_system IPS] based on [https://en.wikipedia.org/wiki/Open-source_software OSS] for nuts!
 
*Provides a easy [https://en.wikipedia.org/wiki/Intrusion_prevention_system IPS] based on [https://en.wikipedia.org/wiki/Open-source_software OSS] for nuts!
 
*It runs on it's own, no additional server software is required (such as [https://en.wikipedia.org/wiki/LAMP_%28software_bundle%29 LAMP]), only [http://perl.com/ Perl] with a few additional [http://www.cpan.org/ Modules] is needed.
 
*It runs on it's own, no additional server software is required (such as [https://en.wikipedia.org/wiki/LAMP_%28software_bundle%29 LAMP]), only [http://perl.com/ Perl] with a few additional [http://www.cpan.org/ Modules] is needed.
Line 14: Line 12:
 
*Tight ip address checking to avoid false blockings, psad2ipt does not want to get blamed.
 
*Tight ip address checking to avoid false blockings, psad2ipt does not want to get blamed.
 
*Optional reporting into a [http://splunk.com Splunk] server.
 
*Optional reporting into a [http://splunk.com Splunk] server.
*'''Blame protection''' - never block internal or known customer addresses.
+
*Stateless, ipt records will be added if they are missing (eg after a global flush)
 +
*'''Blame protection''' - never block private IP addresses
 +
<br>
 +
 
 +
=Advanced Features=
 +
*IP to Country mapping, this requires '''geoip.db'''
 +
**Optional overwrite lock times for configured countries
 +
*Whitelist support, this requires additional files
 +
**Never lock any IP address appearing on an whitelist
 +
*Blacklist support, this requires additional files
 +
**Block any IP address appearing on an blacklist, Note that the Whitelist overrules the Blacklist if records are matching
 
<br>
 
<br>
  
Line 31: Line 39:
 
*psad2ipt.xml - Configuration
 
*psad2ipt.xml - Configuration
 
*psad2ipt.db - Database
 
*psad2ipt.db - Database
 +
*geoip.db - Optional IP to Country Code Database
 +
 
==Install Perl Modules==
 
==Install Perl Modules==
 
*This will work with Debian
 
*This will work with Debian
Line 53: Line 63:
 
Chain
 
Chain
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
Chain Name to be used with psad2ipt, the default is P2I
+
Chain Name to be used with psad2ipt, the default is '''P2I'''
 
|-----
 
|-----
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
Line 61: Line 71:
 
Maximum events with a single IP addrress,<br>  
 
Maximum events with a single IP addrress,<br>  
 
this is a counter which counts until the amount has been reached before blocking this ip address. <br>
 
this is a counter which counts until the amount has been reached before blocking this ip address. <br>
The default is 1
+
'''The default is 1'''
 
|-----
 
|-----
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
MaxDBDays
+
LookBehind
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
Maximum days of events which is keeped within the database, older records will be deleted
+
Number of Days where psad2ipt looks behind to get get amount of events for the specified ip address<br>
 +
This values is used when running psad2ipt with the options '''-A''' and '''-C'''
 
|-----
 
|-----
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
LookBehind
+
MaxRules
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
Number of Days where psad2ipt looks behind to get get amount of events for the specified ip address<br>
+
Flood protection: Maximum number of rules allowed within the iptables / psad2ipt chain, abort if exceed
This values is used when running psad2ipt with the options '''-A''' and '''-C'''
 
 
|-----
 
|-----
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
MaxRules
+
MaxRecords
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
Used for flooding prevention, it is the maximum number of rules allowed within the psad2ipt chain
+
Flood protection: Maximum records the database may conatin, abort if exceed
 +
 
 
|-----
 
|-----
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
Line 104: Line 115:
 
Path to DB File, this is needed to be used with option '''-c'''
 
Path to DB File, this is needed to be used with option '''-c'''
 
|-----
 
|-----
 +
 +
 +
 +
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 +
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 +
GeoIP
 +
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 +
Optional Ip to Country Code Database
 +
|-----
 +
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
Line 115: Line 136:
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
Path to be used for reading whitelist files
 
Path to be used for reading whitelist files
 +
 
|-----
 
|-----
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 +
Country (Array)
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
OutsideInterface
+
Code
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
Required: Name of outsite interface name, for exampe '''eth0''', this value has no default!
+
ISO Country Code
 
|-----
 
|-----
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px: 1px solid #F3F781; "|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
SplunkServer
+
BlockTime
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
 
| align="left" valign="top" bgcolor="#ffffff" style="padding:5px; border: 1px solid #F3F781;"|
IP address of the splunk server where psad2ipt is sending messages to UDP 514
+
The time to replace BaseLock
 +
 
 
|}
 
|}
 +
 
==Setup iptables==
 
==Setup iptables==
 
To setup iptable it is essential to define the rule, example for the default rule 'P2I'
 
To setup iptable it is essential to define the rule, example for the default rule 'P2I'
Line 136: Line 161:
 
  /sbin/iptables -A FORWARD -j P2I
 
  /sbin/iptables -A FORWARD -j P2I
 
*Note that the assignment must be placed after the rule creation and before the default drop chain/rule
 
*Note that the assignment must be placed after the rule creation and before the default drop chain/rule
==Running psad2ipt==
+
 
 +
==Setup syslog==
 +
If syslog should be used then this setup can hel to divert messages into an own log file
 +
*/etc/rsyslog.conf
 +
if $programname == 'psad2ipt.pl' then /var/log/psad2ipt.log
 +
:programname, isequal,  "psad2ipt.pl"  ~
 +
#pass tabs and others to syslog
 +
$EscapeControlCharactersOnReceive off
 +
 
 +
 
 +
==White List Path==
 +
psad2ipt is using whitelist files from the configuration value '''WhiteListPath''', every file within path<br>
 +
using the extension '''.conf''' will be automatically read.<br>
 +
Sample Record:<br>
 +
{| style="text-align:left; background:#eeeeee;" border="1"
 +
|-style="background:#aaaaaa"
 +
! Item !! Equivalent CIDR
 +
|- style="color:black;"
 +
|-
 +
| 123 || 123.0.0.0/8
 +
|-
 +
| 123.19 || 123.19.0.0/16
 +
|-
 +
| 123.19.20 || 123.19.20.0/24
 +
|-
 +
|}
 +
 
 +
 
 +
 
 +
==psad.conf==
 +
*Example of enable script, path and param, per alert.
 +
ENABLE_EXT_SCRIPT_EXEC      Y;
 +
EXTERNAL_SCRIPT              /usr/local/psad2ipt/psad2ipt.pl -c /usr/local/psad2ipt/psad2ipt.xml -A SRCIP;
 +
EXEC_EXT_SCRIPT_PER_ALERT  Y;
 +
 
 +
 
 +
==Cron job==
 +
*Example cron job, check psad2ipt each minute and run database maintenance once a motnh
 +
*/1 * * * *  /usr/local/psad2ipt/psad2ipt.pl -c /usr/local/psad2ipt/psad2ipt.xml -C
 +
@monthly  /usr/local/psad2ipt/psad2ipt.pl -c /usr/local/psad2ipt/psad2ipt.xml -VkE 190
 +
 
 +
=Running psad2ipt=
 
psad2ipt can be applied with the following option:
 
psad2ipt can be applied with the following option:
 
*Check the inventory, delete expired addresses from the chain, use the configuration option to allow this command to be allowed from everywhere else then our home directory
 
*Check the inventory, delete expired addresses from the chain, use the configuration option to allow this command to be allowed from everywhere else then our home directory
Line 146: Line 212:
 
*List the database records
 
*List the database records
 
  /usr/local/psad2ipt #./psad2ipt -l
 
  /usr/local/psad2ipt #./psad2ipt -l
 +
*List the database records, show active records only
 +
/usr/local/psad2ipt #./psad2ipt -l -e
 +
*List the database records, list by ip address
 +
/usr/local/psad2ipt #./psad2ipt -l -i x.x.x.x
 
*Delete a single ip address from the environment
 
*Delete a single ip address from the environment
 
  /usr/local/psad2ipt #./psad2ipt -D 1.2.3.4
 
  /usr/local/psad2ipt #./psad2ipt -D 1.2.3.4
 
*Flush the database
 
*Flush the database
 
  /usr/local/psad2ipt #./psad2ipt -F
 
  /usr/local/psad2ipt #./psad2ipt -F
 +
*Vacuum/Shrink the database
 +
/usr/local/psad2ipt #./psad2ipt -V
 +
*Delete records older then 200 days
 +
/usr/local/psad2ipt #./psad2ipt -E 200
  
 
=Examples=
 
=Examples=
*Example rule in chain P21
+
*Example rule in chain P2I
  [email protected]rb-mk01:/usr/local/psad2ipt# iptables -L P2I -n
+
  [email protected]xx-xx01:/usr/local/psad2ipt# iptables -L P2I -n
 
  Chain P2I (1 references)
 
  Chain P2I (1 references)
 
  target    prot opt source              destination
 
  target    prot opt source              destination
 
  DROP      all  --  11.1.2.5            0.0.0.0/0            state NEW /* Dynamic rule by P2I at 2016-02-19 19:16:02 */
 
  DROP      all  --  11.1.2.5            0.0.0.0/0            state NEW /* Dynamic rule by P2I at 2016-02-19 19:16:02 */
 +
 +
*Example Syslog records
 +
M=P2I A=ADD2IPT LCK=1 W=0 IP=71.6.167.142 LTIME=960 SEEN=6
 +
 +
 +
=Download=
 +
<br>
 +
{| style="width: 70%;"
 +
|style="width:10%; vertical-align: top;"|
 +
'''Download the script'''<br>
 +
[[File:Download.png|60px|link=http://coolscript.org/download/psad2ipt.zip|Download]]
 +
<br>
 +
|style="width:90%; vertical-align: top;"|
 +
<br>
 +
 +
|}

Latest revision as of 18:13, 6 May 2016

This is an easy and small script to allow customized drop rules on your iptables Firewall to protect against intruders on your network.
The script follows the same approach then Syslog to Firewall but runs on Linux together with iptables and psad.
Finally this goes into the direction of a IPS

Environment

Psad2ipt has been tested on Linux Debian 8 (Jessie) but should run on any other recent Linux Distribution too.

Basic Features

  • Provides a easy IPS based on OSS for nuts!
  • It runs on it's own, no additional server software is required (such as LAMP), only Perl with a few additional Modules is needed.
  • Sqlite3 is used (that's based on a flat file) to allow to cope a large activity with psad2ipt.
  • Dynamic ramp up the drop time, an intruder get first blocked by default with 15, then 30, 60, 120 and so on minutes on every occurrence of an event.
  • Tight ip address checking to avoid false blockings, psad2ipt does not want to get blamed.
  • Optional reporting into a Splunk server.
  • Stateless, ipt records will be added if they are missing (eg after a global flush)
  • Blame protection - never block private IP addresses


Advanced Features

  • IP to Country mapping, this requires geoip.db
    • Optional overwrite lock times for configured countries
  • Whitelist support, this requires additional files
    • Never lock any IP address appearing on an whitelist
  • Blacklist support, this requires additional files
    • Block any IP address appearing on an blacklist, Note that the Whitelist overrules the Blacklist if records are matching


Setup and Operation description

Pad2ipt runs on it's own iptables chain to add or remove malicious ip addresses which has been identified by psad.
The iptables chain must be present at runtime [abort if not] so creating the Psad2ipt chain is a essential step to do first.
If psad2ipt get's called by psad then it takes immediatly action and blocks the ip by adding a iptables rule into it previous assigned chain.
The rule is using the state connection module to identify incoming packages only and requires the outside interface name to specify the direction,
this way it should be a save drop rule to avoid false blockings. We also offer a whitelist function to prevent wrong data assignment.
However, psad2ipt will never add private ip addresses into it's chain, even if specified to do so.

Installation

Download and extract the archive to /usr/local/psad2ipt, a different path is possible by setup the configuration file.

List of files

  • psad2ipt.pl - Script
  • psad2ipt.xml - Configuration
  • psad2ipt.db - Database
  • geoip.db - Optional IP to Country Code Database

Install Perl Modules

  • This will work with Debian
apt-get install libipc-run-perl
apt-get install libproc-processtable-perl
apt-get install libdbi-perl
apt-get install libdbd-sqlite3-perl 
cpan Net::Syslog

Setup

Setup psad2ipt

  • Edit psad2ipt.xml
psad2ipt.xml
XML Child Element XML Attribute Value

SETTINGS

Chain

Chain Name to be used with psad2ipt, the default is P2I

MaxEvents

Maximum events with a single IP addrress,
this is a counter which counts until the amount has been reached before blocking this ip address.
The default is 1

LookBehind

Number of Days where psad2ipt looks behind to get get amount of events for the specified ip address
This values is used when running psad2ipt with the options -A and -C

MaxRules

Flood protection: Maximum number of rules allowed within the iptables / psad2ipt chain, abort if exceed

MaxRecords

Flood protection: Maximum records the database may conatin, abort if exceed

BaseLock

This is the startup amount of mintes which psad2ipt will use when it's get called with the option -A
The unit is Minutes
The default is 15 Minutes
The amount will dynamically increase on every event, first 15, then 30, 60, 120 and so on

UseSyslog

If set to 1 then psad2ipt will write into syslog to localhost using UDP 514,
Note that this needs to be setup within the syslog daemon configuration before for doing this

DBFile

Path to DB File, this is needed to be used with option -c

GeoIP

Optional Ip to Country Code Database

LogPath

If UseSyslog equals 0 then the specified path is used to wrtie the psa2ipt log files

WhiteListPath

Path to be used for reading whitelist files

Country (Array)

Code

ISO Country Code

BlockTime

The time to replace BaseLock

Setup iptables

To setup iptable it is essential to define the rule, example for the default rule 'P2I'

/sbin/iptables -N P2I

Note that the chain will have no affect unless it has been assigned to the INPUT or FORWARD rule of iptables.
Assigning the chain:

/sbin/iptables -A INPUT -j P2I
/sbin/iptables -A FORWARD -j P2I
  • Note that the assignment must be placed after the rule creation and before the default drop chain/rule

Setup syslog

If syslog should be used then this setup can hel to divert messages into an own log file

  • /etc/rsyslog.conf
if $programname == 'psad2ipt.pl' then /var/log/psad2ipt.log
:programname, isequal,  "psad2ipt.pl"  ~
#pass tabs and others to syslog
$EscapeControlCharactersOnReceive off


White List Path

psad2ipt is using whitelist files from the configuration value WhiteListPath, every file within path
using the extension .conf will be automatically read.
Sample Record:

Item Equivalent CIDR
123 123.0.0.0/8
123.19 123.19.0.0/16
123.19.20 123.19.20.0/24


psad.conf

  • Example of enable script, path and param, per alert.
ENABLE_EXT_SCRIPT_EXEC      Y;
EXTERNAL_SCRIPT              /usr/local/psad2ipt/psad2ipt.pl -c /usr/local/psad2ipt/psad2ipt.xml -A SRCIP;
EXEC_EXT_SCRIPT_PER_ALERT   Y;


Cron job

  • Example cron job, check psad2ipt each minute and run database maintenance once a motnh
*/1 * * * *  /usr/local/psad2ipt/psad2ipt.pl -c /usr/local/psad2ipt/psad2ipt.xml -C
@monthly  /usr/local/psad2ipt/psad2ipt.pl -c /usr/local/psad2ipt/psad2ipt.xml -VkE 190

Running psad2ipt

psad2ipt can be applied with the following option:

  • Check the inventory, delete expired addresses from the chain, use the configuration option to allow this command to be allowed from everywhere else then our home directory
#/psad2ipt -C -c /usr/local/psad2ipt/psad2ipt.xml
  • Check the inventory, delete expired addresses from the chain
/usr/local/psad2ipt #./psad2ipt -C
  • Add the sample address (1.2.3.4) to the specified chain (P2I), this is done immediately.
/usr/local/psad2ipt #./psad2ipt -A 1.2.3.4
  • List the database records
/usr/local/psad2ipt #./psad2ipt -l
  • List the database records, show active records only
/usr/local/psad2ipt #./psad2ipt -l -e
  • List the database records, list by ip address
/usr/local/psad2ipt #./psad2ipt -l -i x.x.x.x
  • Delete a single ip address from the environment
/usr/local/psad2ipt #./psad2ipt -D 1.2.3.4
  • Flush the database
/usr/local/psad2ipt #./psad2ipt -F
  • Vacuum/Shrink the database
/usr/local/psad2ipt #./psad2ipt -V
  • Delete records older then 200 days
/usr/local/psad2ipt #./psad2ipt -E 200

Examples

  • Example rule in chain P2I
[email protected]:/usr/local/psad2ipt# iptables -L P2I -n
Chain P2I (1 references)
target     prot opt source               destination
DROP       all  --  11.1.2.5             0.0.0.0/0            state NEW /* Dynamic rule by P2I at 2016-02-19 19:16:02 */
  • Example Syslog records
M=P2I A=ADD2IPT LCK=1 W=0 IP=71.6.167.142 LTIME=960 SEEN=6


Download


Download the script
Download