Decidim::Antivirus

A Decidim module to add antivirus checks as validations for Decidim's public file uploads, e.g. for proposals.

The antivirus checks are done through ClamAV using Clamby.

The antivirus validation is handled by Ratonvirus.

The gem has been developed by Mainio Tech.

The development has been sponsored by the City of Helsinki.

Prerequisites

You need to have ClamAV installed on the target machine for the antivirus checks to actually work. With the default configuration, you will also need the ClamAV daemon installed in order to make the antivirus checks more efficient.

Check ClamAV installation and configuration instructions from:

https://github.com/mainio/ratonvirus-clamby

This documentation also contains a section about testing the virus detection without installing the ClamAV application. Refer to the "Testing without installing ClamAV" section of that documentation if you want to do this for development purposes.

Installation

Add this line to your application's Gemfile:

gem "decidim-antivirus"

And then execute:

$ bundle

After installation, test that the gem is loaded properly in your environment and it can run the ClamAV executable:

$ bundle exec rails ratonvirus:test

This command should show the following message when correctly installed:

Ratonvirus correctly configured.

Usage

This gem provides a new validator named AntivirusValidator which can be used to attach antivirus checks to any CarrierWave connected file attributes.

This is automatically added to the Decidim's own Decidim::Attachment model to check any files that the users upload as attachments to any records, e.g. proposals.

If this is all you need, you are all set after installing this gem.

NOTE:

The custom validator is applied automatically only if you have configured the ClamAV daemon correctly for checking the files. In case the ClamAV executable clamdscan is not available on the target machine, this gem does nothing.

Testing from the UI

In order to test that the functionality is working correctly, follow these steps:

1. Create an EICAR test file with one of the Decidim's supported files extensions (e.g. .pdf).
2. Install Decidim with this gem and create the development app. In case you have an existing instance.
3. Run the development server bundle exec rails s.
4. Add the Proposals component to one of your participatory spaces and enable attachments for the component and proposal creation for the active step.
5. Go to the component URL and create a new proposal. Define the EICAR test file in the attachement's file field in the final "complete" step.
6. Try posting the Proposal form.

In case the validator is working correctly, you should see an error saving the proposal and when you scroll the page down, you should also see the following validation error in the file field:

File contains a virus

Adding antivirus checks to custom models

In case you want to attach any other models to the AntivirusValidator, it is also possible. For example, if you have the following type of model locally in your installation:

class CustomModel < Decidim::ApplicationRecord
  validates :image, :content_type, presence: true
  mount_uploader :image, Decidim::AttachmentUploader
end

You can apply the AntiVirusValidator to that model by adding the following line to the class:

  validates :image, antivirus: true

Contributing

See Decidim.

Testing

To run the tests run the following in the gem development path:

$ bundle
$ DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rake test_app
$ DATABASE_USERNAME=<username> DATABASE_PASSWORD=<password> bundle exec rspec

Note that the database user has to have rights to create and drop a database in order to create the dummy test app database.

In case you are using rbenv and have the rbenv-vars plugin installed for it, you can add these environment variables to the root directory of the project in a file named .rbenv-vars. In this case, you can omit defining these in the commands shown above.

Test code coverage

If you want to generate the code coverage report for the tests, you can use the SIMPLECOV=1 environment variable in the rspec command as follows:

$ SIMPLECOV=1 bundle exec rspec

This will generate a folder named coverage in the project root which contains the code coverage report.

License

See LICENSE-AGPLv3.txt.