/usr/share/doc/samhain/manual.html/calling-external-programs.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Calling external programs</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="The Samhain Host Integrity Monitoring System"
HREF="index.html"><LINK
REL="UP"
TITLE="Hooks for External Programs"
HREF="extern.html"><LINK
REL="PREVIOUS"
TITLE="System V message queue"
HREF="system-v-message-queue.html"><LINK
REL="NEXT"
TITLE="Additional Features &#8212; Signed Configuration/Database Files"
HREF="signed-files.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="./docbook.css"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><!--#if expr="! ($HTTP_USER_AGENT = /MSIE/)"--><!--#include virtual="/resources/ssi/header.html"--><!--#endif --><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>The Samhain Host Integrity Monitoring System</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="system-v-message-queue.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 7. Hooks for External Programs</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="signed-files.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="CALLING-EXTERNAL-PROGRAMS"
>7.3. Calling external programs</A
></H1
><P
>  <SPAN
CLASS="APPLICATION"
>samhain</SPAN
> may invoke external programs 
  or scripts in order to implement
  logging capabilities that are not supported by 
  <SPAN
CLASS="APPLICATION"
>samhain</SPAN
> itself (e.g.
  pager support). This section provides an overview of this capability.</P
><P
>  External programs/scripts invoked for logging will receive the
  formatted log message on <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>stdin</I
></SPAN
>. 
  The program should expect
  that <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>stdout</I
></SPAN
> and <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>stderr</I
></SPAN
> are 
  closed, and that the
  working directory is the root directory.</P
><P
>	Each external program must be defined in the configuration file,
	in a section starting with the header <B
CLASS="COMMAND"
>[External]</B
>. 
	In addition, <B
CLASS="COMMAND"
>ExternalSeverity</B
> must be set to
	an appropriate threshold in the section <B
CLASS="COMMAND"
>[Log]</B
>.</P
><P
>	Each program definition starts with the line </P
><P
>	<B
CLASS="COMMAND"
>OpenCommand=<TT
CLASS="REPLACEABLE"
><I
>/full/path</I
></TT
></B
></P
><P
>	Options for the program may 
	follow. The definition of an external program 
	is ended (a) when explicitely terminated with the line 
	<B
CLASS="COMMAND"
>CloseCommand</B
>, (b) when the section
	ends, or (c) when another
	<B
CLASS="COMMAND"
>OpenCommand=<TT
CLASS="REPLACEABLE"
><I
>/full/path</I
></TT
></B
>
	line for
	the next command is encountered.</P
><DIV
CLASS="NOTE"
><P
></P
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="./stylesheet-images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
>Environment variables</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>   By default, the environment is limited to the TZ (timezone)
   variable. If you need other variables (e.g. LD_LIBRARY_PATH),
   you can set them using the 
   <B
CLASS="COMMAND"
>Setenviron=<TT
CLASS="REPLACEABLE"
><I
>KEY=value</I
></TT
></B
>
   option (see below).
 </P
></TD
></TR
></TABLE
></DIV
><P
><P
></P
><UL
><LI
><P
>	There are
	several places in <SPAN
CLASS="APPLICATION"
>samhain</SPAN
> where 
	external programs may be called.
	Each such place is identified by a <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>type</I
></SPAN
>. 
	Currently, valid types are:
        </P
><P
><P
></P
><UL
><LI
><P
>	  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>log</I
></SPAN
> &mdash; An external logging facility, 
	  which is handled like
	  other logging facilities. The program will receive the
	  logged message on stdin, followed by a newline, followed by
	  the string <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>[EOF]</I
></SPAN
> and another newline.
	  </P
></LI
><LI
><P
>	  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>srv</I
></SPAN
> &mdash; Executed by the server, 
	  whenever the status of a
	  client, as displayed in the HTML status table, has changed.
	  The program will receive the client hostname, the timestamp,
	  and the new status, followed by a newline, followed by
	  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>[EOF]</I
></SPAN
> and another newline. 
	  </P
></LI
></UL
></P
></LI
><LI
><P
>	Any number of external programs may be defined in the
	configuration file. Each external program has a 
	<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>type</I
></SPAN
>, which
	is <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>log</I
></SPAN
> by default. 
	Whenever external programs are called,
	all programs of the appropriate 
	<SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>type</I
></SPAN
> are executed.
	The <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>type</I
></SPAN
> can be set with 
	<B
CLASS="COMMAND"
>SetType=<TT
CLASS="REPLACEABLE"
><I
>type</I
></TT
></B
>
	</P
