Create Linux User Login Monitor on Monitis

Monitis provides the ability to monitor almost any operation on your server

Jun. 15, 2011 04:28 AM

Monitis provides the ability to monitor almost any operation on your server. Using simple Linux tools and scripts you are able to monitor each time a user logs into the server and capture various information, including username, host address and login service. Using pam_script and bash scripts, you are able to transmit information to a Custom Monitor with this information.

API Access

The first thing you will need in order to create this monitor is the Monitis API Key and Secret Key. The API Key is a alphanumeric code that allows you to access the Monitis API url’s and transmit or receive data about your Monitis services. The Secret Key is an alphanumeric code that allows you to digitally sign your information to ensure that only you can transmit data to your Monitis account. Your API Key may be disclosed to anyone, but your Secret Key must be maintained private and should not be shared nor transmitted. To obtain your Monitis API Key and Secret Key, log into your account and from the top menu bar, go to Tools then API then API Key, it will display both your API Key and your Secret Key.

Now let’s test your API access. You should be able to connect and get an Auth Token:

curl 'http://www.monitis.com/api?action=authToken&apikey=[API Key]&secretkey=[Secret Key]&version=2'

In the above command you should replace [API Key] and [Secret Key] with your API Key and Secret Key. We are using curl in order to connect to http://www.monitis.com and access the API to get a Auth Token. The return value is json and sends back something similar to:

{"authToken":"3TVQN32TIP1DN71OB4GOML1D7N"}

Where the alphanumeric code will be your Auth Token. You can use your Auth Token to validate against the API later. However sending your Secret Key is not extremely secure, others could possibly obtain your Secret Key this way. The more secure method of authenticating is to send your data using POST instead of GET and using a Base64-encoded RFC 2104-compliant HMAC signature to sign the post data. The signature is sent in the checksum parameter of the POST data. To calculate the checksum you must follow these rules:

sort all parameters alphabetically by name (excluding the checksum parameter)
concat all parameter names and values like this: name1value1name2value2…
create Base64-encoded RFC 2104-compliant HMAC signature using Secret Key

The final rule can be calculated using openssl:

echo -en “name1value1name2value2” | openssl dgst -sha1 -hmac [Secret Key] -binary | openssl enc -base64

Creating a Custom Monitor

