Applies to Product: | USM Appliance™ | LevelBlue OSSIM® |
Database plugins extract data from an external database and turn them into Events. USM Appliance supports MySQL and Microsoft SQL Server using the UTF-8 character set encoding.
The database plugin configuration file provides information on how USM Appliance should connect to and query the database.
# Plugin mcafee-epo id:4008 version: 0.0.2
# Last modification: 2015-05-13 16:11
#
# Plugin Selection Info:
# McAfee:ePolicy Orchestrator:-
#
# END-HEADER
# Accepted products:
# mcafee - epo_mcafee_virtual_technician 1.0.9
# Description:
# McAfee EPO plugin
# MSSQL connection can be configured using a static port or
# a dynamic port (using instances)
# Static port config:
# source_ip=database_addr_or_hostname
# source_port=database_port (empty = default port 1433)
#
# Dynamic port config:
# source_ip=database_addr_or_hostname\database_instance (note: only one '\')
# no source_port
#
[DEFAULT]
plugin_id=4008
[config]
type=detector
enable=yes
custom_functions_file=/etc/ossim/agent/plugins/custom_functions/mcafee_epo_custom_functions.cfg
source=database
source_type=mssql
source_ip=
source_port=1433
user=db_user
password=db_pass
db=db_epo
sleep=60
process=
start=no
stop=no
[start_query]
query="SELECT TOP 1 AutoID FROM EPOEvents ORDER BY AutoID DESC"
regexp=
[query]
query="SELECT AutoID, CONVERT(nvarchar(40), AutoGUID), ServerID, DetectedUTC, SourceIPV4, TargetIPV4, TargetUserName, TargetFileName, ThreatCategory, ThreatEventID, ThreatSeverity, ThreatName FROM EPOEvents where AutoID > $1 ORDER BY AutoID"
regexp=
ref=0
plugin_sid={$9}
date={normalize_date($3)}
src_ip={:mcafeeIP($4)}
dst_ip={:mcafeeIP($5)}
filename={$8}
username={$6}
userdata1=GUID {$2}
userdata2=ServerID {$2}
userdata3=Severity {$10}
userdata4={$9}
userdata5={$11}
userdata6={$1}
Anatomy of the Plugin Configuration File
See below for a description of various sections in the database plugin configuration file above.
In the database plugin configuration file example, the section that starts with [config] tells USM Appliance how to connect to the database. This consists of the following parameters.
[config]
type=detector
source=database
source_type=
source_ip=
source_port=
user=
password=
db=
sleep=
Parameter | Description |
---|---|
source_type | Database type that USM Appliance supports, which is mssql or mysql. |
source_ip | Fully qualified domain name, hostname, or IP address. |
source_port | Port number of the external database. |
user | Name of the user with access to the database. |
password | Password for user with access to the database. |
db | Machine name of the external database. |
sleep | Duration, in seconds, between plugin queries to the database. |
To find the point where the database plugin should begin capturing data, USM Appliance uses a query called start_query. This query obtains the last row in a table identified by a sequence number. The following code example initiates a query to select the largest AutoID number from the EPOEvents table.
[start_query]
query="SELECT TOP 1 AutoID FROM EPOEvents ORDER BY AutoID DESC"
USM Appliance queries the database as soon as a database plugin is loaded and, thereafter, every few seconds.
The duration between queries depends on the value of sleep in each plugin's configuration file. Default values range from 2 to 60 seconds and are configurable. For information about customizing existing or developing new plugins, see Customize and Develop New Plugins and its related topics.
This query starts with [query] and also references the [start_query] code line, shown in bold below.
[query]
query="SELECT AutoID, CONVERT(nvarchar(40), AutoGUID), ServerID, DetectedUTC, SourceIPV4, TargetIPV4, TargetUserName, TargetFileName, ThreatCategory, ThreatEventID, ThreatSeverity, ThreatName FROM EPOEvents where AutoID > $1 ORDER BY AutoID"
regexp=
Important: You must leave the regexp field empty (shown below the query), because database plugins use it in operation.
Fields containing $ correspond to fields in the database query. For example
$0 | First element in the query (AutoID) |
$1 | Second element in the query (AutoGUID) |
$2 | Third element in the query (ServerID) |
... | """" |
And you can map them to any of the event fields, like this
username={$6}
userdata1=GUID {$2}
userdata2=ServerID {$2}
userdata3=Severity {$10}
userdata4={$9}
userdata5={$11}
userdata6={$1}
Modify the Plugin Configuration File
Before modifying the plugin configuration file, you must first obtain the IP address, port number, and an authenticated user account of your database.
Warning: For Microsoft SQL Servers, you must use SQL Server Authentication. You will receive a "Connection refused" error if you use Windows Authentication instead.
This task enables communication with the external database from which the plugin receives data. You will need command line access to USM Appliance to complete this task.
To configure communication with an external database
-
Connect to the LevelBlue Console through SSH and use your credentials to log in.
The LevelBlue Setup menu displays.
-
On the LevelBlue Setup main menu, select Jailbreak System to gain command line access.
Select Yes when prompted. You will be in the root directory.
-
Create the file /etc/ossim/agent/plugins/<database-plugin>.cfg.local.
For example, to configure the mcafee-epo plugin, you need to create the mcafee-epo.cfg.local file.
-
In the .local file, add the fields shown below and replace the angle bracket part (including the brackets) with your database settings.
[config]
source_ip=<database_IP>
source_port=<database_port>
user=<username>
password=<user_password>
db=<database_name>
sleep=<number_of_seconds_between_sending_queries>
- Save the file.
-
Restart all services for changes to apply:
alienvault-reconfig -c -v -d
Important: If connecting to multiple databases, you must repeat this task for every external database you want to receive data from. In other words, you must create a different <database-plugin>.cfg.local file for each database you want to connect to.
If you do not see any events in Analysis > Security Events (SIEM) after you have modified the plugin configuration file and enabled the plugin, you can troubleshoot the database connection using tcpdump or ngrep. The following example examines the traffic to a MSSQL database.
ngrep -d eth0 host 10.10.10.10
where 10.10.10.10 is the IP address of the database server. If the database connection is established, you will see output similar to the following. You can confirm the user name, password, and database name (high-lighted in bold) from the output.
interface: eth0 (10.10.10.10/255.255.255.224)
filter: (ip or ip6) and ( host 10.10.10.10 )
......
#####
T 10.10.10.20:54983 -> 10.10.10.10:1433 [AP]
........10.10.10.10..................siem.................... PASSWORD
..............37876...............pymssql............10.10.10.10............
...... PASSWORD....................DB-Library........us_english.............
....L.........................ANSI_X3.4-1968..................512............
#
T 10.10.10.10:1433 -> 10.10.10.20:54983 [AP]
.....g.......ePO4_HOSTNAME17.master.B.E.....-.Changed database context to
'ePO4_HOSTNAME17'..HOSTNAME15........iso_1... .......Microsoft SQL
Server.._........512.512.........
If the database connection cannot be established, you will receive an error instead.