Plugin API Reference

honeycomb.servicemanager.base_service module

Custom Service implementation from MazeRunner.

class honeycomb.servicemanager.base_service.DockerService(*args, **kwargs)

Bases: honeycomb.servicemanager.base_service.ServerCustomService

Provides an ability to run a Docker container that will be monitored for events.

docker_image_name

Return docker image name.

docker_params

Return a dictionary of docker run parameters.

See also

Docker run: https://docs.docker.com/engine/reference/run/

Returns:Dictionary, e.g., dict(ports={80: 80})

get_lines()

Fetch log lines from the docker service.

Returns:A blocking logs generator

on_server_shutdown()

Stop the container before shutting down.

on_server_start()

Service run loop function.

Run the desired docker container with parameters and start parsing the monitored file for alerts.

parse_line(line)

Parse line and return dictionary if its an alert, else None / {}.

read_lines(file_path, empty_lines=False, signal_ready=True)

Fetch lines from file.

In case the file handler changes (logrotate), reopen the file.

Parameters:

• file_path – Path to file
• empty_lines – Return empty lines
• signal_ready – Report signal ready on start

class honeycomb.servicemanager.base_service.ServerCustomService(alert_types: list, service_args: dict = {})

Bases: multiprocessing.context.Process

Custom Service Class.

This class provides a basic wrapper for honeycomb (and mazerunner) services.

add_alert_to_queue(alert_dict)

Log alert and send to integrations.

alert_types = None

List of alert types, parsed from config.json

alerts_queue = None

emit(**kwargs)

Send alerts to logfile.

Parameters:kwargs – Fields to pass to honeycomb.decoymanager.models.Alert

logger = <Logger honeycomb.servicemanager.base_service (DEBUG)>

Logger to be used by plugins and collected by main logger.

on_server_shutdown()

Shutdown function of the server.

Override this and take care to gracefully shut down your service (e.g., close files)

on_server_start()

Service run loop function.

The service manager will call this function in a new thread.

Note

Must call signal_ready() after finishing configuration

run()

Daemon entry point.

run_service()

Run the service and start an alert processing queue.

See also

Use on_server_start() and on_server_shutdown() for starting and shutting down your service

service_args = None

Validated dictionary of service arguments (see: honeycomb.utils.plugin_utils.parse_plugin_args())

signal_ready()

Signal the service manager this service is ready for incoming connections.

thread_server = None

honeycomb.integrationmanager.integration_utils module

Honeycomb Integration Manager.

class honeycomb.integrationmanager.integration_utils.BaseIntegration(integration_data)

Bases: object

Base Output Integration Class.

Use __init__() to set up any prerequisites needed before sending events, validate paramaters, etc.

Parameters:integration_data (dict) – Integration parameters Raises:IntegrationMissingRequiredFieldError – If a required field is missing.

format_output_data(output_data)

Process and format the output_data returned by send_event() before display.

This is currently only relevant for MazeRunner, if you don’t return an output this should return output_data without change.

Parameters:output_data – As returned by send_event() Return type:dict Returns:MazeRunner compatible UI output. Raises:IntegrationOutputFormatError – If there’s a problem formatting the output data.

poll_for_updates(integration_output_data)

Poll external service for updates.

If service has enabled polling, this method will be called periodically and should act like send_event()

Parameters:integration_output_data – Output data returned by previous send_event() or poll_for_updates() Returns:See send_event() Raises:IntegrationPollEventError – If there’s a problem polling for updates.

send_event(alert_dict)

Send alert event to external integration.

Parameters:

alert_dict – A dictionary with all the alert fields.

Return type:

tuple(dict(output_data), object(output_file))

Raises:

• IntegrationSendEventError – If there’s a problem sending the event.
• IntegrationMissingRequiredFieldError – If a required field is missing.

Returns:

A tuple where the first value is a dictionary with information to display in the UI, and the second is an optional file to be attached. If polling is enabled, the returned output_data will be passed to poll_for_updates(). If your integration returns nothing, you should return ({}, None).

test_connection(integration_data)

Perform a test to ensure the integration is configured correctly.

This could include testing authentication or performing a test query.

Parameters:integration_data – Integration arguments. Returns:success Return type:tuple(bool(success), str(response))