This add-on is operated by Clear Edge Software Ltd.

Anti-virus for developers. Scan uploads for viruses, malware and more.

Last updated May 01, 2020

Attachment Scanner is an add-on that allows you to scan user-uploaded content for viruses, malware, and other malicious files. It’s anti-virus for developers.

Using our JSON API, you can start scanning securely in minutes. It’s also possible to confine scans to a single region if required. From the Attachment Scanner dashboard, you can see a full history of your scans and any findings.

You can use Attachment Scanner with any programming language that supports REST APIs (including Java, Ruby, Python, Node.js, PHP, and Go).

Provisioning the add-on

Attachment Scanner can be attached to a Heroku application via the CLI:

$ heroku addons:create attachment-scanner
-----> Adding attachment-scanner to sharp-mountain-4005... done, v18 (free)

After you provision Attachment Scanner, the ATTACHMENT_SCANNER_URL and ATTACHMENT_SCANNER_API_TOKEN config vars are available in your app’s configuration.

These config vars contain the JSON API’s base URL and your API token needed to communicate with the API. You can confirm this via the heroku config:get command:

$ heroku config:get ATTACHMENT_SCANNER_URL
https://clustername.attachmentscanner.com

$ heroku config:get ATTACHMENT_SCANNER_API_TOKEN
123456

After you install Attachment Scanner, your application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After you provision the add-on, it’s necessary to locally replicate its config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config vars, type heroku config. Use the following command for each value that you want to add to your .env file:

$ heroku config:get ATTACHMENT_SCANNER_URL -s  >> .env
$ heroku config:get ATTACHMENT_SCANNER_API_TOKEN -s  >> .env

For more information, see the Heroku Local article.

Initiating a scan

The Attachment Scanner API lets you specify a file to scan either by providing a publicly accessible URL for the file, or by uploading the file in a multipart/form-data request.

The following cURL request demonstrates providing the URL of a file to scan:

$ curl --request POST \
  --url ATTACHMENT_SCANNER_URL/requests \
  --header 'authorization: bearer ATTACHMENT_SCANNER_API_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"url":"http://www.attachmentscanner.com/eicar.com"}'

{"id":"045709af-ce64-40f0-8f85-7cdbfcd15554","status":"found","matches":["Eicar-Test-Signature"],"created_at":"2017-04-04T12:14:43.888Z","updated_at":"2017-04-04T12:14:43.955Z","callback":null,"url":"http://www.attachmentscanner.com/eicar.com","filename":"eicar.com","content_length":70,"md5":"e7e5fa40569514ec442bbdf755d89c2f"}

The following cURL request demonstrates uploading a file in a multipart/form-data request:

$ curl --request POST \
  --url ATTACHMENT_SCANNER_URL/requests \
  --header 'authorization: bearer ATTACHMENT_SCANNER_API_TOKEN' \
  --header 'content-type: multipart/form-data' \
  --form @./PATH_TO_FILE

{"id":"57b8a020-fcd6-4fc1-8c3d-cadfed0f5059","status":"found","matches":["Eicar-Test-Signature"],"created_at":"2017-04-04T12:22:11.728Z","updated_at":"2017-04-04T12:22:11.773Z","callback":null,"url":null,"filename":"eicar.com","content_length":70,"md5":"e7e5fa40569514ec442bbdf755d89c2f"}

Obtaining the result of a scan

The JSON object provided in the API’s response to your scan request includes a status field with one of the following values:

Using with Ruby

require 'faraday'
require 'faraday/middleware'

def scan_connection
  Faraday.new(ENV['ATTACHMENT_SCANNER_URL']) do |f|
    f.request :multipart
    f.request :url_encoded
    f.authorization :Bearer, ENV['ATTACHMENT_SCANNER_API_TOKEN']
    f.response :json
    f.response :raise_error
    f.adapter :net_http
  end
end

