tubbz-alt / nginx_flaskapp_whitelister

Nginx Flask App Whitelister

Thinkst Applied Research

Overview

The Nginx Flask App Whitelister is a tool that ensures that only Flask routes that are explicitly defined will be allowed to be served by Nginx (and all other requested routes will be served 404's). It does this by generating additional configuration for Nginx webservers serving Fask applications to be included in a simple one-line addition in existing Nginx configuration. This ensures that all unknown/unwanted routes (including debug endpoints accidentally enabled) will be blocked by Nginx before it get's anywhere near your running Flask app.

The tool ensures as far as possible that the additional config written will incorporate the current server setup, whilst still taking priority over possibly conflicting config in the current configuration file, but not ignoring additional configuration already existing in the current setup. This makes for a tool deployment ontop of an already existing Nginx config, with minimal user-input required in order to update a config setup with the latest relevant Flask app routes.

This tool is intended to be used in an automated deployment process, such as Saltstack or Ansible. nginx_flaskapp_whitelister would be run after your nginx.conf is written by the deployment process, but before the nginx process is (re)started.

Prerequisites

• Python 2.7
• python-nginx

Install

• Install tool from source in the python environment in which your Flask application runs

$ git clone https://github.com/thinkst/nginx_flaskapp_whitelister
$ cd nginx_flaskapp_whitelister
$ python setup.py install

Run

• Add the line include include.whitelist at the top of your location directive definitions in your current Nginx configuration file (as seen in the snippet example config).

server {
        listen        one.example.com;
        server_name   one.example.com  www.one.example.com;

        access_log   /var/log/nginx.access_log  main;

        include include.whitelist;

        location / {
            proxy_pass         http://127.0.0.1/;
            proxy_redirect     off;

            (etc.........)

• Run the tool with no arguments, or with the addition of the -h flag to view the usage

$ nginx_flaskapp_whitelister
Usage: nginx_flaskapp_whitelister -r (optional) -p <pythonenvdirectory> -f <flaskappmodule> -a <flaskapplicationname> -c <nginxconfiglocation> -n <nginxincludelocation>
Flags:
        -h                              Help function to display functionality and guidance to use the nginx_flaskapp_whitelister module.
        -r                              Optional: Restart Nginx to reload added configuration and for white-listing to take immediate effect.
        -p <pythonenvdirectory>         The directory of the python environment that the Flask application is running in. The $PYTHONHOME variable.
        -f <flaskappmodule>             The python module from where the Flask application is served.
        -a <flaskapplicationname>       The physical name of the Flask application.
        -c <nginxconfiglocation>        The location of the current Nginx configuration that is used to serve the Flask application.
        -n <nginxincludelocation>       Optional: File path to where the 'include.whitelist' file will be included from within the Nginx configuration,
                                        that is used to serve the Flask application. If no file path is provided, the default will be used as
                                        '/etc/nginx/'.

• Add in the necessary relevant arguments with the matching flags (as described in the usage notes).

• If the -r flag was not set to automatically restart the Nginx service after the completion of the tool (or the restart process failed); Nginx will have to be restarted manually in order for the whitelisting configuration generated by the tool to take effect.

Example

For implementing the nginx_flaskapp_whitelister for your Flask application called app, that is defined in the file /module/flask.py and run from /path/to/python/virtualenv; you would run the following command:

nginx_flaskapp_whitelister -p /path/to/python/virtualenv -f module.flask -a app -c /etc/nginx/nginx.conf

This is assuming that your current Nginx configuration file is located at and defined as /etc/nginx/nginx.conf and that you will include the line in your current config file as include include.whitelist (thus implying that the default location for the additional tool-generated-config is acceptable to be used - which is /etc/nginx/).