Working with files

Overview​ 

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

IMAP Action​ 

Every event emitted by an IMAP action 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.",
  "has_attachment": true,
  "attachments": [
    {
      "filename": "hello.txt",
      "guid": "dee73fe0-044f-4e2d-873e-e6850debc03a",
      "md5": "aba2d86ed17f587eb6d57e6c75f64f05",
      "sha256": "807126cbae47c03c99590d081b82d5761e0b9c57a92736fc8516cf41bc564a7d",
      "sizeinbytes": 1578,
      "base64encodedcontents": "ug4AtAnNIbgBTM0hVGhpc=="
    }
  ]
}

HTTP Request Action​ 

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 action to send files to 3rd-party systems using:

  • a multipart/form-data request

  • a field containing the Base64 encoded representation of a file

  • the BASE64_DECODE function

For example, the following HTTP Request action 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": "=BASE64_DECODE(get_email_with_attachment.attachments[0].base64encodedcontents)",
      "filename": "=get_email_with_attachment.attachments[0].filename"
    },
    "apikey": "=CREDENTIAL.virustotal"
  },
  "headers": {}
}

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 BASE64_DECODE function, we include this in a field called 'contents'. We must also include a 'filename' field in the object. In this example, the object is labeled file, but you can use whatever label you like – Tines will recognize the object based on its contents and filename structure.

Tines will automatically detect the content type based on file contents, but if you need to control this directly, you can specify content_type alongside the contents and filename keys.

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

Other APIs may require that file information is uploaded in base 64, for instance, for this other Virustotal API endpoint:

{
  "url": "https://www.virustotal.com/api/v3/files",
  "method": "post",
  "content_type": "application_json",
  "payload": {
    "file": "=BASE64_ENCODE(upstream_action.file_contents)"
  },
  "headers": {
    "x-apikey": "YOUR_API_KEY"
  }
}
Was this helpful?