== Interscanners
==============================

add_header()
|  Add email headers.
|  
|  This scanner can be used to add an header line to email.
|  
|  Usage: add_header('Header_name','header_data',scanners)
|     or: add_header(...).onlyif('virname')
|  
|  Where: 'Header_name' is a string, which defines name of the header
|         'header_data' is a string, which defines header's content
|         'virname' is a string, which defines any virus name.
|           By default all virus names at least 1 character long: '.'
|         There are some special pattern, which are replaced:
|           %V ... virus name
|           %S ... scanner name
|           %L ... detected level

alternatives()
|  Alternative scanners.
|  
|  Returns a virus, if one scanner returns a virus.
|  Scannig is ended if one scanner returns virus or clean.
|  Next scanner from the list is used, if previous scannes fails
|  (raises an error). Raises an ScannerError, if all scanners failed.
|  
|  Usage: alternatives(scanner1(),scanner2(),...)
|  
|  Where: scanner1(),... are scanners, which may find a virus

cache()
|  Cache return value of a scanner.
|  
|  First call of this scanner caches return value for a scanner included into
|  and return it's value. Next calls returns stored values.
|  
|  Usage: cache('VAR',scanners...)
|  
|  Where: 'VAR' is a string, which defines variable name to cache return value
|  
|  Example: cache('var1', scanner1())
|  
|  New in version 0.7.0.

decompress()
|  Scanner used to decompress archives (zip,rar,arj,zoo,tar,...).
|  
|  It is a scanner, which can decompress some of files.
|  You can define your own decompressors and assing it to any extensions.
|  This scanner is a filescanner only, because external decompressors
|  can unpack only files. A used scanner must be also a filescanner.
|  If not, use file2stream() interscanner.
|  
|  Filetype is determined on file content (not on file extension).
|  It can detect some exe SFX archives too.
|  
|  Usage: decompress(filescanner1(),[a,b,c,d]=[3,500,50MB,20MB])
|  
|  Where: filescanner1() is an filescanner, which can scan all files
|         [a,b,c,d] is an array of 4 numbers:
|           a = max number of recursions
|           b = max number of decompressed files
|           c = max disk usage with all of decompressed files
|           d = max address space usage

deliver()
|  A scanner to force sending some viruses/spams to original recipients.
|  
|  This scanner can be used to send some viruses/spams.
|  You can define by regular expression, what virus name or spam
|  can be sent. By default all non empty virus names will be matched.
|  
|  Usage: deliver(deliver_pattern, scanners)
|  
|  Where: deliver_pattern is an regular expression, which defines
|           virus name to really deliver, other emails will not be delivered.
|  
|  For compatibility issues deliver_pattern is used as fist scanner,
|  if it's type is not string. Also suboption .onlyif(pattern) can
|  be used to define deliver_pattern.

deliver_to()
|  Interscanner to send emails to admins.
|  
|  This scanner can be used to send viruses/spams to an administrator.
|  
|  Usage: deliver_to(recipients,scanners)
|     or: deliver_to(...).onlyif('string')
|  
|  Where: recipients is an array of recipients
|         'string' is an string, which defines regular expression.
|           If this expression is found in virus name, mail is
|           delivered, otherwise don't.

drop()
|  Interscanner to drop viruses/spams. By default they are rejected.
|  
|  This scanner can be used to drop some viruses, like Klez.
|  Klez sends fake sender address and this virus can't be sent
|  back to sender, because sender is faked.
|  
|  This scanner does nothing else, like sets the DROP flag.
|  Email is passed to parent scanners and is dropped in sagator.
|  
|  Usage: drop(drop_pattern,scanners)

f2s()
|  An alias for file2stream interscanner.

file2stream()
|  File to stream converter.
|  
|  This scanner converts a filescanner input into streamscanner.
|  
|  Usage: file2stream(scanner1())
|  
|  Where: scanner1() is an interscanner or realscanner.
|           It must be a streamscanner.

interscanner()
|  Default scanner used for building all other interscanners.

log()
|  Advanced logger interscanner.
|  
|  This scanner can be used to log some special data.
|  You can use these variables in format string:
|    $LEVEL              - detected virus level
|    $VIRNAME            - name of detected virus, empty if CLEAN
|    $STATUS             - if mail is dropped, rejected, ...
|    $QNAME              - quarantine file name
|    $SCANNER_NAME       - scanner which reported this virus
|    $SENDER             - scanned message sender
|    $RECIPIENTS         - scanned message recipients
|    $SIZE               - email size
|    $VERSION            - sagator's version
|    $SENTBY_IP          - sender's IP
|    $SENTBY_NAME        - sender's hostname
|    $SENTBY_HELO        - sender's HELO/EHLO string
|    $DATETIME           - date and time in standard format ("%c")
|    $SYSLOG_DATE        - date and time in syslog format ("%a %e %H:%M:%S")
|    $PID                - current process ID
|  
|  You also can use log.FORMAT for default format or log.SUMMARY_REPORT
|  for summary reporter script.
|  
|  Usage: log(logto,format,scanners...)
|  
|  Where: logto is a string, which defines filename to store these data
|           If logto is an integer, it defines log level in standard
|           log file.
|         format is a string, which defines data format

