Provided by: renattach_1.2.4-3_amd64 bug

NAME

       renattach - rename/delete dangerous email attachments

SYNOPSIS

       renattach [OPTIONS]

DESCRIPTION

       renattach is a fast and efficient 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 software is even capable of reading filenames from
       inside ZIP archives on the  fly,  without  requiring  any  external  software.  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).

       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

OPTIONS

       Note that the filter's default behaviour is to rename dangerous attachments that match the
       badlist {mode=badlist, action=rename}. If searching inside ZIP archives for filenames (see
       the  search_zip  configuration  option),  the  only  actions that modify the ZIP files are
       delete and kill but NOT rename.  Therefore the default rename action has no effect on  ZIP
       files;  instead,  use  the --delete or --kill options. Alternatively, append the /d and /k
       switches to badlist extensions in the .conf file to selectively delete or kill  some  file
       types while just renaming the rest.

       -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. Run renattach with --settings to  verify  the
              current settings.

       -d, --delete

              Filter action: Delete attachment body after renaming headers.

       -e, --excode

              Extend  exitcodes  with  a  new code, 77=filtering occurred. See below for standard
              exit codes.

       -g, --goodlist

              Filter mode: Match all attachments except those that have extensions listed on  the
              goodlist.

       -h, --help

              Show help, explain options.

       -k, --kill

              Filter action: Kill (absorb) entire email. There is null output.

       -l, --loop

              Remove  Delivered-To  headers  to prevent malicious mail forwarding loop.  This can
              prevent Postfix from inadvertently relaying spam. This option  must  only  be  used
              when  renattach  is  a filter service to the outside world, otherwise you will lose
              loop protection. Do not use from procmail.

       -p, --pipe command [args]

              Instead of writing output to stdout, open pipe to  command  (with  args)  and  send
              output  there.  This  program  must  return with exit code 0. This must be the last
              option on the command line. See INSTALL file for instructions on  integrating  with
              Postfix as a filter service.

       -r, --rename

              Filter action: Rename matching attachments (default). The MIME type is also renamed
              to new_mime_type from the .conf file.

       -s, --settings

              Show current settings/configuration and terminate.

       -v, --verbose

              Write verbose output (including settings) to stderr.

       -V, --version

              Display software version and terminate.

EXIT CODES

       0 - Success (filtered mail and wrote output)

       75 - Temporary failure (resource shortage; failed to write to pipe if using --pipe )

       255 - Critical failure (improper parameters; bad .conf file)

       The temporary failure code allows MTAs to re-queue mail for  later  delivery.  These  exit
       codes  are compatible with BSD-style mailers, and --excode should not be used without good
       reason because it returns a non-success code when the filter "catches" something.

CONFIGURATION FILE

       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  are
       compiled into the software.

       NOTE: please run renattach --settings to verify your configuration!

       Description of all options:

       # renattach 1.2.4 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

       # Kill executable binary attachments by signature, as in the previous
       # directive. Note that delete_exe and kill_exe are mutually exclusive.
       #
       # kill_exe = no

       # Search for filenames within ZIP archives using the internal ZIP
       # parsing engine (no external software required). Any filenames found
       # are subject to the same checks, for instance badlist or goodlist,
       # with the notable difference that the RENAME ACTION HAS NO EFFECT on
       # ZIP files. Only the delete or kill actions will modify ZIP files.
       #
       # search_zip = no

       # Normally, MIME Content-ID fields are dropped during filtering due
       # to their application-specific use and security risk (recently used
       # by worms to link malicious code to embedded images). If you are sure
       # you want to pass Content-ID fields unfiltered, enable this option.
       #
       # pass_contentid = no

       # Normally, all periods in filenames are replaced with underscores
       # during renaming. Although this is the recommended mode, you can
       # also disable full renaming if you only want the last period to be
       # changed to an underscore.
       #
       # full_rename = 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
       # Specify just # to leave the extension as is, and not rename it.
       #
       # 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 inserting a warning into HTML parts of messages (warning_html),
       # this tag defines the preferred position to insert the new HTML. If
       # the first tag in the list is found, the warning position is placed
       # just after this tag. As subsequent tags are found, the position
       # advances after each.
       #
       # htmlwarn_pos = html, body

       # If an attachment is filtered, this lets you specify some warning
       # text that will be inserted into any plain text portion(s) of the
       # email. This is effective for informing users of filtered files,
       # but the act of inserting arbitrary text into an email can cause
       # new problems. Use with caution.
       #
       # warning_text =    *******************
       # warning_text =    MAIL SYSTEM WARNING
       # warning_text =    Attachments removed
       # warning_text =    *******************

       # Inserts a warning message into HTML portions of the email when
       # filtering occurs. The HTML is inserted at a position determined by
       # htmlwarn_pos (see above) which provides a good hope for adding a
       # visible warning. Unfortunately, inserting arbitrary HTML is tricky
       # due to the complexity of markup interactions. Inserting warnings in
       # HTML may thoroughly disrupt the original message, so use with caution.
       #
       # warning_html =    <h1>Mail system warning<h1>
       # warning_html =    <h2>Attachments removed</h2>

       # 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.
       # An additional switch can be used to specify an action only for
       # files found within ZIP archives. For instance, EXE/k/d tells the
       # filter to kill emails containing EXE attachments, but if the EXE
       # was found inside a ZIP then the attachment is deleted, not killed.
       #
       # 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

FILES

       renattach.conf

SEE ALSO

       procmail(1)

WARRANTY

       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 and detectable filenames; as such, the software tries
       to handle both correct structures and incorrectly formatted messages. This filter will not
       catch all dangerous emails, particularly attachments embedded inside attachments.

AUTHOR

       Copyright (C) 2003-2006  Jem E. Berkes <jberkes@pc-tools.net>

       http://www.pc-tools.net/unix/renattach/
       http://www.sysdesign.ca/