===============
django-avsubmit
===============

django-avsubmit is an application written for Django to allow security response
groups (CIRTs, SOCs, etc.) to easily upload and submit malicious code samples
to antivirus vendors and other security research partners.


Setup
=====

Requirements
------------

- Django. This application was developed and tested with Django 1.3. Other
  versions are likely to work. Testing is encouraged.
- Zip functionality requires that the ubiquitous ``zip(1)`` (Info-ZIP) or
  ``7z(1)`` (7-Zip) binary be installed. Since encrypted archives are created,
  Python's standard ``zipfile`` module won't do.
- The Unix ``file(1)`` binary, due to the fact that libmagic support is difficult
  on some platforms.
- Default templates make use of `Bootstrap <http://twitter.github.com/bootstrap/>`_
  for styling. You can either keep the default templates and add Bootstrap
  static content if you don't use it already, or override the default templates.
- Templates also make use of jQuery for minor functionality such as setting focus
  on form fields and toggling non-critical controls. It is recommended to have
  jQuery available in the project.
- Email delivery from the server hosting this app should be functional. Care is
  taken to ensure that emailed samples pass through mail systems which may filter
  attachments; samples are encrypted, a generic file extension of '.bin' is used
  on every file (to avoid content filters that look for .exe in ZIP headers), and
  an upload size limit is required to be set. Nonetheless, it is possible that
  MTAs in the delivery chain between sender and recipient could still filter more
  aggressively than anticipated. Note that the file details log indication of
  successful deliveries only intends to mean that the mail was successfully
  accepted for delivery by the SMTP server that Django initially connects to.
  Deliveries to subsequent SMTP relays could result in the message being filtered
  and no effort is made to handle these failures. When in doubt, test and verify.


Installation
------------

If installing from source, unpack the distribution tarball and then install as
follows::

    python setup.py build
    python setup.py install

django-avsubmit can then be hooked into a Django project (site) as follows:

1. Add the application to INSTALLED_APPS in your project's ``settings.py``
   file.::

    INSTALLED_APPS = (
        ...
        'avsubmit',
    )

2. Add application settings to ``settings.py``. The following minimum settings
   are required for functionality::

    AVSUBMIT_SETTINGS = {
        # maximum size to accept for file uploads as AV sample submissions
        'max_upload_size': '5242880',  # 5 MB
        # envelope sender address for sample submission emails
        'sender_address':  'cirt-samples@example.net',
    }

   Additional options are available for changing other settings such as the
   encryption passphrase for the ZIP. See ``docs/README_settings.txt`` for more.

3. Add the application's URLconf into your project's own, typically by adding
   to ``urls.py``.::

    urlpatterns = patterns('',
        ...
        url(r'^avsubmit/', include('avsubmit.urls')), 
    )

4. Run ''python manage.py syncdb'' to create table schemas.


Configuration and use
---------------------

Before samples may be submitted, one or more "submission targets" must be
added with email address and enabled. This is currently done in the Django
admin application.

With a target available for delivery, application use should be straight-
forward. Users who have the **submit_file** privilege for the app may
upload and dispatch samples.