log_mysql()
|  MySQL logger interscanner. [obsolete]
|  
|  Usage: log_mysql(host, port, dbname,dbuser,dbpasswd,format,scanners...)
|  
|  Where: host is a string, which defines MySQL database hostname
|           (you can use "127.0.0.1", UNIX socket can't be used in chroot)
|         port is an integer, which defines MySQL database TCP port number
|           (it is by default 3306)
|         dbuser is a string, which defines username which can log to DB
|         dbname is a string, which defines database name
|         dbpasswd is a string, which defines user password
|         format is a string, which defines data format.
|           For detailed format description see log() scanner documentation.
|           You also can use log_mysql.FORMAT for default format.
|  
|  Obsolete since 0.7.0, use log_sql() instead.

log_pgdb()
|  PostgreSQL logger, using pgdb python DB API 2.0 compilant module. [obsolete]
|  
|  Usage: log_pgdb(host, port, dbname,dbuser,dbpasswd,format,scanners...)
|  
|  Where: host is a string, which defines pgsql database hostname
|           (you can use "localhost", UNIX socket can't be used in chroot)
|         port is an integer, which defines pgsql database TCP port number
|           (it is by default 5432)
|         dbuser is a string, which defines username which can log to DB
|         dbname is a string, which defines database name
|         dbpasswd is a string, which defines user password
|         format is a string, which defines data format.
|           For detailed format description see log() scanner documentation.
|           You also can use log_pgdb.FORMAT for default format.
|  
|  Obsolete since 0.7.0, use log_sql() instead.

log_pgsql()
|  PosgreSQL logger interscanner, using pg module. [obsolete]
|  
|  Usage: log_pgsql(host, port, dbname,dbuser,dbpasswd,format,scanners...)
|  
|  Where: host is a string, which defines pgsql database hostname
|           (you can use "localhost", UNIX socket can't be used in chroot)
|         port is an integer, which defines pgsql database TCP port number
|           (it is by default 5432)
|         dbuser is a string, which defines username which can log to DB
|         dbname is a string, which defines database name
|         dbpasswd is a string, which defines user password
|         format is a string, which defines data format.
|           For detailed format description see log() scanner documentation.
|           You also can use log_pgsql.FORMAT for default format.
|  
|  Obsolete since 0.7.0, use log_sql() instead.

log_psycopg()
|  PostgreSQL logger, using psycopg python DB API compilant module. [obsolete]
|  
|  Usage: log_psycopg(host, port, dbname,dbuser,dbpasswd,format,scanners...)
|  
|  Where: host is a string, which defines pgsql database hostname
|           (you can use "localhost", UNIX socket can't be used in chroot)
|         port is an integer, which defines pgsql database TCP port number
|           (it is by default 5432)
|         dbuser is a string, which defines username which can log to DB
|         dbname is a string, which defines database name
|         dbpasswd is a string, which defines user password
|         format is a string, which defines data format.
|           For detailed format description see log() scanner documentation.
|           You also can use log_psycopg.FORMAT for default format.
|  
|  Obsolete since 0.7.0, use log_sql() instead.

log_sql()
|  SQL interscanner for python DB-API 2.0 compatible DB modules.
|  
|  Usage: log_sql(db_connection,format,scanners...)
|  
|  Where: db_connection is a database connection. For these connections
|           see doc/Databases.txt file.
|         format is a string, which defines an SQL INSERT command with
|           optional variables described in log() scanner.
|  
|  New in version 0.7.0.

log_sqlite()
|  SQLite logger interscanner. [obsolete]
|  
|  Usage: log_sqlite(dbname,format,scanners...)
|  
|  Where: dbname is a string, which defines, which database to use
|         format is a string, which defines data format.
|           For detailed format description see log() scanner documentation.
|           You also can use log_sqlite.FORMAT for default format.
|  
|  Obsolete since 0.7.0, use log_sql() instead.

log_syslog()
|  Syslog logger interscanner to log via syslog.
|  
|  For detailed description see log() scanner.
|  
|  Usage: log_syslog(format,scanners...)

match_all()
|  Returns a virus only if all scanners returns a virus.
|  
|  Usage: match_all(scanner1(),scanner2(),...)
|  
|  Where: scanner1(),... are scanners, which must find a virus

match_any()
|  Match for any sub-scanner is required.
|  
|  Returns a virus, if one scanner returns a virus.
|  Next scanner from list is used, if previous scanner returns
|  no virus, or failed (raised an error).
|  
|  Usage: match_any(scanner1(),scanner2(),...)
|  
|  Where: scanner1(),... are scanners, which may find a virus

mimeparse()
|  Email parser interscanner. [obsolete]
|  
|  This scanner parses MIME attached mail and send multiple of
|  streams into another_scanner(). If an multiscanner is used
|  as scanner1(), optimal method is used (scans all files
|  at once).
|  
|  Usage: mimeparse(scanner1(...))
|  
|  This scanner is obsolete since 0.5.0, use parsemail() instead.

modify_header()
|  Modify email headers.
|  
|  This scanner can be used to modify email headers.
|  
|  Usage: modify_header('^Header_regexp:','Header_regexp: prefix',scanners)
|     or: modify_header(...).onlyif('virname')
|  
|  Where: '^Header_regexp:' is a string, which defines regular expression
|           to find for this header
|         'Header_regexp: prefix' is a string, which defines new header
|           data
|         'virname' is a string, which defines any virus name.
|           By default all virus names at least 1 character long: '.'
|         There are some special pattern, which are replaced:
|           %V ... virus name
|           %S ... scanner name
|           %L ... detected level

modify_subject()
|  Modify email Subject.
|  
|  This scanner can be used to modify email Subject.
|  
|  Usage: modify_subject('prefix',scanners)
|     or: modify_subject(...).onlyif('virname')
|  
|  Where: 'prefix' is an prefix added into Subject.
|         'virname' is a string, which defines any virus name.
|           By default all virus names at least 1 character long: '.'
|         For more information see modify_header() interscanner.
|  
|  For example original Subject line is:
|    Subject: Testing mail
|  and i use:
|    modify_subject('[SPAM]', spamassassind(['localhost',783]))
|  When spam will be found, header will be modifyed to:
|    Subject: [SPAM] Testing mail

nothing()
|  This scanner does nothing. :-)
|  
|  Usage: nothing(some parameters...)
|  
|  Where: some parameters... are ignored :)

parsemail()
|  Email parser interscanner.
|  
|  This scanner parses emails and send multiple of streams into
|  scanner1(). If an multiscanner is used as another_scanner,
|  optimal method is used (scans all files at once).
|  
|  Usage: parsemail(scanner1(...) [,scanner2(...)] )
|  
|  Example: parsemail(libclam())

quarantine()
|  Quarantine into a directory.
|  
|  This scanner can be used to quarantine an virus/spam.
|  qdir is a directory, in which viruses are stored.
|  Following regular expression can be used to disable quarantining
|  of some viruses or spams.
|  
|  Usage: quarantine('qdir','dont quarantine regular expression',scanners)
|  
|  Where: 'qdir' is a string, which defines a qatantine directory,
|                directory, in which viruses/spams are stored.
|                This string can contain %X substrings. These strings
|                are represented as defined in strftime. For more information
|                see "man strftime". If this directory not exitst,
|                it's created.
|         'dont quarantine regular expression' is a regular expression,
|                which defines virus names, which can't be quarantined
|  
|  Example: quarantine('/tmp/quarantine/%Y%m', '', a_scanner())
|             - every month will be stored in separate directory

recover()
|  Recover from an error. [obsolete]
|  
|  This scanner can be used to recover from scanner fail. If an scanner
|  fails (raises an error), this scanner return no virus.
|  
|  Usage: recover(scanner1(),scanner2(),...)
|  
|  Where: scanner1... are scanners
|  
|  This scanner is obsolete since 0.5.0. Please use recover operator (~).

rename()
|  Interscanner to rewrite virus name returned by an scanner.
|  
|  Usage: rename(newname, scanners)
|     or: multiplier(MP)
|  
|  Where: newname is a string, which defines new virus name.
|         These string will be replaced:
|           $VNAME by old name
|           $LEVEL by detected level as float
|           $STARS by detected level as stars
|         MP is an multiplier for LEVEL and STARS. Returned level
|           is multiplied by this constant.
|  
|  Renaming is skipped, if level<1.0.

report()
|  Report any message to admin, user or anybody.
|  
|  This module can be used to report an message to administrator
|  or to any user. You can use following variables in report messages:
|    $FROM               report sender
|    $VIRNAME            detected virus name
|    $SMTP_COMM          SMTP communication
|    $STATUS             status of this message (REJECTED, DROPPED, ...)
|    $QNAME              filename in quarantine
|    $SCANNER_OUTPUT     returned scanner output
|    $SCANNER_NAME       name of the scanner
|    $MSG_HEADER         virus/spam header
|    $MSG_BODY           virus/spam body (without header)
|    $RANDOM             10 random characters (useable to generate a boundary)
|    $SENDER             virus/spam sender
|    $RECIPIETNS         virus/spam recipients joined by comma (',')
|    $TO                 report recipeints
|    $VERSION            sagator's version
|    $SENTBY_IP          sender's IP
|    $SENTBY_NAME        sender's hostname
|    $SENTBY_HELO        sender's HELO/EHLO string
|  
|  Usage: report(recipients, msg, scanners)
|     or: report(...).sender('<email@of.sender.dom>')
|     or: report(...).ifscan(cond_scanner)
|  
|  Where: recipients is an array of recipients,
|           like: ['<r1@dom>','<r2@dom>',...]
|         msg is an message template, you can use report.MSG_TMPL
|         cond_scanner is a scanner, which defines, when report may be sent

report_recipients()
|  Report any message to email recipients.
|  
|  This module can be used to report an message to mail recipients.
|  For message description see report() scanner.
|  
|  Usage: report_recipients(msg, scanners)
|     or: report_recipients(...).sender('<email@of.sender.dom>')
|     or: report(...).ifscan(cond_scanner)
|  
|  Where: msg is an message template, you can use report.MSG_TMPL
|          scanners are scanners which are used
|         cond_scanner is a scanner, which defines, when report may be sent

restore()
|  Restore scanner return value. [obsolete]
|  
|  This scanner return's return value for previously stored variable.
|  
|  Usage: restore('VAR')
|  
|  Where: 'VAR' is a string, which defines variable name to store return value
|  
|  Example: store('var1')
|  
|  Obsolete since 0.7.0, use cache() instead.

s2f()
|  An alias for stream2file interscanner.

scanoper()
|  A scanner used to operate over various scanners.

status()
|  This interscanner can be used to collect some other statistics.
|  
|  Usage: status("String",scanner1(),scanner2(),...)
|  
|  Where: "String" is a string, which defines a prefix for status update
|           This scring can't contain spaces.
|         scanner1(),... are sagator's scanners
|  
|  Preffered usage:
|    SCANNERS=[
|      status("Virus",virus_scanner1(),...),
|      status("Spam",spam_scanner1(),...)
|    ]
|  This collects Virus-count,Virus-bytes,Spam-count,Spam-bytes in collector.

store()
|  Store scanner return value. [obsolete]
|  
|  This scanner return's return value for a scanner included into
|  and stores it's value into a variable.
|  
|  Usage: store('VAR',scanners...)
|  
|  Where: 'VAR' is a string, which defines variable name to store return value
|  
|  Example: store('var1', scanner1())
|  
|  Obsolete since 0.7.0, use cache() instead.

stream2file()
|  Stream to file converter.
|  
|  You can use it to save streams into files.
|  
|  Usage: stream2file(scanner1())
|  
|  Where: scanner1() is a interscanner or realscanner.
|           It must be a filescanner.

stream2mbox()
|  An alias for stream2file(...,1) interscanner.

time_limit()
|  Interscanner to limit scanner execution time.
|  
|  Usage: time_limit(seconds, scanners)
|  
|  Where: seconds is an float, which defines maximum number of seconds.
|           After this limit scanner returns a virus and will be
|           dropped or rejected (maybe also quarantined) according
|           to configuration.
|  
|  Example: time_limit(300, parsemail(s2f(libclam())) )
|  
|  New in version 0.7.0.

== Virus scanners
==============================

ascanner()
|  Default scanner user for building all other realscanners.

attach_name()
|  Attachment name scanner.
|  
|  This scanner checks defined name of file in mime attachments.
|  By default known executable extensions will be blocked.
|  This scanner can be used only if it's parent is parsemail().
|  
|  Usage: attach_name({'VirName':'regexp_pattern',..},flags=re.I)
|  
|  Where: 'VirName' is a string, which defines virus name
|         'regexp_pattern' is an regular expression. If this expression
|           is found in attachment's name, VirName is returned
|           as virus name.
|         flags is a number, which defines regular expression flags.
|           By default IGNORECASE is used.
|  
|  Example: attach_name({
|             'Executable': '\.(exe|com|vxd|dll|cpl|scr|pif|lnk|bat|vbs|js)$'
|           })

avgd()
|  AVG daemon realscanner.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. It uses AVGd (a deamonized linux version of AVG7).
|  
|  Usage: avgd(params='-arc -rt -heur',connto=('localhost',55555),chroot='')
|  
|  Where: params is a string which defines command line parameters,
|           like -arc, -heur, -rt, ... see man page for avgscan
|           By default "-arc -rt -heur" is used now.
|         connto is a tuple of host,port of avgd, by default ('localhost',55555)
|         chroot is an string in which sagator is running, if avgd
|           is not running in this chroot
|  
|  To start AVGd in chroot, move all neccessary files into your chroot,
|  and change following line in init.d/avgd from:
|    daemon $AVG_HOME/avgscan -d
|  to:
|    daemon chroot /var/spool/vscan $AVG_HOME/avgscan -d
|  or similiar.

bdc()
|  Bitdefender realscanner.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. It parses Bitdefender output.
|  
|  Warning: If you are using bdc in chroot, don't forget to mount
|           /proc directory under chroot.
|  
|  Usage: bdc(command=['/opt/bdc/bdc','--mail','--arc'])
|  
|  Where: command is a array which defines command with parameters.
|           By default: ['/opt/bdc/bdc','--mail','--arc']

clamd()
|  ClamAV daemon realscanner.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. ClamAV is a free program under GPL and may be freely
|  used. Its database is very well.
|  
|  If you need a chrooted clamd, copy it into chroot and start it
|  from here. If you are not familiar with it, use clamscan scanner
|  from this module. It easily does chroot support, but it
|  is not powerfull.
|  
|  Requires: clamd (clamav daemon)
|  
|  Usage: clamd(['localhost',3310])
|     or: clamd('/var/spool/vscan/clamd')
|  
|  Where: 1st definition defines a clam daemon on host localhost,
|             port 3310 (it is the default)
|         2nd definition defines access to clamd via UNIX socket

clamscan()
|  ClamAV command line realscanner.
|  
|  This scanner is a realscanner, which can be used to scan
|  for viruses. ClamAV is a free program under GPL and may be freely
|  used. Its database is very well.
|  
|  It can be easily used in chroot. mkchroot.sh from sagator package
|  automatically integrates it into chroot environment.
|  
|  Requires: clamscan binary from clamav
|  
|  WARNING: If you are using clamscan from chroot, you need to configure
|           freshclam to update chrooted copy of database!!!
|  
|  Usage: clamscan(['/usr/bin/clamscan','--stdout','--infected',
|                   '--disable-summary','-r','--mbox'])
|  
|  Where: in [] are command line parameters for clamscan binary

cmd()
|  A realscanner used to scan over command line programs.
|  
|  Usage: cmd(['command','arg1',...],StatusCLEAN,StatusINFECTED,RE)
|  
|  Where: 'command' is a string, which command to run
|         'argX' are command line arguments, as last argument the
|           filename is added
|         StatusCLEAN may be:
|           an array of integers, which defines "clean" exit codes
|           an regexp, indication no virus found
|         StatusINFECTED may be:
|           an array of integers, which defines "virus found" exit codes
|         RE is an regular expression string, which can extract virus
|           names from scanner output.

cmd_bdc()
|  This scanner uses bdc command from BitDefender antivirus.
|  
|  See http://www.bitdefender.com/ for more info.
|  
|  Usage: cmd_bdc(command='/opt/bdc/bdc')

cmd_clamav()
|  This scanner uses clamscan command from clamav project.
|  
|  See http://www.clamav.net/ for more info.
|  
|  Usage: cmd_clamav(command='clamscan')

cmd_drweb()
|  This scanner uses drweb command from DRWEB antivirus.
|  
|  See http://www.sald.com/, http://drweb.imshop.de/ for more info.
|  
|  Usage: cmd_drweb(command='/usr/local/drweb/drweb')

cmd_fprot()
|  This scanner uses f-prot command from FRISK F-Prot antivirus.
|  
|  See http://www.f-prot.com/ for more info.
|  
|  Usage: cmd_fprot(command='f-prot')

cmd_kavscanner()
|  This scanner uses kavscanner command from KasperskyLab kavscanner.
|  
|  See http://www.kaspersky.com/ for more info.
|  
|  Usage: cmd_kavscanner(command='/opt/kav/bin/kavscanner')

cmd_mks()
|  This scanner uses mks antivirus.
|  
|  See http://linux.mks.com.pl/ for more info.
|  
|  Usage: cmd_mks(command='mks32',extra_params_array=[])

cmd_trendmicro()
|  This scanner uses trendmicro command from Trend Micro FileScanner.
|  
|  See http://www.trendmicro.com/ for more info.
|  
|  Usage: cmd_trendmicro(command='/etc/iscan/vscan')

cmd_uvscan()
|  This scanner uses uvscan command from McAfee AntiVirus.
|  
|  See http://www.mcafee.com/ for more info.
|  
|  Usage: cmd_uvscan(command='uvscan')

cmd_vbuster()
|  This scanner uses vbuster command from VirusBuster.
|  
|  See http://www.virusbuster.hu/en/ for more info.
|  
|  Usage: cmd_vbuster(command='vbscan')

const()
|  Realscanner to return a constant value (virus or clean).
|  
|  This scanner has no special functionality. It returns always
|  a defined virus, or clean (if virus is not defined).
|  This scanner has no error codes.
|  
|  Usage: const(level,VirName,return_string=[])
|      or const()
|  
|  Where: level is an float which defines returned infection level
|           If level is not defined, after scanning an error is raised.
|         VirName is a returned virus.
|         return_string is a array of strings returned
|  
|  Examples: const(0.0)         # Return clean
|            const(1.0,'Virus') # Return virus name "Virus"
|            const()            # Raise an error

dazuko()
|  Scanner which uses dazuko directory to scan for viruses.
|  
|  Usage: dazuko('/dazuko_prefix','logfile')
|  
|  Where: '/dazuko_prefix' is a string, which defines directory
|            and a part of filename to store scanned files,
|            by default '/tmp/dazuko'
|         'logfile' is a string, which defines full path and filename
|            of logfile, by default not logfile used
|         'regexp' is a string, which defines how to parse logfile
|  
|  Obsolete since 0.7.0, use filesys() instead.

dspam()
|  This realscanner uses dspam library.
|  
|  For detailed description see DSPAM documentation.
|  
|  Usage: dspam(home='/var/dspam',user=None,group=None,
|               classify=None,source=None,
|               train=None,flags=pydspam.DSF_SIGNATURE)
|  
|  Where: home is dspam home dir ('/var/dspam')
|         user is dspam user (user running sagator's process)
|         group is dspam group (group running sagator's process)
|         classify is how to classify this message
|           Available options: DSR_ISSPAM, DSR_ISINNOCENT
|           Default: Don't classify.
|         source is message source:
|           Available options: DSS_ERROR, DSS_CORPUS, DSS_INOCULATION
|           Default: No source defined.
|         train is training mode
|           Available options: DST_TEFT, DST_TOE, DST_TUM, DST_NOTRAIN
|           Default: DST_TEFT
|         flags are dspam flags
|           Available options: DSF_CHAINED, DSF_SIGNATURE, DSF_COPYBACK
|                              DSF_NOISE, DSF_WHITELIST, DSF_MERGED
|           Default: DSF_SIGNATURE
|  
|  Examples:
|    basic usage:
|      dspam()
|    training emails badly assigned as spams:
|      drop('',dspam(classify=DSR_ISSPAM,source=DSS_ERROR,train=DST_TOE))
|    training emails badly assinged as inoocent:
|      drop('',dspam(classify=DSR_ISINNOCENT,source=DSS_ERROR,train=DST_TOE))

dspam_classify()
|  Realscanner to classify emails for DSPAM.
|  
|  This scanner can be used to classify messages as spams/hams.
|  For parameters see dspam() scanner documentation.
|  
|  Example:
|    configure SCANNERS=[ dspam_classify(source=DSS_CORPUS,flags=0) ]
|    and you can run sgscan to learn messages from a box:
|    Training ham (clean messages):
|      sgscan --dspam-classify=innocent MAILBOX
|    Training spam:
|      sgscan --dspam-classify=spam MAILBOX

exec_any()
|  Realscanner to exec a defined command. [obsolete]
|  
|  If command returns exit status 0, no virus is returned.
|  If exit code is any from statusX, virus is returned.
|  Otherwise an error is raised.
|  
|  Usage: exec_any([command,arg1,...],[statusA1,...],[statusB1,...])
|  
|  Where: command is a string, which command to run
|         argX are command line arguments, as the last argument the
|           filename is added
|         statusA1,... are integers, which defines "clean" exit codes
|         statusB1,... are integers, which defines "virus found" exit codes
|  
|  This scanner is obsolete since 0.5.9. Use cmd() scanner.

file_magic()
|  File magic test (like "file -i command").
|  
|  This scanner can be used to test file content for a special type.
|  You need a python module "magic", which is by default in file's
|  source, but in most distributions it is not compiled in package.
|  
|  Usage: file_magic({'VirName':'regexp_pattern',..}, flags=0)
|  
|  Where: 'VirName' is a string, which identifies defined virus
|         'regexp_pattern' is a regular expression pattern
|         flags is an int, which defines regular expression flags,
|           like re.I to ignore it's case.

file_type()
|  Realscanner, which scans type of a file.
|  
|  A scanner to chcek content of a file for a special type (like zip, ...).
|  
|  Usage: file_type({'type':'vir',...})
|  
|  Where 'type' is a name of type returned by filetype.* function
|        'vir' is a vir name returned, if file type is matched
|  
|  Example: # scan for executables (COM,EXE,PIF and similiar types)
|           parsemail(file_type({'exe': 'MS Executable',
|                                'elf': 'Linux Executable'}))

filesys()
|  Scanner which uses filesystem scanners.
|  
|  Usage: filesys(prefix='/tmp/fs',logfile='',regexp='')
|  
|  Where: '/prefix' is a string, which defines directory
|            and a part of filename to store scanned files,
|            by default '/tmp/fs'
|         'logfile' is a string, which defines full path and filename
|            of logfile, by default not logfile used
|         'regexp' is a string, which defines how to parse logfile
|  
|  New in version 0.7.0.

kav()
|  Kaspersky Antivirus realscanner.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. It parses Kaspersky antivirus output.
|  
|  Usage: kav(command=['/opt/kav/5.5/kav4unix/bin/kavscanner','-j3'])
|  
|  Where: command is a array which defines command with parameters.

kavclient()
|  Kaspersky antivirus client realscanner.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. It parses Kaspersky antivirus client output.
|  
|  Usage: kavclient(socket_path='/var/run/aveserver',
|                   command='/opt/kav/5.5/kav4mailservers/bin/aveclient',
|                   chroot=True)
|  
|  Where: socket_path is a string, which defines path co aveserver socket
|           inside chroot. (default: /var/run/aveserver)
|         command is a string, which defines command to run.
|           (default: /opt/kav/bin/aveclient)
|         chroot is an string, which defines a prefix added to each filename.
|           If you are not running aveserver in chroot path, set it
|           to your CHROOT.

libclam()
|  ClamAV realscanner - uses libclamavmodule python library.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. ClamAV is a free program under GPL and may be freely
|  used. Its database is very well.
|  
|  Requires: libclamav module for python (sagator-libclamav package)
|  
|  WARNING: Streamscanner ignores options and limits!
|  
|  WARNING: Streamscanner can't scan mailboxes and archives.
|           Use parsemail() for emails anb if you need also
|           archive support, use decompress() interscanner.
|  
|  WARNING: If you are using clam from chroot, you need to configure
|           freshclam to update chrooted copy of database!!!
|  
|  Usage: libclam(options=CL_DEFAULT,limits={})
|  
|  Where: options is an number, whic defines libclam options,
|           see clamav documentation for more info
|         limits is an tuple, which defines limits for clamav
|           decompressor, see clamav doc. for more info

max_file_size()
|  Realscanner to test email's size.
|  
|  Usage: max_file_size(size,name='FileSizeOverrun')
|  
|  Where: size is a number of bytes, which if exceeded, virus is returned
|         name is a string, which identifies the virus name.
|            If this parameter is not present, 'FileSizeOverrun' is returned.
|  
|  Example: max_file_size(1024*1024*10)
|           # all files at least 10MB will be reported as virus

mime_ext()
|  A extension scanner. [obsolete]
|  
|  This scanner checks defined extension of file in mime attachments.
|  Regexp checks with ignoring of case are used.
|  You can use predefined extensions from mime_ext.EXECUTABLES.
|  
|  Usage: mime_ext(wrong_type='')
|  
|  Example: mime_ext(mime_ext.EXECUTABLES)
|  
|  This scanner is obsolete since 0.5.9, use attach_name() instead.

nod2()
|  NOD2 scanner. Works with nod32lfs.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. You can use nod32 from nod32lfs package.
|  
|  Usage: nod2(['command','params...'])
|  
|  Where: in [] are command line parameters for nod32

nod2dazuko()
|  NOD32lfs scanner over dazuko module.
|  
|  Usage: nod2dazuko('/dazuko_prefix','logfile')
|  
|  Where: '/dazuko_prefix' is a string, which defines directory
|            and a part of filename to store scanned files,
|            by default '/tmp/dazuko'
|         'logfile' is a string, which defines full path and filename
|            of logfile, by default not logfile used

nod2pac()
|  NOD32lfs scanner over it's preload library module.
|  
|  You need to set LD_PRELOAD to NOD32's preload library (libnod32pac.so).
|  You can do this by adding this line into /etc/sysconfig/sagator:
|    LD_PRELOAD=/usr/lib/libnod32pac.so
|  
|  Usage: nod2dazuko(prefix='/tmp/fs',logfile='')
|  
|  Where: prefix is a string, which defines directory
|            and a part of filename to store scanned files,
|            by default '/tmp/dazuko'
|         logfile is a string, which defines full path and filename
|            of logfile, by default not logfile used
|  
|  Recommended settings:
|    /etc/nod32/nod32.cfg:
|      nod32_sock_path = "/var/spool/vscan/tmp/nod32d.sock"
|      log_enabled = yes
|      log_file = "/var/spool/vscan/var/log/nod32d.log"
|      act = 1
|    rm -f /tmp/nod32d.sock /var/log/nod32d.log
|    ln -s /var/spool/vscan/var/log/nod32d.log /var/log/
|    ln -s /var/spool/vscan/tmp/nod32d.sock /tmp/

regexp_scan()
|  Primitive regexp pattern scanner.
|  
|  There can be more patterns for one virus. All patterns in []
|  must match to assign an stream as virus (AND opeator).
|  There can also be more virnames in one dictionary.
|  
|  Usage: regexp_scan([['VirName','RegExp_Pattern1...',...],...],size=0,flags=0)
|  
|  Where: 'VirName' is a string, which identifies defined virus
|         'RegExp_Pattern1...' is a regexp pattern
|         size is a number, which defines, how many bytes may be checked.
|           If it is 0 or not defined, whole stream is scanned.
|           If it is -1, email header is scanned.
|         flags is an integer, which defines regular expression flags.
|           By default no flags are used.
|    
|  Example: regexp_scan([
|             # Scan for a part of EICAR virus test file pattern
|             ['EICAR','^X5O!P%@AP[4.*EICAR-STANDARD-ANTIVIRUS-TEST-FILE'],
|             # Scan for a an EXE file pattern endoded as base64.
|             ['UnknownEXE','^TVqQ']
|           ])

remove_headers()
|  Remove email headers.
|  
|  This scanner can be used to remove email headers.
|  
|  Usage: remove_headers('header name' [,'next header name' [, ...] ])
|  
|  Where: 'header name' is a string, which defines header key to delete

sanitize()
|  Sanitize (rename attachment filenames) an email.
|  
|  This scanners is a realscanner, which can be used to sanitize
|  email. It means all attachments are renamed to safe names.
|  For example "filename.exe" will be renamed to "filename-exe".
|  
|  WARNING! This scanner is in BETA stage! Id don't conform to RFC 2183!
|  
|  Usage: sanitize(insert='-',extensions='[a-z0-9]{3}')
|  
|  Where: insert is a string, which can be inserted for sanitized attachments
|         extensions is an regular expressios to find

savse()
|  Symantec antivirus scan engine scanner.
|  
|  Usage: savse('host',port)
|  
|  Example: parsemail(savse('localhost',1344))
|  
|  Comments:
|    You need to configure ICAP protocol on port 1344 (or another)
|    to use this scanner properly.
|    These options are suggested in symcscan.cfg:
|      BindAddress=127.0.0.1
|      Port=1344
|      Protocol=ICAP
|      ExtensionPolicy=0
|      ICAPActionPolicy=SCAN
|      ICAPResponse=1

smtp_comm()
|  Primitive regexp pattern scanner for SMTP communication.
|  
|  For more information about this scanner see documentation for
|  regexp_scan realscanner.
|  
|  This scanner also can be used to apply some scnanner to defined
|  email adresses. For example:
|      smtp_comm(['D','^RCPT TO:.*anydomain.dom']])
|        & stream2mbox(libclam())
|  In this example, libclam() scanner is used only if mail is
|  adressed to an user on anydomain.dom.
|  
|  Usage: smtp_comm([['VirName','RegExp_Pattern...',...],...],flags=0)
|  
|  Where: 'VirName' is a string, which identifies defined virus
|         'RegExp_Pattern...' is a regexp pattern
|         flags is an integer, which defines regular expression flags.
|           By default re.IGNORECASE is used.

sophie()
|  Sophie realscanner.
|  
|  This scanners is a realscanner, which can be used to scan
|  for viruses. Sophie uses sophos libsavi. It can also be used
|  for Trophie with TrendMicro antivirus scanner.
|  
|  If you need a chrooted sophie, copy it into chroot and start it
|  from here. Do not forget to update it's chrooted database.
|  
|  Usage: sophie(sophie_socket,chroot_path='')
|  
|  Where: sophie_socket is a filename to sophie via UNIX socket
|         chroot_path is a path, which you need to add
|           (may be the same as your CHROOT, if you are using
|           sagator in chroot and sophie not)

string_scan()
|  Primitive string pattern scanner.
|  
|  There can be more patterns for one virus. All patterns
|  must match to assign an stream as virus.
|  There can also be more virnames in one dictionary.
|  
|  Usage: string_scan([['VirName','Pattern1...',...],...],size=0)
|  
|  Where: 'VirName' is a string, which identifies defined virus
|         'Pattern...' is a string pattern
|         size is a number, which defines, how many bytes may be checked.
|           If it is 0 or not defined, whole stream is scanned.
|           If it is -1, email header is scanned.
|    
|  Example: string_scan([
|             # Scan for a part of EICAR virus test file pattern
|             ['EICAR','X5O!P%@AP[4','EICAR-STANDARD-ANTIVIRUS-TEST-FILE'],
|             # Scan for a an EXE file pattern endoded as base64.
|             ['UnknownEXE','TVqQ']
|           ])

trophie()
|  Trophie realscanner.
|  
|  It is an alias for sophie. See sophie documentation.

== Antispam scanners
==============================

bogofilter()
|  BogoFilter scanner.
|  
|  This scanner scans for spams. If a spam is returned, a string
|  SPAM is returned as virus name.
|  
|  Usage: bogofilter(['/usr/bin/bogofilter','-v'],
|                    SPAMSTRING='',
|                    MAX_FILE_SIZE=500000)
|  
|  Where: in [] is a path and argumets of bogofilter binary
|         SPAMSTRING is a string, which define a report string,
|           which is checked. If it is found, mail is assigned as 'SPAM'
|         MAX_FILE_SIZE is a number, which defines maximum file size,
|           which can be tested. If a mail (with header) is larger,
|           it is not checked (by default 500000).

filter()
|  Filter a message through a command.
|  
|  This scanner can be used to filter email through an external program.
|  It's return status is always clean.
|  
|  Usage: filter(['/path/command_name','-options',...])
|  
|  Where: in [] is a path and argumets of filter binary

qsf()
|  Quick Spam Filter scanner.
|  
|  This scanner scans for spams. If a spam is returned, a string
|  SPAM is returned as virus name. It uses Quick Spam Filter.
|  
|  Usage: qsf(['/usr/bin/qsf','-r'],SPAMSTRING='',MAX_FILE_SIZE=500000)
|  
|  Where: in [] is a path and argumets of qsf binary
|         SPAMSTRING is a string, which define a report string,
|           which is checked. If it is found, mail is assigned as 'SPAM'
|         MAX_FILE_SIZE is a number, which defines maximum file size,
|           which can be tested. If a mail (with header) is larger,
|           it is not checked (by default 500000).

spamassassin()
|  SpamAssassin scanner.
|  
|  This scanner scans for spams. If a spam is returned, a string
|  SPAM is returned as virus name. This scanner uses a spamassassin
|  binary. For better performance, configure spamd and use
|  spamassassind.
|  
|  WARNING! You need to install spamassassin into chroot manually.
|  mkchroot.sh script does it not. If you want to use spamassasin
|  with chroot and don't want to make a copy in chroot, use
|  a spamassassind scanner, but remember, that scanning for spams
|  are not done in chroot environment.
|  
|  WARNING! This scanner is not fully compatible with header adding.
|  Some data from headers are not added!
|  
|  Usage: spamassassin(['/usr/bin/spamassassin','-e'],
|                      spamstring='',sa_max_file=500000)
|  
|  Where: in [] is a path and argumets of spamassassin binary
|         spamstring is a string, which define a spamassassin report,
|           which is checked. If it is found, mail is assigned as 'SPAM'
|           (by default all reports with exit status!=0 are reported as spam).
|         sa_max_file is a number, which defines maximum file size,
|           which can be tested. If a mail (with header) is larger,
|           it is not checked (by default 500000).

spamassassind()
|  SpamAssassin daemon scanner.
|  
|  This scanner scans for spams. If a spam is returned, a string
|  SPAM is returned as virus name.
|  This scanner uses a spamassassind daemon. If you are not familiar with it,
|  you also can use spamassassin binary. Look at spamassassin scanner.
|  
|  Usage: spamassassind(['localhost',783],reqspamlevel=-1,
|                       sa_max_file=500000,filter=False,
|                       mydestination=None,virtual_users=None)
|  
|  Where: ['localhost',783] are the host and port of spamd.
|         if reqspamlevel is less than spam hits, virus is returned,
|           if it is -1 (default), spam level from spamassassin config is used
|         for sa_max_file see spamassassin scanner description.
|         filter is an boolean whic can be used to process whole message
|           by spamassassin. New message (generated by spamassassin) will
|           be stored instead of original. It's default is False.
|         mydestination is an regular expression, which defines local domains.
|           If it is set and only one recipient is specified
|           and recipients domain matches against this regular expression,
|           then username part will be sent into spamd.
|           This parameter is new in 0.7.0.
|         virtual_users is an regular expression, which defines virtual users.
|           These users can be used to configure virtual user settings
|           for spamassassin. Only for emails with one recipient will be
|           applied.
|           This parameter is new in 0.7.0.

