mat2-web/README.md

                 _   ___                     _     
                | | |__ \                   | |    
 _ __ ___   __ _| |_   ) | ___ __      _____| |__   Trashing your meta,
| '_ ` _ \ / _` | __| / / |___|\ \ /\ / / _ \ '_ \    keeping your data,
| | | | | | (_| | |_ / /_       \ V  V /  __/ |_) |     within your browser.
|_| |_| |_|\__,_|\__|____|       \_/\_/ \___|_.__/ 

This is an online version of mat2. Keep in mind that this is a beta version, don't rely on it for anything serious, yet.

Demo instance

There is a demo instance deployed a mat2-web.dustri.org. Please don't upload any sensitive files to it.

How to deploy it?

mat2 is available in Debian stable.

# apt install uwsgi uwsgi-plugin-python3 git mat2
# apt install nginx-light  # if you prefer nginx
# apt install apache2 libapache2-mod-proxy-uwsgi  # if you prefer Apache2
# cd /var/www/
# git clone https://0xacab.org/jvoisin/mat2-web.git
# mkdir ./mat2-web/uploads/
# chown -R www-data:www-data ./mat2-web

Since uWSGI isn't fun to configure, feel free to copy this file to /etc/uwsgi/apps-enabled/mat2-web.ini and this one to /etc/nginx/sites-enabled/mat2-web.

Nginx is the recommended web engine, but you can also use Apache if you prefer, by copying this file to your /etc/apache2/sites-enabled/mat2-web file.

Then configure the environment variable: MAT2_ALLOW_ORIGIN_WHITELIST=https://myhost1.org https://myhost2.org Note that you can add multiple hosts from which you want to accept API requests. These need to be separated by a space. IMPORTANT: The default value if the variable is not set is: Access-Control-Allow-Origin: *

Finally, restart uWSGI and your web server:

systemctl restart uwsgi
systemctl restart nginx/apache/…

It should now be working.

You should add find /var/www/mat2-web/uploads/ -type f -mtime +1 -exec rm {} \; in a crontab to remove files that people might have uploaded but never downloaded.

Deploy via Ansible

If you happen to be using Ansible, there's an Ansible role to deploy mat2-web on Debian, thanks to the amazing systemli people: ansible-role-mat2-web

The role installs mat2-web as a uWSGI service, and runs it as a dedicated system user, installs bubblewrap to sandbox mat2 and creates a garbage collector cronjob to remove leftover files. Besides, it can create a dm-crypt volume with random key for the uploads folder, to ensure that the uploaded files won't be recoverable between reboots.

Deploy using Docker

You can find the ready to run docker image here: https://0xacab.org/jvoisin/mat2-web/container_registry

Example: docker run -p 80:80 -d -e MAT2_ALLOW_ORIGIN_WHITELIST='https://myhost1.org' registry.0xacab.org/jvoisin/mat2-web:latest

Make sure to add find /var/www/mat2-web/uploads/ -type f -mtime +1 -exec rm {} \; as cron job run inside the container.

Development

Install docker and docker-compose and then run docker-compose up to setup the docker dev environment. Mat2-web is now accessible on your host machine at localhost:5000. Every code change triggers a restart of the app. If you want to add/remove dependencies you have to rebuild the container.

RESTful API

Upload Endpoint

Endpoint: /api/upload

HTTP Verbs: POST

Body:

{
	"file_name": "my-filename.jpg",
	"file": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

The file_name parameter takes the file name. The file parameter is the base64 encoded file which will be cleaned.

Example Response:

{
    "output_filename": "fancy.cleaned.jpg",
    "mime": "image/jpg",
    "key": "81a541f9ebc0233d419d25ed39908b16f82be26a783f32d56c381559e84e6161",
    "meta": {
        "BitDepth": 8,
        "ColorType": "RGB with Alpha",
        "Compression": "Deflate/Inflate",
        "Filter": "Adaptive",
        "Interlace": "Noninterlaced"
    },
    "meta_after": {},
    "download_link": "http://localhost:5000/download/81a541f9ebc0233d419d25ed39908b16f82be26a783f32d56c381559e84e6161/fancy.cleaned.jpg"
}

Supported Extensions Endpoint

Endpoint: /api/extension

HTTP Verbs: GET

Example Response (shortened):

[
    ".asc",
    ".avi",
    ".bat",
    ".bmp",
    ".brf",
    ".c",
    ".css",
    ".docx",
    ".epub"
]

Docker

There are two Dockerfiles present in this repository. The file called Dockerfile.development is used for development and Dockerfile.production is used for production deployments.

You can find the automated docker builds in the registry of this repository: https://0xacab.org/jvoisin/mat2-web/container_registry

Custom templates

You can override the default templates from templates/ by putting replacements into the directory path that's configured in app.config['CUSTOM_TEMPLATES_DIR'] (default custom_templates/).

Threat model

• An attacker in possession of the very same file that a user wants to clean, along with its names, can perform a denial of service by continually requesting this file, and getting it before the user.
• An attacker in possession of only the name of a file that a user wants to clean can't perform a denial of service attack, since the path to download the cleaned file is not only dependent of the name, but also the content.
• The server should do its very best to delete files as soon as possible.

Licenses

• mat2-web is under MIT
• The raleway font is under OFL1.1
• normalize.css is under MIT
• skeleton is under MIT