DShield Framework Firewall Log Conversion Client



Send any questions to info@dshield.org

This script reads the log that your firewall produces and converts it to DShield format and emails it into DShield.

CONFIGURE IT FIRST

The configuration variables are located in a separate configuration file. The default location is /etc/dshield.cnf. If putting dshield.cnf in /etc isn't possible, you can use the '-config=' command line variable to point to a different location. e.g. '-config=/home/dshield/script/dshield.cnf' (if you put dshield.cnf in '/home/dshield/script')

See dshild.cnf for documentation for each variable.

If you want a "quick start" to test the script, see the TEST IT section, below.

IP AND PORT EXCLUSION

You can prevent log lines from being included in the file that is sent to DShield

By IP address: by specifying IP addresses in the 'dshield-source-exclude.lst' and dshield-target-exclude.lst' files. Enter either a single IP or a range of IPs (192.168.1.0 - 192.168.1.255)

By Port: by specifying ports in the 'dshield-source-port-exclude.lst' and dshield-target-port-exclude.lst' files. Enter either a single port or a range of ports (1000 - 1005)

The default location for these files is in /etc. If you need to put them somewhere else, change the appropriate variables in dshield.cnf

CONFIGURATION HINTS

TEST IT

We supply test.cnf, which is a configuration file with the comments stripped down and most of the variables changed to point to the current directory. (This is OK for testing from the command line, but not necessarily a good idea for running from a cron job. "Current directory" is not particularily defined for a cron job--so variables should contain explicit paths when running from a cron job.)

The one variable you must set is 'log=....' This must be set to point to the file that contains your firewall logs. Otherwise, test.cnf is configured to

Look at the test.wrapper.sh script:

(where {scriptname}.pl is the name of the script you are running.) When you run this, the debugging output will be written to debug.txt. The converted log (that is normally sent to DShield.org) will be written to output.txt

Look at 'debug.txt' in your favorite editor. It should contain:

Note that this test script writes "20011201000000" to dshield.cnt. This is the date/time "2001-12-01 00:00:00" in the stripped down format that dshield.cnt uses. debug.txt should show that log lines that are earlier than this are rejected. Log lines later than this are accepted. Adjust this in your test script as needed for testing.

Check to see that any IP or port exclusions you set in the /etc/dshield*.lst files are executed as you intended them to.

Test and edit .cnf variables as needed. When you have it working, then configure the variables in dshield.cnf (or in test.cnf) to mail the output to dshield (usually 'to=report@dshield.org' and 'whereis=MAIL'), put the .cnf and .lst files where you want them, and then add a cron job to run the script. (The cron job shouldn't write to the dshield.cnt file, of course.)

test.cnf and test_wrapper.sh are oriented towards keeping everything in the current directory. dshield.cnf is oriented towards putting files in their "classical" locations. e.g., config files in /etc, temp files in /tmp, etc. dshield.cnf also has more extensive comments above each variable. You can work with whichever version suits the way you want to set things up.

See http://www.dshield.org/framework.html#security for more information on how to run this script after you have it configured and tested.

(The reason why this document is vague on the actual name of the script is that this script is one of our new "framework" clients, which consist of one processing "engine" and separate parsers for different types for firewalls. So the script will be named 'iptables.pl', 'ipchains.pl', depending. See CHANGES AND BUG FIXES for more on the framework development system.)

USER SUGGESTION ON HANDLING LOG ROTATION

User Tim Rushing contributed this suggestion:

Instead of letting your ipchains.pl script rotate my logs, I kept the log rotation going via logrotate. (That way I still get things e-mailed to me and the old logs compressed without hacking the ipchains.pl script.) What I did, though, to make certain that I don't miss those additional hack attempts was to change the "messages" section of my stock Red Hat /etc/logrotate.d/syslog file to this:

I still have the daily crontab sending things, but this way there will be an additional submission from me just before my logs are rotated on a weekly basis.

I have also modified my /etc/crontab file so that the daily cron jobs (the ones that call logrotate) do not run at the default Red Hat time of 4:02 am, so that if you do add this suggestion to your instructions, mine won't come in when everyone else's do. :)

---Tim Rushing

CHANGES AND BUG FIXES

This script was developed using our "framework" system. If you fix any bugs or want to write a new parser (highly encouraged!), please download framework.tar.gz from the DShield Linux Framework Clients page (http://www.dshield.html/framework.php#frameworkdevelopment) so that your development efforts coordinate with ours. Thank you.

Send any questions to info@dshield.org