Graylog2 and Powershell: best of both worlds

If you’re already a Graylog2 user or if you plan to become one (if it’s still not the case, don’t hesitate > Go go go #GetGraylog2) and you are a Powershell addict, these 3000 lines of code are for you!

It’s been a while now that we work with Graylog2 (even if we are migrating to ELK these past weeks, we’ll talk about that later) on a daily basis (which gives us a real advantage for all the troubleshooting section and huge analytic capabilities!), but it still lacked some automation features. Of course API exists already and is pretty awesome (for instance the Graylog2 web interface is mainly based on these APIs), but we were simply looking to automate tasks on the Graylog2 server(s) (like stream creations, rules, alerts …) to make our life easier and especially to make new Graylog2 server deployment quicker.

For the hardcore people among you, the API-browser is available by default to http://<graylog2-IP-server>:12900/api-browser. This browser interface is based on the well known Swagger:

In order to solve this problem, we developed this Powershell module that allows you to achieve almost everything you can do in Graylog2 via Powershell cmdlets. “Almost” because some API calls do not seem necessarily useful to be accessible through Powershell (for instance the ability to search directly via API …). The goal of this Powershell module is not to completely bypass the Graylog2 web interface but rather to make its management easier:

For the technical part (aka the good stuff), the Graylog2 API is available through RESTful which makes it very easy to manage with Powershell since v3 (which is a prerequisite to use this module, and checked with the first line of the module via the instruction #Requires -Version 3), thanks to the Invoke-RestMethod cmdlet.

However we faced a problem with Powershell when using the Invoke-RestMethod cmdlet regarding the management of TCP connections with PUT or DELETE methods (GET and POST methods do not seem to have this problem, more information are available on the website connect.microsoft.com). In some cases we had to use Invoke-WebRequest cmdlet instead.

External documentation is not yet available, but we formatted all the functions so that the Get-Help cmdlet helps you to get further information. You are free to use it to find the purpose of each cmdlet (we also tried to name all functions in an obvious way in order for them to be explicit enough most of the time), or which are the arguments:

In order to use this module’s cmdlets, you must first be connected to a Graylog2 instance (the same way as the Connect-VIServer cmdlet with PowerCLI). In order to do that, you must use the cmdlet Connect-Graylog2Server :

Import-Module C:\_Perso\GitRepo\powershell\Graylog2\Graylog2.psm1 -force
Connect-Graylog2Server -restIp 10.0.0.1 -restUsername "admin" -restPassword "graylog2rocks"

Using –force on Import-Module cmdlet enable redefinition of already existing functions (it’s very useful and timesaver during tests and update)

Authentication to Graylog2 server can be done using parameters –restUsername and –restPassword or if you don’t use them, you’ll be prompt to enter credentials (a Get-Credential popup will appear).

Once connected, some informations about Graylog2 server will be displayed and you will be able to use module’s cmdlets:

In order to give you some examples of what you can do with this module (enjoy yourselves), hypervisor.fr used it to build some One-Liner (« Hey, what did you expect » ^^) that will automatically create objects in Graylog2, here are some of them:

Streams bulk creation based on possible events (esx.problem.* esx.audit.* and esx.clear.*) from vCenter EventManager

(Get-View EventManager).Description.EventInfo|select @{n="event";e={if ($_.key -match "^EventEx$|^ExtendedEvent$") {$_.FullFormat.split("|")[0]} else {$_.key}}}|?{$_.event -match "esx\.problem|esx\.audit|esx\.clear"}|%{New-Graylog2Stream -title $_.event -enabled}

StreamRules creation for each stream

Get-Graylog2Streams|?{$_.title -match "esx\.problem|esx\.audit|esx\.clear|vob\."}|%{New-Graylog2StreamRule -stream_id $_.id -field "full_message" -value $_.title -type "match regular expression"}

Alert condition bulk creation for each streamrules

Get-Graylog2Streams|%{New-Graylog2StreamAlertConditions -streamId $_.id -conditionType "message_count" -thresholdType "more" -grace 1 -threshold 0 -time 1}

Adding a receiver for each alert

Get-Graylog2Streams|%{New-Graylog2StreamAlertReceivers -streamId $_.id -type "users" -entity "alert"}

New cmdlets will definitely be added later (as everything isn’t done yet), and don’t hesitate to comment, we’ll be grateful for any feedback ^^

You can download this module straight from our GitHub repository (as posted previously).

git clone git@github.com:v-team/powershell-graylog2.git

Leave a Reply

Required fields are marked *.