Crate bulwark_sdk

SDK for Bulwark plugins

The Bulwark SDK provides an API for writing detection plugins. Plugins are compiled to WebAssembly components and executed by Bulwark in a secure sandboxed environment.

Writing A Plugin

A typical Bulwark detection plugin will declare a struct that implements the generated HttpHandlers trait. This trait is provided by the bulwark_plugin macro.

Minimal Example

use bulwark_sdk::*;
use std::collections::HashMap;

pub struct ExamplePlugin;

#[bulwark_plugin]
impl HttpHandlers for ExamplePlugin {
    fn handle_request_decision(
        _request: http::Request,
        _labels: HashMap<String, String>,
    ) -> Result<HandlerOutput, Error> {
        let mut output = HandlerOutput::default();
        // Main detection logic goes here.
        output.decision = Decision::restricted(0.0);
        Ok(output)
    }
}

Building A Plugin

Bulwark plugins are compiled to WebAssembly components. They can be compiled using the bulwark-cli build subcommand. Detailed instructions are available in the main Bulwark documentation.

Handler Functions

There are five handler functions that can be implemented by a plugin:

• handle_init
  • Initializes a plugin. Rarely implemented.
• handle_request_enrichment
  • Enriches a request with labels prior to a decision being made. Can be used e.g. to decrypt session cookies.
• handle_request_decision
  • Makes a decision on a request before sending it to the interior service. Most plugins will implement this.
• handle_response_decision
  • Makes a decision on a response received from the interior service. Can be used e.g. for circuit breaking.
• handle_decision_feedback
  • Receives the combined decision after a Verdict has been rendered. Can be used e.g. for counters or unsupervised learning.

Each handler function is called by the Bulwark runtime with Request and label parameters. Additionally, the handle_response_decision function is called with the Response from the interior service. The handle_decision_feedback function is called with both the Response and the Verdict of the combined decision.

If a handler function is not declared, the bulwark_plugin macro will automatically provide a no-op implementation instead.

The handle_request_decision and handle_response_decision functions return a HandlerOutput result.

Modules

http

The http module provides HTTP type definitions and sends outgoing HTTP requests.

redis

The redis module manages remote state, including rate-limiting and circuit-breaking.

Macros

error

Construct an ad-hoc error from a string or existing non-anyhow error value.

value

Construct a Value from a literal.

Structs

Decision

A Decision represents evidence in favor of either accepting or restricting an operation under consideration.

HandlerOutput

A HandlerOutput represents a decision and associated output for a handler function within a detection.

Map

Represents a JSON key/value type.

Verdict

A Verdict represents a combined decision across multiple detections.

Enums

Outcome

Represents a value from a continuous range taken from the pignistic transformation as a category that can be used to select a response to an operation.

ParseCounterError

Returned when an attempt to parse a counter within a plugin environment fails.

ThresholdError

Returned when a threshold is either out-of-order or out-of-range.

Value

Represents any valid JSON value.

Constants

ACCEPT

A decision representing acceptance with full certainty.

RESTRICT

A decision representing restriction with full certainty.

UNKNOWN

A decision representing full uncertainty.

Functions

client_ip

Returns the true remote client IP address.

config_keys

Returns all of the plugin’s configuration key names.

config_var

Returns a named plugin configuration value as a Value.

from_value

Interpret a Value as an instance of type T.

Type Aliases

Bytes

A type alias. See bytes::Bytes for details.

Error

A generic detection plugin error.

Attribute Macros

bulwark_plugin

The bulwark_plugin attribute generates default implementations for all handler traits in a module and produces friendly errors for common mistakes.