Overview

Files are typically handled in Tines through base64 encoded strings. Base64 encoding allows Tines include binary data in events and, as such, any agent type may interact with a file. The IMAP Agent and HTTP Request Agent provide specific features for working with files.

IMAP Agent

Every event emitted by an IMAP agent includes an array containing information on all files attached to the corresponding email. For example, in the below event, we see a single file, hello.txt, was attached to the email. We also have various pieces of metadata about the file including the file name and hashes. The field base64encodedcontents contains a Base64 representation of the file.

{
  "message_id": "1688375064.8603887.1514928714437@example.com",
  "folder": "INBOX",
  "subject": "This is the subject of the email",
  "from": "bob@example.com",
  "to": [
    "alice@example.com"
  ],
  "cc": [
     "carol@example.com"
  ],
  "date": "2018-01-01T10:10:00+00:00",
  "mime_type": "text/plain",
  "body": "This is the body of the email.",
  "matches": {
  },
  "has_attachment": true,
  "attachments": [
      {
        "filename": "hello.txt",
        "guid": "dee73fe0-044f-4e2d-873e-e6850debc03a",
        "md5": "aba2d86ed17f587eb6d57e6c75f64f05",
        "sha256": "807126cbae47c03c99590d081b82d5761e0b9c57a92736fc8516cf41bc564a7d",
        "sizeinbytes": 1578,
        "base64encodedcontents": "ug4AtAnNIbgBTM0hVGhpc=="
      }
  ]        
}

HTTP Request Agent

It is common for web applications to accept file uploads. These uploads are typically processed by sending the web application a multipart/form-data request. We can use the HTTP Request Agent to send files to 3rd-party systems using:

  • a multipart/form-data request
  • a field containing the Base64 encoded representation of a file
  • the base64decode liquid filter

For example, the following HTTP Request Agent will submit a file from an incoming event to Virustotal:

{
  "url": "https://www.virustotal.com/vtapi/v2/file/scan",
  "content_type": "data",
  "method": "post",
  "payload": {
    "file": {
      "contents": "{{.get_email_with_attachment.attachments[0].base64encodedcontents | base64_decode}}",
      "filename": "{{.get_email_with_attachment.attachments[0].filename}}"
    },
    "apikey": "{% credential Virustotal %}"
  },
  "headers": {

  },
  "expected_update_period_in_days": "1"
}

As shown above, we use the data content_type to indicate we wish to submit the request using multipart/form-data. We then build a ‘file’ object, taking the encoded content contained in the .get_email_with_attachment.attachments[0].base64encodedcontents field from the incoming event and decoding it back to its original form using the base64decode liquid filter, we include this in a field called ‘contents’. We must also include a ‘filename’ field in the ‘file’ object.

When the above agent runs, it will build and send a correctly formatted multipart request to the specified URL.