In order to create a custom monitor, you must send a POST request to the API. This POST request must contain several parameters: action, name, resultsParams, and tag (refer to http://monitis.com/api/api.html#addCustomMonitor for specifications). We will use the following specifications for the params:

action=addMonitor
name=Login Monitor
resultsParam=user_login:Login Name:logins:3;host:Host Address:hostaddress:3;srv:Service:service:3
tag=loginMonitor

There is other necessary information in order to communicate with the API:

apikey=[API Key]
timestamp=[Current UTC time]
version=2

In order to create our new monitor called Login Monitor we would post this data plus a checksum to http://monitis.com/customMonitorApi which is the Custom Monitor API url. Here is a simple script that will accomplish this:

#!/bin/bash # create a Custom Monitor for Monitis # Be sure to modify the API Key and Secret Key ACTION="addMonitor" APIKEY="[API Key]" NAME="login monitor" RESULTPARAMS="user_login:Login Name:logins:3;host:Host Address:hostaddress:3;srv:Service:service:3" TAG="loginMonitor" TIMESTAMP=`date -u +"%F %T"` VERSION="2" SECRETKEY="[Secret Key]" URL="http://monitis.com/customMonitorApi"

# Create Checksum CHECKSUM_STR="action"$ACTION"apikey"$APIKEY"name"$NAME"resultParams"$RESULTPARAMS"tag"$ TAG"timestamp"$TIMESTAMP"version"$VERSION CHECKSUM=$(echo -en $CHECKSUM_STR | openssl dgst -sha1 -hmac $SECRETKEY -binary | openssl enc -base64 )

# Post Data to API POSTDATA="--data-urlencode \"action="$ACTION"\" --data-urlencode \"apikey="$APIKEY"\" --data-urlencode \"name="$NAME"\" --data-urlencode \"resultParams="$RESULTPARAMS"\" --data-urlencode \"tag="$TAG"\" --data-urlencode \"timestamp=$TIMESTAMP\" --data-urlencode \"version="$VERSION"\" --data-urlencode \"checksum="$CHECKSUM"\""

eval "curl ${POSTDATA} $URL"

Save the above script into a file called monitis_create_monitor.sh, be sure not to change the order of the variables in the checksum calculation as they must be in alphabetical order. Ensure to make this file executable:

chmod 755 monitis_create_monitor.sh

Now run it:

./monitis_create_monitor.sh

The output should look similar to this:

{"status":"ok","data":305}

This is showing us that the monitor was successfully created and that the id of the resulting monitor is 305. If you go to your Monitis account now, you will be able to access this monitor. From the top level menu, go to Monitors then Manage Monitors and then Custom Monitors. Here you should find the Login Monitor. Click the check box next to the title and then click Add to Window. A window will pop up below the Custom Monitors dialog box. Close the Custom Monitors dialog box and you will see your new monitor there. But no data has been sent to it, so it is not that interesting.

Sending Data to Custom Monitor

In order to send data to your Custom Monitor, you must provide the action, monitorId, checktime, and results (refer to http://monitis.com/api/api.html#addCustomMonitorResult for specifications). The action is addResult, the monitorId is the id that was returned to us in the previous example (If you forgot the id, don’t worry we will get it back), the checktime is the timestamp of the results data, and the results is a string of the parameters and values in this format: name1value1;name2value2

The following script will send data to your Custom Monitor:

# add result to Custom Monitor for Monitis

#!/bin/bash usage() { cat << EOF usage: $0 options

This script will add results to a Custom Monitis Monitor.

OPTIONS: -h Show this message -a api key -s secret key -m monitor tag -i monitor id -t timestamp (defaults to utc now) -r results name:value[;name2:value2...] EOF }

APIKEY= VERSION="2" SECRETKEY= URL="http://monitis.com/customMonitorApi" OUTPUT="xml" MONITOR= ID= CHECKTIME=`date -u +"%s"000` TIMESTAMP=`date -u +"%F %T"` RESULTS= SESSIONACTION=

while getopts "ha:s:m:i:t:r:s:" OPTION do case $OPTION in

h) usage exit 1 ;; a) APIKEY=$OPTARG ;; s) SECRETKEY=$OPTARG ;; m) MONITOR=$OPTARG ;; i) ID=$OPTARG ;; t) CHECKTIME=$OPTARG ;; r) RESULTS=$OPTARG ;; esac done

if [[ -z $APIKEY ]] || [[ -z $SECRETKEY ]] || [[ -z $MONITOR$ID ]] || [[ -z $RESULTS ]] || [[ -z $CHECKTIME ]]
then
usage
exit 1
fi