def scan(path_to_file, content_type, filename)
  upload = Faraday::UploadIO.new(path_to_file, content_type, filename)
  response = scan_connection.post('/requests', file: upload)
  puts response.body
end

Using with CarrierWave

AttachmentScanner has a specific gem for working with CarrierWave called CarrierWave::AttachmentScanner

Add the gem using:

gem 'carrierwave-attachmentscanner'

then bundle:

$ bundle

Generate your config:

$ bundle exec rails generate carrierwave_attachmentscanner:config

The created configuration will pull your credentials from the ENV variables created by the add-on. You can then include the following in your uploaders or the base uploader:

class YourUploader < CarrierWave::Uploader::Base
  include CarrierWave::AttachmentScanner
end

This will then scan the uploaded files for viruses and malware blocking any files with a found status.

Using with Python

To use Attachment Scanner in a Python app, you just need to make an HTTP POST to the requests endpoint:

import requests

url = "https://ATTACHMENT_SCANNER_URL/requests"

payload = "{\"url\":\"http://www.attachmentscanner.com/eicar.com\"}"
headers = {
    'content-type': "application/json",
    'authorization': "bearer ATTACHMENT_SCANNER_API_TOKEN"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Using with NodeJS

To use Attachment Scanner in a Node app, you just need to make an HTTP POST to the requests endpoint:

var unirest = require("unirest");

var req = unirest("POST", "https://ATTACHMENT_SCANNER_URL/requests");

req.headers({
  "authorization": "bearer ATTACHMENT_SCANNER_API_TOKEN",
  "content-type": "application/json"
});

req.type("json");
req.send({
  "url": "http://www.attachmentscanner.com/eicar.com"
});

req.end(function (res) {
  if (res.error) throw new Error(res.error);

  console.log(res.body);
});

Using with Java

To use Attachment Scanner in a Java app, you just need to make an HTTP POST to the requests endpoint:

HttpResponse<String> response = Unirest.post("https://ATTACHMENT_SCANNER_URL/requests")
  .header("content-type", "application/json")
  .header("authorization", "bearer ATTACHMENT_SCANNER_API_TOKEN")
  .body("{\"url\":\"http://www.attachmentscanner.com/eicar.com\"}")
  .asString();

Using with PHP

To use Attachment Scanner in a PHP app, you just need to make an HTTP POST to the requests endpoint.

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://ATTACHMENT_SCANNER_URL/requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"url\":\"http://www.attachmentscanner.com/eicar.com\"}",
  CURLOPT_HTTPHEADER => array(
    "authorization: bearer ATTACHMENT_SCANNER_API_TOKEN",
    "content-type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Using with Go

To use Attachment Scanner within a GoLang app you just need to make an HTTP POST to the requests endpoint.

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://ATTACHMENT_SCANNER_URL/requests"

    payload := strings.NewReader("{\"url\":\"http://www.attachmentscanner.com/eicar.com\"}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("authorization", "bearer ATTACHMENT_SCANNER_API_TOKEN")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

Advanced API usage

See the full Attachment Scanner API documentation for advanced usage.

Dashboard

The Attachment Scanner dashboard allows you to view previous scans and details.

You can access the dashboard via the CLI:

$ heroku addons:open attachment-scanner
Opening attachment-scanner for sharp-mountain-4005

Alternatively, you can visit the Heroku Dashboard, select the app in question, and select Attachment Scanner from the Add-ons menu.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan:

$ heroku addons:upgrade attachment-scanner:newplan
-----> Upgrading attachment-scanner:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: attachment-scanner:newplan

Removing the add-on

You can remove Attachment Scanner via the CLI:

$ heroku addons:destroy attachment-scanner
-----> Removing attachment-scanner from sharp-mountain-4005... done, v20 (free)

Support

All Attachment Scanner support and runtime issues should be submitted via one of the Heroku Support channels.

Any non-support related issues or product feedback is welcomed by Attachment Scanner.