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.