# Get id of monitor if not provided
if [[ -z $ID ]]
then
XMLID=$(curl -s "$URL?apikey=$APIKEY&output=$OUTPUT&version=$VERSION&action=getMonitors&tag=$MONITOR" | xpath -q -e /monitors/monitor/id)
ID=${XMLID//[^0-9]/}
fi

# Add monitor result
ACTION="addResult"
# Create Checksum
CHECKSUM_STR="action"$ACTION"apikey"$APIKEY"checktime"$CHECKTIME"monitorId"$ID"results"$ RESULTS"timestamp"$TIMESTAMP"version"$VERSION
CHECKSUM=$(echo -en $CHECKSUM_STR | openssl dgst -sha1 -hmac $SECRETKEY -binary | openssl enc -base64 )
# Post Data to API

POSTDATA="--data-urlencode \"action="$ACTION"\" --data-urlencode \"apikey="$APIKEY"\" --data-urlencode \"checktime="$CHECKTIME"\" --data-urlencode \"monitorId="$ID"\" --data-urlencode \"results="$RESULTS"\" --data-urlencode \"timestamp=$TIMESTAMP\" --data-urlencode \"version="$VERSION"\" --data-urlencode \"checksum="$CHECKSUM"\""

eval "curl ${POSTDATA} $URL"

Save this file to monitis_add_result.sh and make executable. You can run it with no parameters to get a help menu, that should be self-explanatory. You can either provide the API Key and Secret Key on the command-line or fill in the script to contain it. The script will provide you with the monitorId if you forget yours, but you will have to know the tag name you gave to your Custom Monitor when you created it. Therefore, either your tag or your monitorId is required to run this script.

Capturing Information on Login

Now that we have a script to send data to the Custom Monitor, we need to have data to send. This script could easily be run from .bashrc or /etc/bashrc – and that would work fine, if we knew that no user would be deleting their .bashrc. Since we cannot guarantee that, we will use PAM (Pluggable Authentication Module) to control how and when we send information to the Custom Monitor. Since no user without root access will be able to alter PAM, this is a secure way to guarantee login information. Also since sshd, sftp, ftp, and most other programs utilize PAM for authentication, this will monitor all logins to the server, not just shell logins.

PAM offers many options and modules, we will be utilizing a module called pam_script. pam_script allows you to execute a script on session open, session close, and/or on auth. You must download and install pam_script first:

wget 'http://freshmeat.net/urls/47ddad89e38001dbe0dc50424e36987b' -O libpam-script.tar.gz tar -xzvf libpam-script.tar.gz cd libpam-script-x.x.x #x.x.x is the version that you just download, apparent from tar output make sudo cp pam_script.so /lib/security/ sudo chown root:root /lib/security/pam_script.so sudo chmod 755 /lib/security/pam_script.so

pam_script is now installed, but not configured. There are three files associated with pam_script, /etc/security/onsessionopen /etc/security/onsessionclose /etc/security/onauth The first two files will work on a session and the last will work for a successful auth. Since we want to monitor successful auths, we will create the onauth file:

#!/bin/sh # onauth for Monitis Custom Login Monitor USER=$1 SERVICE=$2 HOST=$PAM_RHOST

/etc/security/monitis_add_data.sh -m loginMonitor -r "user_login:$USER;host:$HOST;srv:$SERVICE"

This script will require that you move the monitis_add_data.sh script to /etc/security and make it and the onauth script executable by root and owned by root:

sudo mv monitis_add_data.sh /etc/security sudo chmod 700 /etc/security/monitis_add_data.sh sudo chown root:root /etc/security/monitis_add_data.sh sudo chmod 700 /etc/security/onauth sudo chown root:root /etc/security/onauth

Now we need to set PAM to utilize the pam_script module. Depending on your system this will vary, but you need to edit the /etc/pam.d/common-auth file or something similar on your system. You should add the following line:

# require the scripts to run at auth auth required pam_script.so runas=root expose=rhost

Here we are telling module to run as root and to expose the rhost variable, which will contain the remote host information that we utilize in the above script with the $PAM_RHOST variable

Testing the Monitor

Now we have a setup that will log all usernames, remote hosts, and service that they logged in from to our Custom Monitor. Give it a try, ssh to your machine several times. You will see the values appear in your account’s Custom Monitor.

Read the original blog entry...

About Hovhannes Avoyan
Hovhannes Avoyan is the CEO of Monitis, Inc., a provider of on-demand systems management and monitoring software to 50,000 users spanning small businesses and Fortune 500 companies.

Prior to Monitis, he served as General Manager and Director of Development at prominent web portal Lycos Europe, where he grew the Lycos Armenia group from 30 people to over 200, making it the company's largest development center. Prior to Lycos, Avoyan was VP of Technology at Brience, Inc. (based in San Francisco and acquired by Syniverse), which delivered mobile internet content solutions to companies like Cisco, Ingram Micro, Washington Mutual, Wyndham Hotels , T-Mobile , and CNN. Prior to that, he served as the founder and CEO of CEDIT ltd., which was acquired by Brience. A 24 year veteran of the software industry, he also runs Sourcio cjsc, an IT consulting company and startup incubator specializing in web 2.0 products and open-source technologies.

Hovhannes is a senior lecturer at the American Univeristy of Armenia and has been a visiting lecturer at San Francisco State University. He is a graduate of Bertelsmann University.