mongoose.forward.webhook

class mongoose.forward.webhook.WebhookFormatter[source]

Bases: BaseFormatter

Formats network data for webhook consumption.

This class handles the conversion of network models (DPI, Alert, Flow) into JSON-serializable dictionaries. It ensures that complex types like datetime objects are correctly converted to strings and that any Pydantic-specific fields are handled according to the Pydantic version in use.

Security considerations:

  • The formatter performs a JSON round-trip to ensure data consistency and safety before it is sent over the network.

  • It uses a custom default for serialization to prevent failures on complex types, ensuring robust operation even with unexpected data.

static format(data)[source]

Format the given data into a dictionary for JSON serialization.

Handles Pydantic v1/v2 instances and generic objects.

Parameters:

data (Any) – The model instance or data object to format.

Returns:

A dictionary representation of the data, guaranteed to be JSON serializable. Returns an error dictionary if formatting fails.

Return type:

Dict[str, Any]

class mongoose.forward.webhook.WebhookForwarder(config)[source]

Bases: BaseForwarder

Forwards network events to a remote webhook asynchronously.

Subscribes to specified topics and sends data to a configured URL using HTTP POST. It manages its own background worker thread for non-blocking operation and supports various authentication methods and retry logic.

Notes

  • Authentication: Supports Basic Auth, Bearer tokens, and custom headers. Credentials should be provided via WebhookConfiguration using SecretStr to prevent accidental leakage in logs.

  • SSL/TLS: SSL certificate verification is enabled by default (verify_ssl=True). It is highly recommended to keep this enabled in production.

  • Sensitive data: While Mongoose normalizes data, users should ensure the webhook endpoint is secured (HTTPS) as network event data may contain sensitive infrastructure information (IPs, ports, protocol details).

  • Isolation: Each forwarder uses a dedicated requests.Session for connection pooling and to keep authentication headers isolated.

  • Forwarding modes:

    • immediate: Sends data as soon as it is received.

    • bulk: Accumulates data up to bulk_size or until a timeout occurs.

    • periodic: Sends data at a fixed periodic_interval at a maximum periodic_rate.

__init__(config)[source]

Initialize the WebhookForwarder.

Parameters:

config (WebhookForwarderConfiguration) – A WebhookConfiguration instance defining the destination and security settings.

forward(data)[source]

Send formatted data to the webhook URL with retries.

Orchestrates the formatting of data and the retry loop for delivery.

Parameters:

data (Any) – The data to forward (Pydantic model instance).

start()[source]

Start the forwarder worker thread.

Launches a background daemon thread that subscribes to the configured topics and processes incoming events.