docs - add plugins system

docs/index.md

@@ -9,4 +9,5 @@ security_tuning
 troubleshooting
 volumes
 environment_variables
+plugins
 ```

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

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
+...
+```
+

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).

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.

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:

examples/clamav/web-files/index.php

@@ -8,7 +8,7 @@ if (file_exists($_FILES['myfile']['tmp_name']) && is_uploaded_file($_FILES['myfi
 }
 ?>
 
-<form action="upload.php" method="post" enctype="multipart/form-data">
+<form action="index.php" method="post" enctype="multipart/form-data">
 	Select file to scan :
 	<input type="file" name="myfile">
 	<input type="submit" value="Scan file" name="submit">