Note: I mistakenly sent this post to only paying subscribers yesterday, but it was supposed to be for all subscribers. I apologize to those of you who are getting this twice.
OSSEC is a popular Host Intrusion Detection System (HIDS). It is very capable out of the box at notifying system administrators of indicators of compromise such as suspiciously changed files and taking action against badly behaving IP addresses that are doing nasty things like credential stuffing. OSSEC doesn’t need a lot of fancy configuring - its basic functions just work after install, and most of the fun comes from configuring it. This article isn’t a deep dive into OSSEC, but it is an overview of one of my favourite features: OSSEC custom integrations.
Daniel Cid is the original author of OSSEC and maintains his own OSSEC fork and instruction here. Once you have OSSEC installed following those instructions, continue on for some fun.
Custom integration support
You should find OSSEC in /var/ossec. We’re going to pay attention to two things within that directory:
/var/ossec/etc/ossec.conf file, and
/var/ossec/integrations/ directory
The custom integration feature of OSSEC is a simple, but really powerful feature, that allows system administrators to cause arbitrary things to happen in response to an OSSEC action. Primarily, I use custom integrations to send OSSEC block data to customer SIEMs such as Splunk. However, a custom integration can call any executable file so the possibilities are literally endless.
The basic custom integration script
Integrations are executable files and the basic criteria for an integration to fire upon an OSSEC event are:
Each integration is associated with a log file that OSSEC is monitoring
The integration file must live in /var/ossec/integrations/
The integration file must be named custom-$FOO, where $FOO is arbitrary.
The integration file must be configured in the /var/ossec/etc/ossec.conf file
Let’s look at at a shell script that will send data to an HTTP endpoint:
#!/bin/sh ALERTFILE=$1 APIKEY=$2 WEBHOOK=$3 # Send it curl --data "$alertlog" "$WEBHOOK"OSSEC sends the log file, any configured API key, and the endpoint to the script. We capture those in the ALERTFILE, APIKEY, and WEBHOOK variables, but that is not necessary. It just makes the script easier to understand.
OSSEC also populates a variable named $alertlog which contains the actual log entry that triggered the alert.
If you’re sending data to and endpoint that needs authorization, use the APIKEY. For example, the curl call would look like this if the endpoint was a Splunk HTTP Event Collector (HEC):
curl -H "Authorization: Splunk $APIKEY" --data "$alertlog" "$WEBHOOK"Obviously, you would want to include some error checking and logging into this script. You can also manipulate the heck out of the content of that $alertlog variable to customize the payload or extract/inject interesting data. I have a few integrations where I have added data, such as GEO IP data, to the payloads before sending them out. But, these are the bare bones you'd need in order to send data to some endpoint, such as a Splunk HEC.
Triggering the custom integration
Because the integration is just a script or some other executable file, you can build it and test it just like any other piece of software. However, once you’re happy with it, just plunking it into the /var/ossec/integrations/ directory isn’t going to work. You still need to tell OSSEC about it.
If the script above is saved in /var/ossec/integrations/custom-basic_script, then we would need to configure the /var/ossec/etc/ossec.conf file with a section like this:
<integration> <name>custom-basic_script</name> <event_location>jonwatson.ca.</event_location> <api_key>45TERT$GU)JHTE</api_key> <hook_url>https://my_splunk.instance/services/collector</hook_url> </integration> This configuration tells OSSEC to fire the /var/ossec/integrations/custom-basic_script file whenever an event is logged about the jonwatson.ca site in the OSSEC log.
The event will be sent to https://my_splunk.instance/services/collector using the 45TERT$GU)JHTE< API key if I use the second curl example which utilizes the -H Authorization header.
Other ideas
I primarily use the custom integrations to send data to SIEMs, but there are others. There are PagerDuty and Slack integration scripts that do other things under different criteria. That is how we get OSSEC to let us know of more critical things it is seeing. There are a million things you can do with these custom integrations, even kicking off a runbook or series of events. If you have any interesting OSSEC integrations running, I’d like to hear about them in the post comment.
Custom OSSEC Integrations