Automating your server security is about more than just one great tool – it’s also about linking together multiple tools to empower you with the information you need to make decisions.
Halo can deliver a wealth of information about security issues on your server, from firewall changes, access changes, software vulnerabilities, and file integrity monitoring alerts. However, the next step to integrating that information into your workflow is to deliver those events into an aggregation tool like Splunk to help you monitor and analyze your environment. Apurva, our Professional Services guru here at CloudPassage, has developed an integration script for just this purpose.
The purpose of the Halo event script is to retrieve event data from a CloudPassage Halo account and import it into an external tool such as Splunk for indexing or processing. It is designed to execute repeatedly, keeping the external tool up-to-date with Halo events as time passes and new events occur. More details about the capabilities of this integration script can be found in the full documentation in the GitHub repo.
First, download the Event Connector script (haloEvents.py) and associated files here. Then, retrieve your secret Halo API key and public ID from your Halo Portal under Settings > Site Administration > API Keys.
Copy them into a text file so that it contains a line with the Key ID and Secret on it separated by the “|” (vertical pipe) operator, as below:
Save the file as haloEvents.auth, in the same directory as haloEvents.py. Next, you’ll probably want to test the script on its own before feeding it into Splunk.
Set the variable PATH to include the location of haloEvents.py and the Python interpreter.
Set the variable PYTHONPATH to include the location of the Python libraries and the Python interpreter.
Execute the script on the command line, from the appropriate directory:
$ python haloEvents.py
Run the script a few times, experimenting with arguments (pdf) to save output to a file, or to produce other output formats. Once you have an idea of what you want, place all of these files:
- cpapi.py and cputils.py
- remote_syslog.py ( if you are running on Windows and you want to generate syslog output)
into the following location in your Splunk installation:
$SPLUNK_HOME/bin/scripts/ (for Linux)
%SPLUNKHOME%binscripts (for Windows)
Your script will emit the default output format (JSON) for Splunk. You need to specify how Splunk should interpret the JSON and extract the timestamp for each event. To do that, add the following lines to your Splunk props.conf file, in the directory $SPLUNK_HOME/etc/system/default
[cp-halo] ← This defines a new source type in Splunk; use any name you wish
NO_BINARY_CHECK = 1
SHOULD_LINEMERGE = false
TIME_FORMAT = %Y-%m-%dT%H:%M%S.%6N
TIME_PREFIX = “created_at”:s?”
pulldown_type = 1
KV_MODE = json
Note: You will require a restart of the Splunk Server for it to recognize the newly created sourcetype.
Now, log into Splunk Home and click Add Data and then Run and collect the output of a script.
Fill in these fields:
Fill in these fields and Save:
- Command field—Enter the full path to haloEvents.py.
- Interval field—Enter the time in seconds between successive automatic executions of the script. In a production environment, a value for this field between 300 (5 minutes) and 86400 (1 day) might be reasonable, depending on the rate of event production from Halo and the desired immediacy of reporting in Splunk.
- Set sourcetype field—Choose “From list”.
- Select source type from list field—Select the source type value that you specified in the Splunk props.conf file.
Once the script runs successfully and is incorporating event data into Splunk, you will see Halo events such as the following appear in your Splunk searches:
That’s it! Now your Halo events are feeding into your Splunk tool automagically, and you can search and analyze them as you please.
Do you have any suggestions or requests for how we can improve our integration? Please let us know by commenting below!