# -*-mode:text-*-
# $Id: README-EN,v 1.12 2004/06/01 05:59:05 hironobu Exp hironobu $
#
# Copyright (C) 1999-2004 Hironobu SUZUKI <hironobu@h2np.net> 
#
# Name: CLSCAN --- Common Log Scan, Analyze for the common security logs
# Author: Hironobu SUZUKI <hironobu@h2np.net> and many contributers
# License: GPL version 2 ( see http://www.gnu.org/licenses/gpl.txt)
# Clscan Official Mail Address:   clscan@h2np.net
#

* clscan --- Tool for analyzing security log.

CLSCAN is a simple tool for analyzing some router's logs and some
security tool's logs like a TCPWRAPPER or IP filter.  CLSCAN supports
plain text and HTML text output. 

statform.pl is a subprogram for create HTML file which include
statistic information from HTML file which was created by clscan.

* SUPPORT

 Routers
     CISCO1003
     CISCO2500
     YAMAHA RT family
     NTT-ME, OMRON, BUG MN 128 family
     Fujitsu NetVehicle
     NEC COMSTARZ
     IODATA NP-BBR
     NTT-ME BA8000pro
     NTT-ME MN8300w
 Tools
     TCPWRAPPER
     IP Filter (FreeBSD)
     iptables  (linux)

* USAGE

  clscan [option]
	-config=config_file
	-outputformat=format (html,text)

		ex) clscan -outputformat=html 
                    clscan -outputformat=text

	-logfile=input_log_file
	-htmlfile=output_HTML_file
	-textfile=output_TEXT_file
	-sitename=site_name

   perl $CLSCANHOME/bin/statform.pl [option]
	-help  show usage.

* CONFIG FILE FORMAT

There are some sample files.

   $CLSCANHOME/etc/sample-class-conf
   $CLSCANHOME/etc/paranoid.conf

** WHAT IS "CLASS"?

Class means "How to describe the level of Alert Warning and Ignore".

    CLASS{Alert,Warn, Ignore}  SERVICE_NAME   PROTOCOL

       * One or more space(s) is required between each elements

CLASS has 3 level condition, "Alert", "Warn" and "Ignore".  

SERVICE NAME is actually name of service, like as "smtp", "sunrpc" or
so on.

PROTOCOL will be described like "Port/Protocol", port number and type
of IP protocol, tcp or udp. Most of router can be applied this format.
But TCPWRAPPER use "daemon name" which is used in inetd.conf.

	ex: (mn128.conf/cisco1003.conf etc.)
	Alert pop3  110/tcp

	ex:(tcpwrapper.conf)
	Alert pop   ipop3d

        [NOTE] You can specify "alert", "warning" and "ignore"
         protocol because each class is depend on your site
         environment.

       "Ignore" means "do nothing and it will not be appeared in
       output".

* SHOULD IT BE ALERT CLASS?

It might depend on the security policy of your site.  For example,
113/tcp may be ignored because "ident 113/tcp" is used for
authenticity check when ftp connection was issued from ftp client.
Some web-robot automatically access all of "http 80/tcp" port.

$CLSCANHOME/etc/sample-class-conf is a sample file. But you have to
decide and choice class entries by yourself.

* HOW TO INSTALL

Step 1: Extract the clscan tar archive file in working directory.

  % tar xzvf  clscan-01.tar.gz

Step 2: Move clscan_dist directory to install directory and 
        rename it.

  # mv clscan_dist /usr/local
  # cd /usr/local
  # mv clscan_dist clscan

Step 3:  run config.sh under clscan directory.

  # pwd 
  /usr/local
  # cd clscan
  # sh config.sh
  Package directory is /usr/local/clscan
  Package bin is /usr/local/clscan/bin
  Package etc is /usr/local/clscan/etc
  Package lib is /usr/local/clscan/lib
  Package doc is /usr/local/clscan/doc
  Sure? [n/Y] Y <-- Type Y if you accept it.
  2921
  #
  3048
  done 
  %

* HOW TO RUN CLSCAN

The system log file which is recorded via syslogd must be used.  Check
your /var/log directory.

** MN128 user

   % clscan -config=$CLSCANHOME/etc/mn128.conf -outputformat=html  \
         < SYSLOG_OF_MN128 > foo.html

** CISCO1003 user

   % clscan -config=$CLSCANHOME/etc/cisco1003.conf -outputformat=html  \
                     < SYSLOG_OF_CISCO1003 > foo.html
