1 renattach 1.2.4 - Filter that renames/deletes dangerous email attachments
2 Copyright (C) 2003-2006 Jem E. Berkes
3
4 Web site: http://www.sysdesign.ca/
5 Program page: http://www.pc-tools.net/unix/renattach/
6 Email contact: support@pc-tools.net
7
8 As per the GNU GPL, there is no warranty for this software.
9 The author makes no guarantees as to software performance or
10 effectiveness. renattach is NOT a virus scanner. Filtering
11 is based on MIME headers and detectable filenames; as such,
12 the software tries to handle both correct structures and
13 incorrectly formatted messages. This filter will not catch
14 all dangerous emails, particularly attachments embedded inside
15 attachments.
16
17
18************************************************************************
19WARNING:
20 THIS SOFTWARE HAS BEEN DISCONTINUED. IT IS NO LONGER MAINTAINED.
21************************************************************************
22
23 The author recommends that you do not depend upon renattach to
24 filter emails for dangerous content. As of 2006, renattach used
25 on its own is not enough to filter potentially harmful emails.
26 Dangerous attachments, or other attacks, may pass through the
27 filter undetected. Please switch from renattach to some other
28 actively developed security system.
29 Jem E. Berkes
30 2006-03-19
31
32************************************************************************
33
34
35renattach is a fast and efficient UNIX stream filter that can rename or
36delete potentially dangerous e-mail attachments. The filter is invoked
37as a simple pipe for use in a wide variety of systems. The 'kill' feature
38(which eliminates entire messages) can also help sites deal with resource
39strains caused by modern virus floods.
40
41renattach is written in pure C and can quickly process mail with little
42overhead. Unlike a conventional virus scanner, there are no specific virus
43or worm definitions. Instead, renattach identifies potentially dangerous
44attachments based on file extension and executable encoded body content.
45The software is even capable of reading filenames from inside ZIP archives
46on the fly, without requiring any external software. The self-contained
47MIME code parses, fully interprets, then rewrites the header of every
48attached file. During this process it checks the file's extension against
49a list, and further checks to make sure the filename is not on a banned
50list. Only after passing through these steps is the MIME header written
51fresh using a predetermined, known format.
52
53The program's operation is simple: a single mail message is read from
54stdin, filtered, then written to stdout (or piped to an external command).
55
56Tested under Linux, FreeBSD, Solaris, Mac OS X, and Cygwin. This software
57should compile on any UNIX-like system that has standard C libraries.
58
59
60FEATURES
61--------
62* Fast, lightweight, little overhead
63* Recognizes both MIME and uuencoded attachments
64* Compliant with RFC2047 and RFC2231, handles encoded filenames
65* Capable of reading filenames inside ZIP archives, on the fly
66* Can rename or delete attachments, or kill entire messages
67* Can detect executables that carry DOS/Windows signature
68* Supports list of banned filenames (great for handling floods)
69* Simple pipe/stream operation; can be used within many filtering systems
70* Can be installed directly as a content_filter for Postfix MTA
71* Can be installed as a local delivery agent for Sendmail MTA
72
73
74renattach looks for its configuration file (renattach.conf) in the path
75specified at compile time. Alternatively, you can specify the location of
76renattach.conf by using the -c command-line options. For example:
77renattach -c renattach.conf
78
79
80COMMAND USAGE
81-------------
82Note that the filter's default behaviour is to rename dangerous attachments
83that match the badlist {mode=badlist, action=rename}. If searching inside
84ZIP archives for filenames (see the search_zip configuration option), the
85only actions that modify the ZIP files are delete and kill but NOT rename.
86Therefore the default rename action has no effect on ZIP files; instead, use
87the --delete or --kill options. Alternatively, append the /d and /k switches
88to badlist extensions in the .conf file to selectively delete or kill some
89file types while just renaming the rest.
90
91(See man page for more detail on some of these command-line options)
92
93Usage: renattach [OPTIONS]
94
95 -a, --all
96 Filter mode: Match all attachments.
97
98 -b, --badlist
99 Filter mode: Only match filenames that have extensions listed on the
100 bad-list. This will match only attachments with known dangerous file
101 extensions (default).
102
103 -c, --config filename
104 Use the specified configuration file. Run renattach with --settings
105 to verify current settings.
106
107 -d, --delete
108 Filter action: Delete attachment body after renaming headers.
109
110 -e, --excode
111 Extend exitcodes: 77=filtering occurred. This is in addition to the
112 default codes: 0=success, 75=temporary failure, 255=critical failure
113
114 -g, --goodlist
115 Filter mode: Match all attachments except those that have extensions
116 listed on the goodlist.
117
118 -h, --help
119 Show help, explain options.
120
121 -k, --kill
122 Filter action: Kill (absorb) entire email.
123
124 -l, --loop
125 Remove Delivered-To headers to prevent malicious mail forwarding loop.
126
127 -p, --pipe command [args]
128 Instead of writing output to stdout, open pipe to command (with args)
129 and send output there. This program must return with exit code 0.
130 This must be the last option on the command line.
131
132 -r, --rename
133 Filter action: Rename matching attachments (default).
134
135 -s, --settings
136 Show current settings/configuration and terminate.
137
138 -v, --verbose
139 Write verbose output (including settings) to stderr.
140
141 -V, --version
142 Display software version and terminate.
143
144
145CONF FILE
146---------
147renattach reads its configuration options from renattach.conf, in your
148$sysconfdir. There are defaults for all options but you will probably want
149to tweak the configuration for your needs. The example configuration file
150renattach.conf.ex fully describes all supported configuration directives
151(in conf/ and copied to $sysconfdir by install).
152
153Configuration directives are also described in the man page.
154
155
156# Drop mail carrying executable attachments (DOS/Windows exec signature)
157delete_exe = no
158kill_exe = yes
159
160# Search for filenames inside ZIP files
161search_zip = yes
162
163# Log filtered mail (delete, kill) to syslog mail facility
164use_syslog = yes
165
166# Delete winmail (MS proprietary) attachments without modifying Subject,
167# also drop emails containing annoying scanner-generated warning bounces
168banned_files = /winmail/d, /warn.txt/k, DELETED0.TXT/k
169subj_banned = #
170
171subj_deleted = [deleted attachment]
172subj_renamed = [renamed attachment]
173
174# When these file types are encountered, rename the attachment (assuming
175# filter is invoked with default action=rename). However, kill mail containing
176# any BAT, COM, etc. attachments even if they are inside ZIP files. There is
177# risk of collateral damage. EML//d means delete ZIPs that contain EML.
178badlist = ADE, ADP, BAS, BAT/k, CHM, CMD/k, COM/k, CPL/k, CRT, EML//d, EXE/k
179badlist = HLP, HTA/k, HTM, HTML, INF, INS, ISP, JS, JSE, LNK, MDB
180badlist = MDE, MSC, MSH, MSI, MSP, MST, NWS, OCX, PCD, PIF/k, REG/k
181badlist = SCR/k, SCT, SHB, SHS, URL, VB, VBE, VBS/k, WSC, WSF, WSH
182