Configuration
main.toml
include.toml
[service]
port = 8089
admin_port = 8090
remote_state = "redis://127.0.0.1:6379"
[thresholds]
restrict = 0.75
[[include]]
path = "include.toml"
[[plugin]]
ref = "evil_bit"
path = "bulwark-evil-bit.wasm"
[[preset]]
ref = "default"
plugins = ["evil_bit", "starter_preset"]
[[resource]]
route = "/"
plugins = ["default"]
timeout = 25
[[resource]]
route = "/*params"
plugins = ["default"]
timeout = 25
[[plugin]]
ref = "blank_slate"
path = "bulwark-blank-slate.wasm"
config = {}
[[preset]]
ref = "starter_preset"
plugins = ["blank_slate"]
All of the settings for Bulwark's services are organized under the
service table.Type:
u16Default:
8089The port number for the Bulwark primary service. Bulwark's primary service is determined by the subcommand supplied to the CLI.
Type:
u16Default:
8090The port number for the Bulwark admin service. The admin service hosts the health check endpoints (
/live, /started, and /ready). Further details may be found on the Deployment page.Type:
boolDefault:
trueDetermines whether the admin service will be enabled. If set to
false, only the primary service will be available.Type:
StringAn optional setting that enables the use of Bulwark's remote state feature. It should be set to a Redis connection URI. When a plugin makes a host call that uses remote state, the corresponding Redis commands will be sent here.
While this setting is optional and disabled by default, it is highly recommended that Bulwark be used with it enabled. Much of Bulwark's capabilities are derived from it.
Type:
u32Default:
16The size of the connection pool to use when accessing remote state.
Type:
u8Default:
0The number of trusted proxy hops in front of, or exterior to, the Bulwark primary service. Bulwark's own proxy hop or the hop of the proxy hosting Bulwark would not be counted. This setting determines which client IP will be reported to the plugin guest environment when parsing the
Forwarded or X-Forwarded-For HTTP header.If Bulwark is deployed in conjunction with a load balancer or with another proxy exterior to it and the
proxy_hops setting is not updated to reflect this, some Bulwark plugins may attempt to block traffic from trusted proxy sources whenever malicious traffic from any source is detected.The settings for how Bulwark provides and manages its metrics are organized under the
metrics table. By default, Bulwark uses Prometheus metrics and does not require any configuration other than the admin_enabled setting to use them.Type:
StringThis is the hostname of the StatsD server to push metrics to. All other StatsD settings are ignored if this value is not set.
If set, disables Prometheus metrics support and enables StatsD support instead. Enabling both at once is not supported.
Type:
u16Default:
8125Determines the port number that will be used for the StatsD server that metrics are pushed to.
Type:
usizeDefault:
5000Determines the size of the queue used when pushing metrics to StatsD.
Type:
usizeDefault:
1024Determines the size of the buffer metrics are sent to before being sent to the StatsD server.
Type:
StringA prefix to apply to StatsD metrics names.
The configurable decision thresholds are organized under the
thresholds table.Type:
boolDefault:
falseDisables blocking of requests. If set, Bulwark will allow all requests through, regardless of the outcome determined by its plugins. It will still calculate a verdict, it will still inject headers readable by interior services, plugin-specific side-effects may still occur, but Bulwark will not otherwise take action on an incoming request. This can be used to perform initial evaluation of Bulwark without concern for false positives.
Type:
f64Default:
0.8The decision score lower-bound for blocking a request. Any decision risk score above this threshold will be blocked if Bulwark is in blocking mode.
Type:
f64Default:
0.6The decision score lower-bound for marking a request as suspicious. Any decision risk score above this threshold will be marked as suspicious. Suspicious requests are not blocked, but they may be queried and manually inspected and plugins may use them in the context of feedback loops to inform future decision-making.
Type:
f64Default:
0.2The decision score upper-bound for marking a request as trusted. Any decision risk score value below this threshold will be marked as trusted. Trusted requests are not handled differently than accepted requests, but plugins may use them in the context of feedback loops to inform future decision-making.
An include directive used during initial configuration loading. Allows configuration to span multiple files. Multiple
include tables may appear in a configuration file.Type:
StringThe relative path of the configuration file to be included. The path is resolved relative to the configuration file that is performing the include.
Configuration for an individual plugin. Multiple
plugin tables may appear in a configuration file. Additionally, multiple plugin tables that point to the same file path may appear, as long as they have different reference values. This is typically used to supply different guest configurations to the same plugin implementation.Type:
StringA unique identifier that should be both human-readable and machine-readable, for a specific plugin and its associated configuration. Should only include ASCII lowercase a-z and underscore (_) characters.
Type:
StringThe relative path to the compiled Web Assembly file for a plugin. The path is resolved relative to the file in which it appears.
Type:
f64Default:
1.0A weight factor which this plugin's decisions will be multiplied by. This may be used to tune results from a plugin without recompiling it. In particular, values below 1.0 may be used to scale down the output of the
set_accepted or set_restricted host calls, which would otherwise only output a maximum value.Type:
Map<String, Value>Default:
{}An opaque configuration structure that will be passed to the plugin guest environment. It will be JSON-serialized when sent to the plugin. Language-specific SDKs may provide convenience functions to automatically deserialize this value within the guest.
Type:
Map<String, Vec<String>>Default:
{}A set of permission grants for the plugin. If a plugin attempts to perform a privileged operation without the necessary permission grant, it will exit immediately with a panic.
The
env permission grant is a list of environment variables that this plugin is allowed to read. This is typically used to grant fine-grained access to a secret.The
http permission grant is a list of URI host values that may be used when sending outbound HTTP requests from a plugin. Host values must match exactly and wildcards are not currently supported.The
state permission grant is a list of Redis key prefixes that may be accessed when using Bulwark's remote state feature.A preset is a reusable grouping of plugins and other presets that can be used to reduce repetition within Bulwark's configuration. A good practice is to create a default preset that provides generic protection, and then use more specialized plugin lists on a per-resource basis, where needed.
Type:
StringA unique identifier that should be both human-readable and machine-readable, for a specific preset and its associated configuration. Should only include ASCII lowercase a-z and underscore (_) characters.
Type:
Vec<String>A list of plugin reference values or other preset references that this preset should represent. Circular references are not allowed. Reference types may be a mix of plugin and preset references.
A resource in Bulwark's configuration is a mapping between an endpoint and the set of plugins that will be applied to incoming requests for it. Resource tables may also be used to control how latency-sensitive Bulwark should be on a per-endpoint basis.
The route pattern that this resource should match. Route patterns may capture parameters, which will be made accessible to plugins via the
get_param_value function in the API. Single path parameters may be captured with a : sigil character and multiple path parameters may be captured with a * sigil character. Query strings are ignored for matching, but may be inspected by plugins.Routes within Bulwark match only the request. An interior service does not need to respond to the same or even similar route patterns, and in some cases, Bulwark's configured routes may correspond as much to threat patterns as they do to the shape of the interior services.
The
/ pattern will match only the apex path. It is not a prefix match. The /*params pattern will match everything except the apex path, because *params portion of the pattern will not match if it is empty. A /:user/profile pattern would match the request path /alice/profile, capturing the value alice into the user parameter.Type:
Vec<String>A list of plugin reference values or other preset references that this resource should execute in response to a matching request. Circular references are not allowed. Reference types may be a mix of plugin and preset references.
Type:
u64Default:
10A timeout duration, specified in milliseconds. Each plugin handler phase will have this long to complete execution. If a plugin times out prematurely, the results of its execution will not be considered for that phase. If a plugin registers multiple handlers across both the request and response phase, subsequent handlers will still execute even if earlier handlers timed out. Therefore if the maximum tolerable latency for an endpoint is 30ms, this timeout would be set to 15ms. Remote state becoming unavailable is one scenario where both phase timeouts might be hit.
Last modified 1mo ago