** CISCO25000 user

   % clscan -config=$CLSCANHOME/etc/cisco2500.conf -outputformat=html  \
                     < SYSLOG_OF_CISCO2500 > foo.html

** YAMAHA RT user

	% clscan -config=$CLSCANHOME/etc/rt80i.conf -outputformat=html  \
                     < SYSLOG_OF_YAMAHART > foo.html

** NetVehicle user

	% clscan -config=$CLSCANHOME/etc/NetVehicle.conf -outputformat=html  \
                     < SYSLOG_OF_NETVEHICLE > foo.html


** COMSTERZ user

	% clscan -config=$CLSCANHOME/etc/comstarz.conf -outputformat=html  \
                     < SYSLOG_OF_COMSTARZ > foo.html
** IODATA NP-BBR user

	% clscan -config=$CLSCANHOME/etc/iodatanpbbr.conf -outputformat=html  \
                     < SYSLOG_OF_COMSTARZ > foo.html
** NTT-ME BA8000Pro user

	% clscan -config=$CLSCANHOME/etc/ba8000.conf -outputformat=html  \
                     < SYSLOG_OF_BA8000Pro > foo.html
                     < SYSLOG_OF_COMSTARZ > foo.html
** NTT-ME MN8300w user

	% clscan -config=$CLSCANHOME/etc/mn8300w.conf -outputformat=html  \
                     < SYSLOG_OF_MN8300w > foo.html


** TCPWRAPPER user

    % clscan -config=$CLSCANHOME/etc/tcpwrapper.conf -outputformat=html  \
                     < SYSLOG_OF_TCPWRAPPER > foo.html


** IP Filter user

    % clscan -config=$CLSCANHOME/etc/ipf.conf -outputformat=html  \
                     < SYSLOG_OF_IPF > foo.html

	NOTE:
	Ipf's log style must be none-lookup option format. 
	FQDN format is not supported.

** iptables user (NEW)

    % clscan -config=$CLSCANHOME/etc/iptables.conf -outputformat=html  \
                     < SYSLOG_OF_IPTABLES > foo.html



**  HOW TO RUNNING statform.pl

   % perl statform.pl -clscanfile=$SAVEDIR/$FNAME.html  \
      -htmlfile=$SAVEDIR/$FNAME.stat.html 

	-clscanfile=input_clscan_format_html
	-htmlfile=output_html_file

** DEFAULT CONFIGURATION

If you have one router and check only it, you can use default
configuration file instead of option specific configuration file.  If
you check only TCP_WRAPPER log, you can copy tcpwrapper.conf to
clscan.conf which is default configuration file.

  # mv clscan.conf   clscan.conf.bak
  # cp tcpwrapper.conf clscan.conf

* TIPS FOR CONFIGURATION

"foo.conf" is a configuration file which is available for
personalizing. Copy and modify the configuration file as you wish.

  % cp $foo/etc/tcpwrapper.conf ~/etc
  % cd ~/etc
  % mv tcpwrapper.conf  mytcpwrapper.conf 
  % vi mytcpwrapper.conf 
   edit as you like.
  % clscan -config=$home/lib/mytcpwrapper.conf -logfile=/var/log/secure

* OTHER TIPS

** SENDING BY E-MAIL (with HTML supported MUA


 % clscan < log | uuencode ALERTTLIST.htm | mail -s 'LOG' your_address )

** SHELL SCRIPT

---
% cat weekly-clscan.sh
#! /bin/bash
FNAME=`date +'mn128-%Y%b%d-%H%M%S'`
$CMD=/usr/local/clscan/bin/clscan
$CONF=/usr/local/clscan/etc/mn128.conf
$LOG=/var/log/mn128
$CMD -config=$CONF -logfile=$LOG -outputformat=html  -htmlfile=$FNAME.html
---

* UPDATE INFO

See ChangeLog (but written by Japanese)

* BUG REPORT

	clscan@h2np.net

* MAILING-LIST

Sorry, I prepare only Japanese version of Mailing-list.  Control
address is "clscan-ml-ctl@mail.h2np.net".

---
	To: clscan-ml-ctl@mail.h2np.net
        Subject: (none)

        guide
---

* SPECIAL THANKS TO:

Naohiro HONDA
Hirano Satoshi
NetVehicle Web Master 
Kenichi OHWADA
Teruhiko Shinmura
Shin Kajino
Yoshihisa Kayanaka
Tsuyoshi KAWABE
Yoshiki SUGIURA
Shinichirou Ohhara