 renattach 1.2.0 - Filter that renames/deletes dangerous email attachments
 Copyright (C) 2003  Jem E. Berkes <jberkes@pc-tools.net>

		Post address:	Jem E. Berkes
				PO Box 422 RPO Corydon
				Winnipeg, MB  R3M 3V3
				Canada
		Web site:	http://www.sysdesign.ca/
		Program page:	http://www.pc-tools.net/unix/renattach/

	FUNDING DEVELOPMENT. I enjoy developing high quality software and 
	making it available free to the public, but this requires a huge
	time commitment on my part. If you find my software useful, please 
	consider purchasing one or more copies to help support future 
	development. Because the software is released under the GNU GPL, 
	you will have the same source code and same rights of use whether 
	or not you pay me anything. However, purchasing a copy will get 
	you a comprehensive PDF manual (+updates) as well as priority on 
	email technical support, although I can not guarantee technical
	support due to limited resources. Please see the Program page URL 
	above for information on how to make a contribution.

	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.

The program's operation is simple: a single mail message is read from 
stdin, filtered, then written to stdout (or piped to an external command).

Tested under Linux, FreeBSD, Solaris, Mac OS X, 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 installed directly as a content_filter for Postfix MTA
* Can be installed as a local delivery agent for Sendmail 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: 77=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 by signature. renattach looks
#	for encoded bytes that identify DOS/Windows executables ('MZ').
#	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.
#	renattach logs with priority 'warning' to facility 'mail'
# 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


#	The following directives control how the message Subject is 
#	modified to inform the user that filtering has occurred. They
#	have the following ORDER OF PRIORITY (starting with highest):
#	subj_banned, subj_exec, subj_deleted, subj_renamed, add_subject
#	By default, only add_subject is defined so any condition (whether
#	it's a ban, executable match, delete, or rename) results in the
#	same Subject addition. If you also define subj_exec then there 
#	could be a different Subject if an executable was caught (since
#	it has higher priority than add_subject). Another alternative for 
#	these options is to specify the single character # to suppress
#	Subject modification for that condition. You could use this to be 
#	quiet in case a banned attachment is caught. You can also use # to 
#	turn off add_subject, hence NEVER modify the message Subject.

#	Add text to Subject if an attachment is caught by banned_files,
#	shown here in suppression mode to NOT inform user on file ban.
# subj_banned = #

#	Add text to Subject if an attachment is caught by delete_exe
# subj_exec = [removed executable]

#	Add text to Subject if an attachment is deleted for any reason
# subj_deleted = [deleted attachment]

#	Add text to Subject if an attachment is renamed for any reason
# subj_renamed = [renamed attachment]

#	Add text to Subject if an attachment is filtered in any way. This 
#	has lowest priority, and is only used if previous are undefined.
#	Use single character # to suppress addition to Subject.
# 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. To specify an action 
#	for an extension, append /r (rename), /d (delete), or /k (kill)
#	to the filename. This overrides the default action for the filter 
#	and can be used to provide special handling for some extensions.
#	To handle worm floods, try: badlist=EXE/k
# 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

