 renattach 1.2.0 - Filter that renames/deletes dangerous email attachments
 Copyright (C) 2003  Jem E. Berkes <jberkes at pc-tools dot net>
 http://www.pc-tools.net/unix/renattach/

		Post address:	PO Box 422 RPO Corydon
				Winnipeg, MB  R3M 3V3
				Canada
		Web site:	http://www.sysdesign.ca/

	NOTE: As per the GNU GPL, there is no warranty for this software.
	The author makes no guarantees as to software performance or
	effectiveness. renattach is NOT a virus scanner. Filtering is 
	based on MIME headers; as such, the software tries to handle all 
	correct and many possible INCORRECT uses of MIME. Given the near-
	infinite cases, it's impossible to achieve 100% accuracy.


renattach is a UNIX stream filter that can rename or delete potentially
dangerous e-mail attachments. It's a highly effective way of protecting
end-users from harmful mail content (worms/viruses) by disabling or
removing attachments that may be accidentally executed by users. The
filter is invoked as a simple pipe for use in a wide variety of systems.
The 'kill' feature (which eliminates entire messages) can also help sites
deal with resource strains caused by modern virus floods.

renattach is written in pure C and can quickly process mail with little
overhead. Unlike a conventional virus scanner, there are no specific virus
or worm definitions. Instead, renattach identifies potentially dangerous
attachments based on file extension and executable encoded body content.
The self-contained MIME code parses, fully interprets, then rewrites the
header of every attached file. During this process it checks the file's
extension against a list, and further checks to make sure the filename is
not on a banned list. Only after passing through these steps is the MIME
header written fresh using a predetermined, known format.

Tested under Linux, Solaris, Mac OS X (Darwin), and Cygwin. This software
should compile on any UNIX-like system that has standard C libraries.


FEATURES
--------
* Fast, lightweight, little overhead
* Recognizes both MIME and uuencoded attachments
* Compliant with RFC2047 and RFC2231, handles encoded filenames
* Can rename or delete attachments, or kill entire messages
* Can detect executables that carry DOS/Windows signature
* Supports list of banned filenames (great for handling floods)
* Simple pipe/stream operation; can be used within many filtering systems
* Can be used directly as a content_filter for Postfix MTA


renattach looks for its configuration file (renattach.conf) in the path
specified at compile time. Alternatively, you can specify the location of
renattach.conf by using the -c command-line options. For example:
renattach -c renattach.conf


COMMAND USAGE
-------------
Usage: renattach [OPTIONS]

  -a, --all
        Filter mode: Match all attachments.

  -b, --badlist
        Filter mode: Only match filenames that have extensions listed on the
        bad-list. This will match only attachments with known dangerous file
        extensions (default).

  -c, --config filename
        Use the specified configuration file.

  -d, --delete
        Filter action: Delete attachment body after renaming headers.

  -e, --excode
        Extend exitcodes: 1=filtering occurred. This is in addition to the
        default codes: 0=success, 75=temporary failure, 255=critical failure

  -g, --goodlist
        Filter mode: Match all attachments except those that have extensions
        listed on the good-list.

  -h, --help
        Show help, explain options.

  -k, --kill
        Filter action: Kill (absorb) entire email.

  -p, --pipe "command [options]"
        Instead of writing filtered output to stdout, open a pipe to the
        indicated command and send output there (for example, sendmail).

  -r, --rename
        Filter action: Rename matching attachments (default).

  -s, --settings
        Show current settings/configuration and terminate.

  -v, --verbose
        Write verbose output (including settings) to stderr.

  -V, --version
        Display software version and terminate.


CONF FILE SYNTAX
----------------
The .conf file should be a plaintext file with one configuration directive
per line. Comments preceded by # will be ignored. Some directives may only
appear once, while others (lists) are additive. The conf file and all
directives are optional, as defaults as compiled into the software.
NOTE: please run 'renattach --settings' to verify your configuration!

#	renattach 1.2.0 recognizes the following configuration directives

#	Delete executable binary attachments when detected. renattach
#	looks for encoded headers that identify DOS/Windows executables. 
#	If an executable is found, the encoded attachment will be removed
#	while the MIME header remains unchanged. This is a feature that 
#	works independently of filename-based filtering, designed as a 
#	backup. The net effect is that encoded executables are deleted.
#	Specify yes or no, or alternatively 1 or 0
# delete_exe = yes


#	If enabled, all filtering actions will be logged via syslog.
# use_syslog = no


#	A generic filename to use when parsing fails. Since renattach 
#	rewrites all attachment headers, it's possible that corruption, 
#	lack of buffer space, or some other problem will prevent filenames
#	from being recreated. In such a case, this generic name is used.
# generic_name = filename


#	A replacement file extension to use when changing dangerous 
#	attachment filenames. This extension is appended to the previous 
#	one. For instance virus.pif becomes virus_pif.bad
# new_extension = bad


#	When attachments are renamed, the MIME type is also changed to 
#	this new_mime_type for safety.
# new_mime_type = application/unknown


#	When enabled, this text will be prepended to the message subject
#	to alert the user that filtering occurred.
# add_subject = [filtered]


#	When enabled, these new headers will be added to the message to
#	inform the user about filtering that occurred.
# add_header = X-Filtered-0:  *** PLEASE NOTE ***
# add_header = X-Filtered-1:  Potentially dangerous attachments have been 
# add_header = X-Filtered-2:  found in this e-mail, and have either been
# add_header = X-Filtered-3:  renamed or deleted for your safety.


#	Catch specifically named, banned attachment filenames and 
#	optionally take an action (r=rename, d=delete, k=kill). This is
#	an additive option so there is no limit to how many names can be
#	specified. If the name begins with a forward slash ('/'), this
#	substring has to be found; '/foo' matches 'foobar' and 'eatfoo'
#	Otherwise, the whole name has to match. Specify case-insensitive
#	filenames separated by commas. To specify an action on matching 
#	filename, append /r (rename), /d (delete), or /k (kill) to the 
#	filename as illustrated in the example.
# banned_files = your_details.zip/r, your_details.pif/k
# banned_files = movie.pif/d, movie.zip, /winmail/d


#	A list of good (known-safe) attachment file extensions to use
#	in goodlist filtering mode. This is an additive option, so there
#	is no limit to how many filenames can be specified. Specify case-
#	insensitive extensions separated by commas.
# goodlist = DOC, PDF, RTF, SXC, SXW, TXT, ZIP


#	A list of bad (known-dangerous) attachment file extensions to use
#	in badlist filtering mode. This is an additive option, so there
#	is no limit to how many filenames can be specified. Specify case-
#	insensitive extensions separated by commas.
# badlist = ADE, ADP, BAS, BAT, CHM, CMD, COM, CPL, CRT, EML, EXE
# badlist = HLP, HTA, HTM, HTML, INF, INS, ISP, JS, JSE, LNK, MDB
# badlist = MDE, MSC, MSH, MSI, MSP, MST, NWS, OCX, PCD, PIF, REG
# badlist = SCR, SCT, SHB, SHS, URL, VB, VBE, VBS, WSC, WSF, WSH

