Real-time system alerts using Twitter OAuth (implementation)

In this article I explain how to implement the solution discussed in the article called System real-time alerts using Twitter (the Theory)

Article published on 6 June 2010
last modification on 29 May 2016

by Emeric Nasi

Note: In order to understand this document it is strongly recommended you already read the theory article.
Also the author suppose the reader have a good base about GNU Linux and security.
English is not my first language, do not hesitate to point our any "bad writing".
License : Copyright Emeric Nasi, some rights reserved
This work is licensed under a Creative Commons Attribution 4.0 International License.
Creative Commons License

Introduction

I really like Twitter. I opened my own account a few days ago.
I was looking at the Twitter features. I just tough that Twitter could be used for more than public communications.
A problem you may face when dealing with monitoring is the reaction time. And having real-time alerts is the big issue.
I found out Twitter’s API could be used for that, in a more secure way then classic emails.
I implemented this solution and I will present it to you using two articles.
This is the second article, in which we are now going to implement the solution we discussed in the first one.

Warning : You should really read the "Theory" article and learn about OAuth before you try to implement the solution proposed in this article.

I Choose the tools

So what do we need?

  • An entity that watches logs and that has real-time actions enabled.
  • An entity that can use the Twitter over OAuth

I.1 Swatch for the real-time alert

I choose swatch because it is simple to understand and it is enough for what we are going to do.
The basic Swatch functioning is simple. It watches a file for any new added text. If the new text contains a certain string or pattern,
it will action an alert mechanism. This alert can be an echo, sending a mail, executing another program, etc.
Install swatch :
apt-get install swatch # for Debian based distrib
yum install swatch # for RedHat based distrib

I.2 Perl for the OAuth/Twitter API

Among the possible languages, I choose perl because it is fast and easy to write a program that does just what we need with it.
Perl has also a Twitter module that is well documented and easy to use.

Note : I am not especially a Perl fan but the Twitter module really convinced me.

First install perl if it isn’t already installed on your system (that is quite unprobable).
apt-get install perl # for Debian based distrib
yum install perl # for RedHat based distrib
After that install the OAuth CPAN perl module.
perl -MCPAN -e "install Net::OAuth"
When you have done that, you can implement OAuth calls and write your own
Twitter over OAuth code.
However why reinvent the wheel when a nice Twitter over OAuth module already exists?
Install this module :
perl -MCPAN -e "install Net::Twitter"

Note : The previous command might ask you to install a lot of dependencies, you should be alright by sticking to default proposals.

II Configure the tools

Note : Most of the below code comes from my application Thylacine (not yet released).

II.1 Create a special monitoring group.

groupadd -f --system thyl_g_monitor

II.2 Create the system directories.

II.3 Create perl script.

Perl’s Net::Twitter module allows easy access and manipulation of the Twitter API, includind OAuth authentication.
In our case, after authentication, we are going to use the private message (direct message) call.
What is great about private message is that if you have activated the mobile features, you will also receive the alert by sms.
This script must be called with one parameter (the system alert)
and will send our system alert via private messages to our own Twitter account.

Create the file :
touch /etc/sevagas/monitor/twitter/the_bird_sentinel.pl
chmod 750 /etc/sevagas/monitor/twitter/the_bird_sentinel.pl
Now open it with your favorite text editor and paste the next code

Note : Replace the text "< your Twitter account >" by your Twitter account (at the end of the file).

II.4 Follow Twitter OAuth workflow

Open your favorite navigator and log into your Twitter account.
Register for OAuth applications at http://twitter.com/oauth_clients
Correctly fill in the form. We assume the application name is The bird sentinel.
Choose "Client" application type, choose "Read and write" default access type and check "Yes, use Twitter for login". Then validate the form.
>> You should see a "Success" message.
The page your are on now is very important, you should note down all informations.
Type the following instructions :

After that, launch our perl script manually for initial authentication.
Be sure you are still logged into your Twitter account.
/etc/sevagas/monitor/twitter/the_bird_sentinel.pl "Hello!"
The script should suggest you to authorize the application at a given twitter address and enter a pin code.
Open your navigator at that address and accept to authorize the bird sentinel application.
>> You’ve successfully granted access to the bird sentinel!
Type the pin code in the script console and press enter.
OK you are now authorized to use the twitter API !!!
To verify that it worked, go to your Twitter account, you should have received a new private message :-).
You should also observe that the access token files are created in /etc/sevagas/monitor/twitter/

II.5 Configure swatch.

Swatch real-time alert is nice but the default installation has some lacks we are going to correct.
First we are going to run swatch daemon as its own system user.
useradd --system --no-user-group --gid thyl_g_monitor --groups adm  -s /bin/false  --comment "Swatch System User" thyl_u_swatch

Note : We added the swatch user to the group ’adm’ to allow it to read system logs (/var/log/message for example)

Now swatch will run as ’thyl_u_swatch’ and will be able to read any files whose group is ’thyl_g_monitor’ or ’adm’.

Swatch generates some temporary files we want to clean.
We are going to write a cron job for that :

Now we are ready to configure our swatch for twitter daemon!
We can do much more but for our example we are going to watch the file /var/log/messages for any new message containing the word "bird_alert".
We create the swatch configuration file :
(umask 037 &&  touch "/etc/sevagas/monitor/swatch-twitter.conf")
Now edit the file /etc/sevagas/monitor/swatch-twitter.conf :

Now create the init script to launch our daemon:
(umask 077 && touch /etc/init.d/swatch-twitter)  
Edit /etc/init.d/swatch-twitter and add next code :

Make script executable :
chmod 700 /etc/init.d/swatch-twitter
Install rc.d :
update-rc.d  swatch-twitter defaults # Starts at runlevel 2,3,4,5

III Test and Adapt

III.1 A quick test!

Run the swatch daemon :
/etc/init.d/swatch-twitter start
>>You should have the tmp files in etc/sevagas/monitor/tmp/
Now lets test our system!
echo "bird_alert : this is an alert" >> /var/log/messages
You can log into your twitter account and check your private messages, you should find a nice message containing "bird_alert : this is an alert" !!!

Pfiew, we are arriving at the end of this article. You can now modify the previous scripts
to adapt them at your own needs! You can combine this system with an IDS a firewall or any other soft that writes logs.

However, before doing anything read the next section...

III.2 Caution!

Be careful not to spam or flood Twitter with your logs!
You should only send the really bad alert and do not send the same alert again and again
Maybe you should keep the "bird_watcher" string required so you are sure other logs wont flood your twitter account.
Just be sure critical logging has the string "bird_watcher" inside the log.
Another thing, twitter has maximum 140 characters messages, if you want to send bigger messages, implement a system that truncates big messages in smaller ones.
Finally remember that Twitter has implemented the next limits :

  • Direct Messages: 250 per day
  • API Requests: 150 per hour
  • Updates: 1000 per day
Note : Because direct messages are limited, alternative to the previous perl script would be to use status updates instead of direct messages. You can configure your account so that your status updates are private.

However, I hope that you won’t need more than 250 messages a day... 250 different critical alerts in one day means you don’t sleep to much...
And you should do a general security review of your systems!
Read more about Twitter imposed limits at http://help.twitter.com/forums/10711/entries/15364