Create New Plugins Using the Plugin Builder

Applies to Product: USM Appliance™ AlienVault OSSIM®

In addition to the other methods described for customizing or creating new USM Appliance plugins, you can also use the Plugin Builder provided in the USM Appliance web UI to create new custom plugins. The plugin builder provides an interactive smart wizard program that guides you through the process of automatically creating and configuring a new plugin to deploy with the USM Appliance.

Using the Plugin Builder to Create a New Custom Plugin

The Plugin Builder wizard program lets you upload a sample log file which it then uses to identify data to be normalized into USM Appliance event fields for a new plugin.

To Use the Plugin Builder

  1. Select the Configuration > Deployment option from the USM Appliance web UI.

  2. Select the Plugin Builder tab.

    The USM Appliance web UI displays a list of any custom plugins previously created with the Plugin Builder.

    Note: The Plugin Builder display only shows new plugins created using the Plugin Builder. It does not show any other custom plugins that may have been created or customized outside of the Plugin Builder. However, you can locate those plugins by viewing the contents of the USM Appliance plugin configuration folder: /etc/ossim/agent/plugins.

    You can also view and enable the custom plugins by establishing an SSH connection to the AlienVault Console SSH management interface used to perform setup and configuration tasks for USM Appliance with options from the AlienVault Setup menu. and selecting the Configure Sensor > Configure data source plugin option from the AlienVault Setup menu.

  3. Click the Add New Plugin button.

    4. The USM Appliance web UI displays the first step of the Plugin Builder wizard. You are prompted to select a sample log file the Plugin Builder will use to identify data that can be normalized into USM Appliance event fields.

    Display showing dialog box to upload sample log file.

  4. Click the Browse button to navigate to the location of the sample log file you want to use to identify possible event field mapping.

    After you choose a log file, the Plugin Builder determines whether it can upload the file for event field mapping and displays a green checkmark if successful.

  5. Click Next.

    The Plugin Builder advances to step 2 in which you are prompted to enter information about the source of the log file.

    Display showing dialog box to specify plugin properties.

    Note: Vendor and Model entries may not contain spaces or special characters. Only the plugin ID is included in the plugin configuration filename. Vendor, model, and version information is included into the plugin file header.

  6. For the Product Type field, select the product type from options displayed in the popup list. (The categories list match the USM Appliance SIEM taxonomy. When you have finished the Plugin Properties entries, click Next.

    The Plugin Builder now displays the initial mapping of log file entries to USM Appliance event fields for specific named event rules.

    Display showing dialog box to define event types from detected event patterns.

    The top portion of the display shows data contained in the sample log file you submitted and the bottom portion displays corresponding event field mapping that the Plugin Builder identified for one or more named event rules.

  7. Click the Edit () button.

    The Plugin Builder displays a set of fields in which you can edit the name, category (and subcategory) that will be used in USM Appliance when events matching specific rules will be generated by the plugin.

    Display showing window to edit properties of selected event types.

    In the area below the event property fields, the Edit Tokens section lets you edit or update data tokens assigned or mapped to USM Appliance event fields.You can also map additional unassigned data patterned after the log data and assign those data tokens to new event fields.

    • In the Edit Tokens section, clicking on highlighted keywords shows the mapping of token data to assigned event fields. The Plugin Builder shows the current token mapping in a dialog box at the bottom of the display. You can adjust the slider at the bottom to change the token mapping and change other attributes of the event field mapping.
    • Clicking on non-highlighted token data in the upper portion of the display lets you create additional log data to event field mappings in the dialog box shown at the bottom of the display.

    Display showing window to categorized events.

    You can use the sliding bar at the bottom of the display to adjust the beginning and ending points of data tokens taken from the sample log file that are mapped to event fields.

  8. Click the Return () link after revising or adding any additional log data you want to map to event fields.
  9. Click Save & Close and then click Next.

    Display showing dialog box to review plugin information and finish plugin.

  10. Click the Finish button to complete creation of the new plugin.

    When you click the Finish button, the Plugin builder creates both the configuration (.cfg) file and the .sql file for the new plugin.

    After creating the new plugin, the USM Appliance Plugin Builder wizard returns to the main custom plugins display page where it shows the new plugin you just created.

Note: The current Plugin Builder does not allow re-editing of custom plugins from the USM Appliance web UI. You can, however, open the plugin configuration file directly with a text editor and make additional configuration changes. (Custom plugins are saved in the /etc/alienvault/plugins/custom folder.) You can also delete the existing plugin from the Plugin Builder's tabular list view, delete an existing plugin, and then start over to make a new plugin using the Plugin Builder wizard.

Deploying Custom Plugins

You can use custom plugins created with the Plugin Builder the same way as all other plugins, by enabling the plugin for individual assets or on a USM Appliance sensor. After creating a new custom plugin, the plugin configuration file is saved to the USM Appliance Server (for USM Appliance All-in-One) and also distributed to all configured remote or external sensors. The plugin .sql file is automatically applied to the USM Appliance Server database. There is no need to copy and run the plugin .sql on external sensors, because they do not have a separate database.

Note: Export or manual copying of plugin .cfg configuration and .sql files is only necessary if you want to deploy a new custom plugin to other USM Appliance installations deployed in your environment. Exporting a new custom plugin only exports the plugin .cfg configuration file. So, you will still need to manually download the plugin .sql file and apply it to the databases associated with any other USM ApplianceServer installations you have deployed in your environment.