WRITING HONEYPOINT PLUGINS WITH HONEYPOINT SECURITY SERVER

Transcription

1 WRITING HONEYPOINT PLUGINS WITH HONEYPOINT SECURITY SERVER Revision: 1.0 MicroSolved, Inc. telephone:

2 Table of Contents Overview! 2 What are HoneyPoint Plugins & What Are They For?! 2 Plugin Management! 2 Plugin Examples! 3 The Plugin Meta-Language Tags! 4 Extending the Plugin Mechanisms with Custom External Code! 4 Plugin Licensing! 5 Obtaining Plugins! 5 Troubleshooting Plugins! 5 1

3 Overview HoneyPoint Security Server (HPSS) is the world s leading platform for performing nuance detection. This unique set of software and hardware tools provides organizations with an easy, effective and powerful set of tools to obtain visibility and detective capabilities at specific points in their environment. These tools can be combined in a flexible, extensible manner to adapt to the location and type of asset that an organization is seeking to protect. The plugin mechanism discussed in this white paper was created to provide a way for organizations to extend the power and capability of the HPSS Console component to match their specific needs. Plugins are an automation tool based around a meta-language that enables the extrusion of event data from the Console. Creating and running plugins lets organizations further automate their response capabilities, process and transfer alert events as needed and quickly integrate HoneyPoint functionality into existing SEIM, event ticketing or third-party monitoring services. This paper discusses what plugins are, how they work and how to develop, implement and manage them. What are HoneyPoint Plugins & What Are They For? HoneyPoint plugins are a tool for automating responsive, data analysis, logging and alerting tasks in HPSS. Basically, they provide a meta-language API for extruding data that relates to an alert event in the HPSS Console. When an alert is received, the event data is parsed against the list of operational plugins. If applicable, the plugin is executed by opening an operating system command line shell and passing the appropriate event data as arguments to the command specified in the plugin script. The event data elements can be customized as needed by using specific elements of the meta-language in the plugin script. This allows the user to easily create their own processes, with as complex logic as they desire to further manage and process HPSS event data or integrate into their existing security monitoring infrastructures. Examples of tasks that plugins might be used to execute include IP lookups, log file creation, updating perimeter or switch device ACLs, or even firing additional recon tools in an automated fashion. In most cases, organizations simply see plugins as a way to implement specific types of event parsing to determine alert priority or as a quick, easy and powerful way to get HPSS event data into their log monitoring systems, SEIM or ticketing applications. While HPSS supports logging to native syslog/event logs on the Console host directly, plugins make for an easy to use way to create a custom data flow and deliver event data in a rapid, sustainable and actionable format specific to your organization s needs. Plugin Management Plugins are enabled and disabled in the HPSS Console GUI by selecting Preferences from the drop down menu and then clicking on the Plugins tab. In this window, the administrator of the Console can enable or disable the plugins that are known to the Console component. The list of plugins in this window is loaded at Console start up, so if you add a plugin and it does not show up in the list, restart the Console application and you will find it has been added. The plugins in the list each have a corresponding.hpp file in a folder called Plugins which is located in the same directory as the Console binary. You can create and edit any.hpp file with a text editor of your choice. The.hpp file has a specific format which is discussed below. More information about the use, creation and management of plugins is available in the HPSS User Guide, which is maintained on the software distribution site from which you obtained your HPSS downloads. See the Quick Start Guide that was delivered via , along with your license key, for the appropriate URL. 2

4 Plugin Examples Below is an example of a plugin created to have HPSS respond to an event by performing a basic nmap scan of the attacker IP. In this case, the HPSS deployment is on an internal network and the administrator wants to be able to see basic information about the offending hosts. NOTE: This is an example, strike back techniques against an attacker IP are NOT recommended as best practice. Creating plugins is quite easy. Each plugin contains four lines of text, below is the sample nmap plugin with a description of each line. NMAP plugin nmap -ss -vv -n -P0 [attacker ip] The first line is the name of the plugin that is displayed in the Console. This can be anything you wish, but must be unique. The second line is the command you wish to run, the [attacker ip] is a variable that is replaced during execution. Keep in mind that the direct path for the command may be necessary (ex: /usr/local/nmap, etc. ). The third line is the most amount of time in milliseconds, that the console will wait for the shell activity of the plugin to complete. If the plugin's code does not complete in the specified time, the process will be terminated by the Console. This is to prevent CPU overloading and hung processes. Depending on the purpose of the plugin, this value may range from 1000 (1 second) to several minutes. If you experience plugins not performing as expected, first try raising this value to see if that corrects the issue. The fourth line, is the number of minutes that must pass before acting again on the same IP address. For example, if an attacker ip of is detected, the initial connection event will trigger the plugin if that IP has not been seen in the last five minutes. However, further events from that IP address will not trigger the plugin until 5 minutes has passed without activity from that specific attacker IP. This value can be set to 0, to repeatedly perform the plugin functions for all alerts, ignoring the requirement for the attacker IP to be unique in a time period. Note that this means that the plugin will fire for each event detected by HPSS. This setting is often used for logging and sending data into other monitoring tools. 3

