From e8f5db0b29ac55ed27dd88d71d95bd81c41a9c7d Mon Sep 17 00:00:00 2001 From: florian Date: Sat, 5 Jun 2021 11:24:35 +0200 Subject: [PATCH] docs - add plugins system --- docs/index.md | 1 + docs/introduction.md | 1 + docs/plugins.md | 108 ++++++++++++++++++++++++++++ docs/security_tuning.md | 4 ++ docs/volumes.md | 7 ++ examples/clamav/docker-compose.yml | 2 - examples/clamav/web-files/index.php | 2 +- 7 files changed, 122 insertions(+), 3 deletions(-) create mode 100644 docs/plugins.md diff --git a/docs/index.md b/docs/index.md index 0c17289..d9c6fb6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,4 +9,5 @@ security_tuning troubleshooting volumes environment_variables +plugins ``` diff --git a/docs/introduction.md b/docs/introduction.md index 8602e18..9329dee 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -17,6 +17,7 @@ Non-exhaustive list of features : - Block TOR, proxies, bad user-agents, countries, ... - Block known bad IP with DNSBL and CrowdSec - Prevent bruteforce attacks with rate limiting +- Plugin system for external security checks (e.g. : ClamAV) - Easy to configure with environment variables or web UI - Automatic configuration with container labels - Docker Swarm support diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 0000000..5846a88 --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,108 @@ +# Plugins + +Bunkerized-nginx comes with a plugin system that lets you extend the core with extra security features. To add a plugin you will need to download it, edit its settings and mount it to the `/plugins` volume. + +## Official plugins + +- [ClamAV](https://github.com/bunkerity/bunkerized-nginx-clamav) : automatically scan uploaded files and deny access if a virus is detected + +## Community plugins + +If you have made a plugin and want it to be listed here, feel free to [create a pull request](https://github.com/bunkerity/bunkerized-nginx/pulls) and edit that section. + +## Use a plugin + +The generic way of using a plugin consists of : +- Download it to a folder (e.g. : myplugin/) +- Edit the settings inside the plugin.json files (e.g. : myplugin/plugin.json) +- Mount the plugin folder to the /plugins/plugin-id inside the container (e.g. : /where/is/myplugin:/plugins/myplugin) + +To check if the plugin is loaded you should see log entries like that : + +```log +2021/06/05 09:19:47 [error] 104#104: [PLUGINS] *NOT AN ERROR* plugin MyPlugin/1.0 has been loaded +``` + +## Write a plugin + +A plugin is composed of a plugin.json which contains metadata (e.g. : name, settings, ...) and a set of LUA files for the plugin code. + +### plugin.json + +```json +{ + "id": "myplugin", + "name": "My Plugin", + "description": "Short description of my plugin.", + "version": "1.0", + "settings": { + "MY_SETTING": "value1", + "ANOTHER_SETTING": "value2", + } +} +``` + +The `id` value is really important because it must match the subfolder name inside the `plugins` volume. Choose one which isn't already used to avoid conflicts. + +Settings names and default values can be choosen freely. There will be no conflict when you retrieve them because they will be prefixed with your plugin id (e.g. : `myplugin_MY_SETTING`). + +### Main code + +```lua +local M = {} +local logger = require "logger" + +-- this function will be called for each request +-- the name MUST be check without any argument +function M.check () + + -- the logger.log function lets you write into the logs + logger.log(ngx.NOTICE, "MyPlugin", "check called") + + -- here is how to retrieve a setting + local my_setting = ngx.shared.plugins_data:get("pluginid_MY_SETTING") + + -- a dummy example to show how to block a request + if my_setting == "block" then + ngx.exit(ngx.HTTP_FORBIDDEN) + end + +end + +return M +``` + +That file must have the same name as the `id` defined in the plugin.json with a .lua suffix (e.g. : `myplugin.lua`). + +Under the hood, bunkerized-nginx uses the [lua nginx module](https://github.com/openresty/lua-nginx-module) therefore you should be able to access to the whole **ngx.\*** functions. + +### Dependencies + +Since the core already uses some external libraries you can use it in your own plugins too (see the [compile.sh](https://github.com/bunkerity/bunkerized-nginx/blob/master/compile.sh file) and the [core lua files](https://github.com/bunkerity/bunkerized-nginx/tree/master/lua)). + +In case you need to add dependencies, you can do it by placing the corresponding files into the same folder of your main plugin code. Here is an example with a file named **dependency.lua** : + +```lua +local M = {} + +function M.my_function () + return "42" +end + +return M +``` + +To include it from you main code you will need to prefix it with your plugin id like that : + +```lua +... +local my_dependency = require "pluginid.dependency" + +function M.check () + ... + local my_value = my_dependency.my_function() + ... +end +... +``` + diff --git a/docs/security_tuning.md b/docs/security_tuning.md index d0d8616..785094b 100644 --- a/docs/security_tuning.md +++ b/docs/security_tuning.md @@ -248,6 +248,10 @@ docker run --network mynet \ bunkerity/bunkerized-nginx-ui ``` +## Plugins + +Some security features can be added through the plugins system (e.g. : ClamAV). You will find more info in the [plugins section](https://bunkerized-nginx.readthedocs.io/en/latest/plugins.html). + ## Container hardening You will find a ready to use docker-compose.yml file focused on container hardening [here](https://github.com/bunkerity/bunkerized-nginx/tree/master/examples/hardened). diff --git a/docs/volumes.md b/docs/volumes.md index 3cdc488..c26ddea 100644 --- a/docs/volumes.md +++ b/docs/volumes.md @@ -82,3 +82,10 @@ Description : Depending of the settings you use, bunkerized-nginx may download external content (e.g. : blacklists, GeoIP DB, ...). To avoid downloading it again in case of a container restart, you can save the data on the host. Read-only : no + +## Plugins + +Mountpoint : `/plugins` + +Description : +This volume is used to extend bunkerized-nginx with [additional plugins](https://bunkerized-nginx.readthedocs.io/en/latest/plugins.html). Please note that you will need to have a subdirectory for each plugin you want to enable. diff --git a/examples/clamav/docker-compose.yml b/examples/clamav/docker-compose.yml index 7285576..330216d 100644 --- a/examples/clamav/docker-compose.yml +++ b/examples/clamav/docker-compose.yml @@ -29,8 +29,6 @@ services: clamav-rest-api: image: benzino77/clamav-rest-api - ports: - - 8080:8080 depends_on: - clamav-server environment: diff --git a/examples/clamav/web-files/index.php b/examples/clamav/web-files/index.php index 82dc64c..e3cd093 100644 --- a/examples/clamav/web-files/index.php +++ b/examples/clamav/web-files/index.php @@ -8,7 +8,7 @@ if (file_exists($_FILES['myfile']['tmp_name']) && is_uploaded_file($_FILES['myfi } ?> -
+ Select file to scan :