></LI
><LI
><P
>	External programs must be on a trusted path 
	(see <A
HREF="layout.html#DEFTRUST"
>Section 2.10.1</A
>&#62;), i.e. must not be 
	writeable by untrusted users.
	</P
></LI
><LI
><P
>	For enhanced security, the (192-bit TIGER) checksum of the
	external program/script may be specified in the configuration
	file:
	<B
CLASS="COMMAND"
>SetChecksum=<TT
CLASS="REPLACEABLE"
><I
>checksum</I
></TT
></B
> 
	(one string, no 
	blanks in checksum)
	</P
></LI
><LI
><P
>	Command line arguments and environment variables for
	each external program are configurable (the default is no
	command line arguments, and a clean environment containing only the TZ (timezone) variable:
	</P
><P
>	<B
CLASS="COMMAND"
>SetCommandline=<TT
CLASS="REPLACEABLE"
><I
>full_command_line</I
></TT
></B
> (full command line starting with
	the name of the program)
	</P
><P
>	<B
CLASS="COMMAND"
>Setenviron=<TT
CLASS="REPLACEABLE"
><I
>KEY=value</I
></TT
></B
>
	</P
></LI
><LI
><P
>	The user whose credentials shall be used, can be specified:
	<B
CLASS="COMMAND"
>SetCredentials=<TT
CLASS="REPLACEABLE"
><I
>username</I
></TT
></B
> 
	</P
></LI
><LI
><P
>	Some filters are available to make the execution of an
	external program dependent on the message content:
	</P
><P
>	<B
CLASS="COMMAND"
>SetFilterNot=<TT
CLASS="REPLACEABLE"
><I
>list</I
></TT
></B
> If any
	regular expression in 'list' matches
	the message, the program is not executed, else
	</P
><P
>	<B
CLASS="COMMAND"
>SetFilterAnd=<TT
CLASS="REPLACEABLE"
><I
>list</I
></TT
></B
> if any
	regular expression in 'list' is
	not matching the message, the program is not executed, else
	</P
><P
>	<B
CLASS="COMMAND"
>SetFilterOr=<TT
CLASS="REPLACEABLE"
><I
>list</I
></TT
></B
> if none
	of the regular expressions in 
	'list' matches the message, the program is not executed.
	</P
><P
>	For all filters, list items can be quoted with single or
	double quotes. It is also possible to use each filter option
	multiple times, although this does not affect the order (not, and, or)
	in which filters are evaluated. A maximum of 32 filter patterns for 
	each of (not, and. or) are supported per defined external program.
	Any filter not defined is not evaluated.
	</P
></LI
><LI
><P
>	It is possible to set a 'deadtime'. Within that 'deadtime', the
	respective external program will be executed only once 
	(if triggered):
	<B
CLASS="COMMAND"
>SetDeadtime=<TT
CLASS="REPLACEABLE"
><I
>seconds</I
></TT
></B
>
	</P
></LI
></UL
></P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="PAGING"
>7.3.1. Example setup for paging</A
></H2
><P
>	The distribution contains two example perl scripts for paging
	and SMS messages (example_pager.pl, example_sms.pl). The paging
	script will page via a web CGI script at www.pagemart.com 
	(obviously will work only for their pagers), the SMS 
	script is for any German 'free SMS' web site that 
	outsources free SMS to
	pitcom (with a suitable query on Google you can find such sites; you
	can then inspect the HTML form to set proper values for the
	required form variables.)</P
><P
>	If you know some Perl, both scripts can be adapted fairly easily to
	other providers. Below is an example setup for calling 
	example_pager.pl as an external logging facility.</P
><PRE
CLASS="PROGRAMLISTING"
>  [External]
  # start definition of first external program
  OpenCommand=/usr/local/bin/example_pager.pl 
    SetType=log 
    # arguments
    SetCommandline=example_pager.pl pager_id 
    # environment 
    SetEnviron=HOME=/home/moses 
    SetEnviron=PATH=/bin:/usr/bin:/usr/local/bin 
    # checksum 
    SetChecksum=FCBD3377B65F92F1701AFEEF3B5E8A80ED4936FD0D172C84 
    # credentials 
    SetCredentials=moses 
    # filter 
    SetFilterOr=POLICY 
    # deadtime 
    SetDeadtime=3600
  #Optional
  CloseCommand </PRE
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="system-v-message-queue.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="signed-files.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>System V message queue</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="extern.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Additional Features &mdash; Signed Configuration/Database Files</TD
></TR
></TABLE
></DIV
><!--#if expr="! ($HTTP_USER_AGENT = /MSIE/)"--><!--#include virtual="/resources/ssi/footer.html"--><!--#endif --></BODY
></HTML
>
samhain 3.1.0-7build1 / usr / share / doc / samhain / manual.html / calling-external-programs.html
