docs - add plugins system
This commit is contained in:
parent
8295f6aeba
commit
e8f5db0b29
|
@ -9,4 +9,5 @@ security_tuning
|
|||
troubleshooting
|
||||
volumes
|
||||
environment_variables
|
||||
plugins
|
||||
```
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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
|
||||
...
|
||||
```
|
||||
|
|
@ -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).
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -29,8 +29,6 @@ services:
|
|||
|
||||
clamav-rest-api:
|
||||
image: benzino77/clamav-rest-api
|
||||
ports:
|
||||
- 8080:8080
|
||||
depends_on:
|
||||
- clamav-server
|
||||
environment:
|
||||
|
|
|
@ -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">
|
||||
|
|
Loading…
Reference in New Issue