Update documentation regarding amavis patching

Remove references to patched amavis and replace with the new
ask_peekaboo plugin. Include the ask_peekaboo amavis plugin here. Add
documentation on AMaViS version requirements.

5 files changed, 123 insertions, 37 deletions

diff --git a/README.md b/README.md
index 51b80ff..8539558 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ For news and announcements follow us on twitter [@peekabooAV](https://twitter.co
 
 * [Python 2.7](https://www.python.org/downloads/)
 * [Cuckoo 2.0](https://github.com/cuckoosandbox/cuckoo)
-* Our [AMaViSd](https://github.com/scVENUS/PeekabooAV-amavisd) Fork
+* [AMaViSd 2.11.0](https://www.ijs.si/software/amavisd/)
 
 
 ### Installation ###
diff --git a/amavis/10-ask_peekaboo b/amavis/10-ask_peekaboo
new file mode 100644
index 0000000..f9eba70
--- /dev/null
+++ b/amavis/10-ask_peekaboo
@@ -0,0 +1,101 @@
+use strict;
+use File::Copy;
+
+# base directory where dump_info() will put its stuff
+my $dump_info_tempdir = '/tmp';
+
+# dump_info creates a .info file for every processed attachment that contains
+# internal meta information determined by amavis. It can be used by
+# av_scanners. E.g. for behavioural analysis checking in sandboxes where the
+# original file extension is required.
+#
+# example: p002.info
+#
+# [attachment]
+# full_name:     : /var/lib/amavis/tmp/amavis-20170427T174709-03863-dIJwSsyE/parts/p002
+# name_declared: : hugo.txt
+# type_declared: : text/plain
+# type_long:     : ASCII text
+# type_short:    : asc
+# size:          : 14
+# digest:        : fecf3151ca5ce7b9d24defdc140edc0eefaaeaed:text/plain
+# attributes:    : 
+# queue_id:      : 96C866A02E4
+sub dump_info($$$) {
+  my ($part, $tempdir, $own_tempdir) = @_;
+
+  my $full_name = $part->full_name;
+  my $base_name = $part->base_name;
+  my $dir_name  = $part->dir_name;
+
+  # redirect amavis tempdir into our tempdir but keep intermediate path
+  # components ->/var/lib/amavis/tmp/amavis-20180822T155830-07760-4DfB2yxI/parts ->
+  # /tmp/amavis-20180822T155830-07760-4DfB2yxI/parts
+  $dir_name =~ s|^$tempdir/|$own_tempdir/|;
+  # remove /parts subdir component from end
+  $dir_name =~ s|/parts$||;
+
+  unless (-d $dir_name || mkdir($dir_name, 0770)) {
+    Amavis::Util::do_log(-1, "WARN: Couldn't create info dir $dir_name: $!");
+    return 0;
+  }
+
+  my $info_file = "$dir_name/$base_name.info";
+  my $info_fh;
+  unless (open($info_fh, ">:encoding(UTF-8)", $info_file)) {
+    Amavis::Util::do_log(-1, "WARN: Couldn't create info file $info_file: $!");
+    return 0;
+  }
+
+  printf $info_fh "[attachment]\n";
+  for my $field (qw(
+               full_name
+               name_declared
+               type_declared
+               type_long
+               type_short
+               size
+               digest
+               attributes
+               queue_id
+              )) {
+    my $val = $part->can($field) ? $part->$field() : $Amavis::MSGINFO->$field();
+    $val = ref $val eq 'ARRAY' ? $val->[-1] : $val;
+    $val = Amavis::Util::safe_decode_mime($val) if $field eq "name_declared";
+    printf $info_fh "%-15s: %s\n", "$field", $val;
+  }
+  close $info_fh;
+
+  unless (copy($full_name, $dir_name)) {
+    Amavis::Util::do_log(-1, "WARN: couldn't copy $full_name to $dir_name");
+    return 0;
+  }
+
+  return 1;
+}
+
+sub ask_peekaboo {
+  my($bare_fnames, $names_to_parts, $tempdir, $dummy) = @_;
+
+  # default to /tmp but let dump_info_tempdir override
+  my $own_tempdir = '/tmp';
+  $own_tempdir = $dump_info_tempdir if defined $dump_info_tempdir;
+
+  # remove everything after and including last slash (job identifier in e.g.
+  # /var/lib/amavis/tmp/amavis-20180822T155830-07760-4DfB2yxI) to get amavis
+  # tempdir
+  $tempdir =~ s|/+[^/]+$||;
+
+  # dump out some additional info for peekaboo
+  foreach my $part (values %{$names_to_parts}) {
+    unless (dump_info($part, $tempdir, $own_tempdir)) {
+      # signal virus scanning failure if info can't be dumped
+      return (undef, '', undef);
+    }
+  }
+
+  # use standard daemon socket communication to trigger peekaboo
+  ask_daemon(@_);
+}
+
+1;  # ensure a defined return value
diff --git a/amavis/README.md b/amavis/README.md
new file mode 100644
index 0000000..16435ac
--- /dev/null
+++ b/amavis/README.md
@@ -0,0 +1,5 @@
+# amavis extension files #
+
+This directory contains extensions to amavis necessary for seamless integration
+of Peekaboo. This currently is a small plugin which dumps out additional meta
+information needed by Peekaboo before submitting the sample for analysis.
diff --git a/docs/source/config.rst b/docs/source/config.rst
index bbcf723..ad95b6a 100644
--- a/docs/source/config.rst
+++ b/docs/source/config.rst
@@ -103,7 +103,7 @@ Helpers & 3rd Party Applications
 Peekaboo requires a little tool called ``chwon2me`` in order to change the ownership of files and directories
 to be analyed by Peekaboo.
 Also, Peekaboo can run behavioural analysis of file and directories by utilizing Cuckoo sandbox for this purpose.
-Further, email attachments can be supplied to Peekaboo for analysis using our patched version of AMaViSd.
+Further, email attachments can be supplied to Peekaboo for analysis directly from AMaViSd.
 
 The remaining sections cover the setup of these components.
 
@@ -124,35 +124,10 @@ Please refer to the Cuckoo documentation available at https://cuckoo.sh/docs/ind
 
 AMaViSd
 -------
-First, replace your AMaViSd with our patched version of AMaViSd. To do so, download the AMaViSd 2.11.0 source code
-and extract ``amavisd.conf-default`` and ``amavisd``.
-
-.. code-block:: shell
-
-    curl https://www.ijs.si/software/amavisd/amavisd-new-2.11.0.tar.xz -o amavisd-new-2.11.0.tar.xz
-    tar xvf amavisd-new-2.11.0.tar.xz  amavisd-new-2.11.0/amavisd.conf-default
-    tar xvf amavisd-new-2.11.0.tar.xz  amavisd-new-2.11.0/amavisd
-
-Now, you can apply our patch.
-
-.. code-block:: shell
-
-    cd amavisd-new-2.11.0/
-    patch -p4 < ../peekaboo-amavisd.patch
-    patch -p1 < ../debian-find_config_files.patch
-    mv amavisd /usr/sbin/amavisd-new
-
-
-Next, edit ``/etc/amavis/amavis.conf``:
-
-.. code-block:: perl
-   
-   $mydomain = 'peekaboo.test';
-   $myhostname = 'host.peekaboo.test';
-   
-   # Optional for development if you want to receive the results of AMaViSd via email
-   $notify_method = 'smtp:[127.0.0.1]:10025';
-   $forward_method = 'smtp:[127.0.0.1]:10025'; 
+First, install the ``10-ask_peekaboo`` plugin as
+``/etc/amavis/conf.d/10-ask_peekaboo``.
+It is available from the ``amavis`` subdirectory of the PeekabooAV installation
+and has been tested with AMaViS 2.11.0.
 
 
 Put the following code into ``/etc/amavis/conf.d/15-av_scanners``:
@@ -161,7 +136,7 @@ Put the following code into ``/etc/amavis/conf.d/15-av_scanners``:
 
     @av_scanners = (
         ['Peekaboo-Analysis',
-        \&ask_daemon, ["{}\n", "/var/lib/peekaboo/peekaboo.sock"],
+        \&ask_peekaboo, ["{}\n", "/var/lib/peekaboo/peekaboo.sock"],
         qr/wurde als "(unknown|checked|good|ignored)" eingestuft/m,
         qr/wurde als "bad" eingestuft/m ],
     );
@@ -185,15 +160,20 @@ and for mail notifications for the user ``peekaboo`` add this line to
    
    $virus_admin = 'peekaboo';
 
-Let AMaViSd use unique directories for temporary files. This configuration is mandatory for Peekaboo.
-So, edit ``/etc/amavis/conf.d/50-user``:
+Next, create an ``/etc/amavis/conf.d/50-peekaboo`` and fill it with:
 
 .. code-block:: perl
    
+   # force a fresh child for each request
    $max_requests = 1;
-   $enable_dump_info  = 1;       # set to 1 to enable dump_info feature
-   $dump_info_tempdir = '/tmp';  # base directory where dump_info() will put its stuff
 
+   # if not autodetectable or misconfigured, override hostname and domain
+   $mydomain = 'peekaboo.test';
+   $myhostname = 'host.peekaboo.test';
+
+   # Optional for development if you want to receive the results of AMaViSd via email
+   $notify_method = 'smtp:[127.0.0.1]:10025';
+   $forward_method = 'smtp:[127.0.0.1]:10025';
 
 Finally, restart AMaViSd
 
diff --git a/docs/source/install.rst b/docs/source/install.rst
index 36a2181..dbcd389 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -4,7 +4,7 @@ Installation
 
 This chapter explains how to install Peekaboo and its dependencies.
 In this chapter we assume that you want to use Peekaboo's extended capabilities to perform behavioural analysis of
-files and directores with Cuckoo. Further, we assume that you want to install AMaViSd and our patch for it to run
+files and directores with Cuckoo. Further, we assume that you want to install AMaViSd to run
 analysis of email attachments. Also, we assume that you use a Debian based Linux distribution.