5 The Plugin Meta-Language Tags Other variables that can be used in plugins are as follows: [attacker IP] - the IP address of the offending host detected by HPSS. In the case of Wasp and other local host detections, or is suggested and often used. [HoneyPoint IP] - this is the IP address of the HoneyPoint host that detected the event [HoneyPoint Port] - if a network port is attacked, this is the port where the probe was received, be aware that some ports can be modified using NAT/PAT and other techniques like port forwarding, if a port is not involved, this value should be set to 0 [HoneyPoint time] - this is the time stamp from the HoneyPoint host that detected the event [event data] - this is a base64 encoded string that contains the data detected by the HoneyPoint in the offending transaction or that caused the alert Note that the [event data] variable is output in base64, so any operations done on this value will need to be base64 decoded prior to operating on the data. CAUTION: Be VERY careful in managing this string once base64 decoded, as it may contain attacker data, including binary contents. NEVER blindly pass this data into a system or process not hardened against injections, overflows and the like. Compromise of the underlying system IS POSSIBLE if this string is mishandled in an unencoded format. Extending the Plugin Mechanisms with Custom External Code In addition to the API meta-language of plugins, you can further extend HPSS with more complex logic and tasks by using scripting or development languages to create applications for the plugins to call and pass variables to. These applications can be written in any language supported by your operating system, including shell scripts, batch files, PERL, Ruby, Python,.NET, etc. To call a custom binary or script, you would simply place the script name (with path if needed), along with the desired data elements on the second line of a plugin.hpp file like this: Mylogfile plugin mylogfile.py [attacker IP] [HoneyPoint IP] [HoneyPoint Port] [HoneyPoint time] [event data]

6 Plugin Licensing Plugins may be individually licensed by their authors as they see fit. This allows independent developers to create plugins for specific tasks and either release them as open source, freeware or even commercial applications. They are free to develop, sell and support HoneyPoint plugins separate and apart from the HPSS system. MSI reserves the right to refuse support for third-party plugins, however, and they are not covered under the HPSS support agreements. Developers wishing to create new plugins can receive a complimentary community edition license of HPSS or they can use the Personal Edition of the product which offers the same functionality for quick prototyping. It is our hope that a lively ecosystem of product development be created around the HoneyPoint platform and we are actively committed to working with developers to bring new functionality and capability to the HPSS platform via the plugin mechanism. For more information about the developer program, community licenses or other plugin questions, please contact us. The contact information is on our web site and in the footer of this paper below. Obtaining Plugins Plugins may be obtained in a variety of ways. MicroSolved maintains plugins in the HPSS Resource Kit (RESKIT) on the software delivery site. Additionally, specific software downloads are available from in the HoneyPoint Security Server section. Basic default plugins are also shipped with the install of the Console. For more information on obtaining plugins, please contact us and/or check out our blog at We review new plugins and often post them through the blog site. Troubleshooting Plugins In the unlikely event that you experience trouble with plugins, here is a quick list of troubleshooting tips from the HoneyPoint Support Engineers: Check to make sure the.hpp file is in the Plugins directory and that the plugin is activated in the Console GUI. If it does not show up there and you just added it, restart the Console to reload the plugin list. If you are not seeing the results you expect, try upping the time frame allowed for execution on the third line of the plugin s.hpp file. Be sure to restart the Console application between tests. Try running the plugin command from the command line with pseudo-data in place of the event data. Does the command execute as expected? If not, fix the errors identified. Is the command from the second line of the file in the path identified? If not, either correct the path or add a direct path to the command (ex: /sbin/python) When contacting support, be ready to send in a copy of the.hpp file so that we can easily assist you. 5