source: tags/4.1.0/man/samhain.8

Last change on this file was 488, checked in by katerina, 5 years ago

Fix for tickets #386 (silent check) and #387 (linux audit support).

File size: 21.7 KB
Line 
1.TH SAMHAIN 8 "26 June 2015" "" "Samhain manual"
2.SH NAME
3samhain \- check file integrity
4.SH SYNOPSIS
5.SS "INITIALIZING, UPDATING, AND CHECKING"
6.PP
7
8.B samhain
9{
10.I \-t init|\-\-set\-checksum\-test=init
11} [\-\-init2stdout] [\-r DEPTH|\-\-recursion=DEPTH] [log-options]
12
13.B samhain
14{
15.I \-t update|\-\-set\-checksum\-test=update
16} [\-D | \-\-daemon | \-\-foreground] [\-\-forever] [\-r DEPTH|\-\-recursion=DEPTH] [log-options]
17
18.B samhain
19{
20.I \-t check|\-\-set\-checksum\-test=check
21} [\-D | \-\-daemon | \-\-foreground] [\-\-forever] [\-r DEPTH,\-\-recursion=DEPTH] [log-options]
22
23.B samhain
24[ \-p threshold ] {
25.I \-\-verify\-database=database
26}
27
28.B samhain
29[ \-p threshold ] {
30.I \-\-create\-database=file\-list
31}
32
33
34
35.SS "LISTING THE DATABASE"
36.PP
37
38.B samhain
39[\-a | \-\-full\-detail]
40[\-\-delimited]
41[\-\-binary]
42[\-\-list\-filter=file]
43\-d
44.IR file |
45.RI \-\-list\-database= file
46
47.SS "VERIFYING AN AUDIT TRAIL"
48.PP
49
50.B samhain
51[\-j | \-\-just\-list]
52\-L
53.IR logfile |
54.RI \-\-verify\-log= logfile
55
56.B samhain
57\-M
58.IR mailbox |
59.RI \-\-verify\-mail= mailbox
60
61
62.SS "MISCELLANEOUS"
63.PP
64
65.B samhain
66.RI \-\-server\-port= portnumber
67
68.B samhain
69\-H
70.I string
71|
72.RI \-\-hash\-string= string
73
74.B samhain
75\-c | \-\-copyright
76
77.B samhain
78\-v | \-\-version
79
80.B samhain
81\-h | \-\-help
82
83.B samhain
84\-V key@/path/to/executable | \-\-add\-key=key@/path/to/executable
85
86.SS "SERVER STARTUP"
87.PP
88
89.B yule
90[\-q | \-\-qualified]
91[
92.RI \-\-chroot= chrootdir ]
93[\-D | \-\-daemon | \-\-foreground]
94[log-options]
95
96.SS "SERVER MISCELLANEOUS"
97.PP
98
99.B yule
100[\-P
101.I password
102|
103.RI \-\-password= password ]
104
105.B yule
106[\-G | \-\-gen-password]
107
108.SS "LOG OPTIONS"
109.PP
110
111[\-s
112.I threshold
113|
114.RI \-\-set\-syslog\-severity= threshold ]
115[\-l
116.I threshold
117|
118.RI \-\-set\-log\-severity= threshold ]
119[\-m
120.I threshold
121|
122.RI \-\-set\-mail\-severity= threshold ]
123[\-e
124.I threshold
125|
126.RI \-\-set\-export\-severity= threshold ]
127[\-p
128.I threshold
129|
130.RI \-\-set\-print\-severity= threshold ]
131[\-x
132.I threshold
133|
134.RI \-\-set\-external\-severity= threshold ]
135[
136.RI \-\-set\-prelude\-severity= threshold ]
137[
138.RI \-\-set\-database\-severity= threshold ]
139[
140.RI \-\-enable\-trace ]
141[
142.RI \-\-trace\-logfile= tracefile ]
143
144
145
146.SH WARNING
147.PP
148The information in this man page is not always up to date.
149The authoritative documentation is the user manual.
150
151.SH DESCRIPTION
152.PP
153.B samhain
154is a file integrity / intrusion detection system both for single hosts
155and networks.
156It consists of a monitoring application
157.RB ( samhain )
158running on
159individual hosts, and (optionally) a central log server
160.RB ( yule ).
161Currently, samhain can monitor the
162integrity of files/directories, and (optionally) also
163check for kernel rootkits
164(Linux and FreeBSD only), search the disk for SUID/SGID,
165and watch for login/logout events.
166.PP
167.B samhain/yule
168can log by email, to a tamper-resistant, signed log file,
169to syslog, to the Prelude IDS, to a MySQL/PostgreSQL/Oracle database,
170and/or to stdout
171.RI ( /dev/console
172if run as daemon).
173.B samhain/yule
174can run as a daemon, and can use a time server instead of the host's
175system clock. Most of the functionality is defined by a
176configuration file that is read at startup.
177.PP
178Most options of these usually would be set in the configuration file.
179Options given on the command line will override
180those in the configuration file.
181
182.SS "OPTIONS FOR INITIALIZING, UPDATING, AND CHECKING"
183.PP
184
185.B samhain
186.I "\-t init, \-\-set\-checksum-test=init"
187.RI [ options ]
188
189Initialize the database of file signatures. The path to the
190database is compiled in, and initializing will
191.B append
192to the respective file (or create it, if it does not exist).
193.B "It is ok to append to e.g. a JPEG image, but it is an error"
194.B "to append to an already existing file signature database."
195.PP
196.TP
197[\-\-init2stdout]
198Write the database to stdout.
199.TP
200[\-r DEPTH|\-\-recursion=DEPTH]
201Set the (global) recursion depth.
202
203.PP
204.B samhain
205.I "\-t update, \-\-set\-checksum-test=update"
206.RI [ options ]
207
208Update the database of file signatures. The path to the
209database is compiled in, and updating will
210.B overwrite
211the database, starting from the start of the database (which may not be
212identical to the start of the file \- see above).
213.PP
214.TP
215[\-r DEPTH|\-\-recursion=DEPTH]
216Set the (global) recursion depth.
217.TP
218[\-D|\-\-daemon]
219Run as daemon. File checks are performed as specified by the timing
220options in the configuration file. Updates are saved after each file check.
221.TP
222[\-\-foreground]
223Run in the foreground. This will cause samhain to exit after the update,
224unless the option
225.I "\-\-forever"
226is used.
227.TP
228[\-\-forever]
229If not running as daemon, do not exit after finishing the update, but
230loop forever, and perform checks with corresponding database updates
231according to the timing options in the
232configuration file.
233.TP
234[\-i|\-\-interactive]
235Run update in interactive mode.
236.TP
237[\-\-listfile=PATH]
238Run the update with a list of 'good' filepaths given in file (one path per line).
239
240
241.PP
242.B samhain
243.I "\-t check, \-\-set\-checksum-test=check"
244.RI [ options ]
245
246Check the filesystem against the database of file signatures.
247The path to the database is compiled in.
248.PP
249.TP
250[\-r DEPTH|\-\-recursion=DEPTH]
251Set the (global) recursion depth.
252.TP
253[\-D|\-\-daemon]
254Run as daemon. File checks are performed as specified by the timing
255options in the configuration file.
256.TP
257[\-\-foreground]
258Run in the foreground. This will cause samhain to exit after the file check,
259unless the option
260.I "\-\-forever"
261is used.
262.TP
263[\-\-forever]
264If not running as daemon, do not exit after finishing the check, but
265loop forever, and perform checks according to the timing options in the
266configuration file.
267
268.PP
269.B samhain
270[ \-p\ threshold ]
271.I "\-\-verify\-database=database"
272
273Check the filesystem against the database given as argument,
274and exit with an appropriate exit status. The configuration file
275will
276.B not
277be read.
278
279.PP
280.B samhain
281[ \-p\ threshold ]
282.I "\-\-create\-database=file\-list"
283
284Initialize a database from the given file list.
285The configuration file
286will
287.B not
288be read. The policy used will be
289.I ReadOnly.
290File content will be stored for a file
291if its path in the list is preceded with a
292.B +
293sign.
294
295.SS "OPTIONS FOR LISTING THE DATABASE"
296.PP
297
298.B samhain
299[\-a | \-\-full\-detail]
300[\-\-delimited]
301\-d
302.IR file |
303.RI \-\-list\-database= file
304
305List the entries in the file signature database in a
306.B ls \-l
307like format.
308.PP
309.TP
310[\-a | \-\-full\-detail]
311List all informations for each file, not only those you would get
312with ls \-l. Must precede the \-d option.
313.TP
314[\-\-delimited]
315List all informations for each file, in a comma-separated format.
316Must precede the \-d option.
317.TP
318[\-\-binary]
319List data in the binary format of the database, thus writing another
320database.
321Must precede the \-d option.
322.TP
323.RI [\-\-list\-filter= file ]
324Filter the output of the database listing by a list of files given
325in a text file. Together with \-\-binary this allows to write a
326partial database. Must precede the \-d option.
327.TP
328.RI [\-\-list\-file= file ]
329List the literal content of the given file as stored in the database.
330Content is not stored by default, must be enabled in the runtime
331configuration file. Must precede the \-d option.
332
333.SS "OPTIONS TO VERIFY AN AUDIT TRAIL"
334.PP
335
336These options will only work, if the executable used for verifying the
337audit trail is compiled with the same \-\-enable\-base=... option as the
338executable of the reporting process.
339
340.B samhain
341[\-j | \-\-just\-list]
342\-L
343.IR logfile |
344.RI \-\-verify\-log= logfile
345
346Verify the integrity of a signed logfile. The signing key is
347auto\-generated on startup, and sent by email.
348.B samhain
349will ask for the key. Instead of entering the key, you can also enter
350the path to the mailbox holding the respective email message.
351.PP
352.TP
353[\-j | \-\-just\-list]
354Just list the logfile, do not verify it. This option must come
355.BR first .
356It is mainly intended for listing the content of an obfuscated logfile, if
357.B samhain
358is compiled with the
359.B stealth
360option.
361
362.B samhain
363\-M
364.IR mailbox |
365.RI \-\-verify\-mail= mailbox
366
367Verify the integrity of the email reports from samhain. All reports must be
368in the same file.
369
370.SS "MISCELLANEOUS OPTIONS"
371.PP
372
373.B samhain
374.RI \-\-server\-port= portnumber
375
376Choose the port on the server host to which the client will connect.
377
378.B samhain
379\-H
380.I string
381|
382.RI \-\-hash\-string= string
383
384Compute the TIGER192 checksum of a string. If the string starts with
385a '/', it is considered as a pathname, and the checksum of the corresponding
386file will be computed.
387
388.B samhain
389\-c | \-\-copyright
390
391Print the copyright statement.
392
393.B samhain
394\-v | \-\-version
395
396Show version and compiled-in options.
397
398.B samhain
399\-h | \-\-help
400
401Print supported command line options (depending on compilation options).
402
403.B samhain
404\-V key@/path/to/executable | \-\-add\-key=key@/path/to/executable
405
406See the section "SECURITY" below.
407
408.SS "SERVER STARTUP OPTIONS"
409.PP
410
411.B yule
412[\-q | \-\-qualified]
413[
414.RI \-\-chroot= chrootdir ]
415[\-D | \-\-daemon | \-\-foreground]
416[log-options]
417
418Start the server, which is named
419.B yule
420by default. If the server is started with superuser privileges,
421it will drop them after startup.
422.PP
423.TP
424[\-q | \-\-qualified]
425Log client hostnames with fully qualified path. The default is to
426log only the leftmost domain label (i.e. the hostname).
427.TP
428[
429.RI \-\-chroot= chrootdir ]
430Chroot to the listed directory after startup.
431.TP
432[\-D | \-\-daemon]
433Run as daemon.
434.TP
435[\-\-foreground]
436Run in the foreground.
437
438
439.SS "MISCELLANEOUS SERVER OPTIONS"
440.PP
441
442.B yule
443[\-G | \-\-gen-password]
444
445Generate a random 8\-byte password and print it out in hexadecimal notation.
446
447
448.B yule
449[\-P
450.I password
451|
452.RI \-\-password= password ]
453
454Use the given
455.I password
456and generate an entry suitable for the [Clients] section of the
457configuration file.
458
459.SS "LOGGING OPTIONS"
460.PP
461
462Depending on the compilation options, some logging facilities may not
463be available in your executable.
464.PP
465.TP
466.I "\-s threshold, \-\-set\-syslog\-severity=threshold"
467Set the threshold for logging events via syslogd(8).
468Possible values are
469.IR debug ,
470.IR info ,
471.IR notice ,
472.IR warn ,
473.IR mark ,
474.IR err ,
475.IR crit ,
476.IR alert ,
477and
478.IR none .
479By default, everything equal to and above the threshold will be logged.
480Time stamps have the priority
481.IR warn ,
482system\-level errors have the priority
483.IR err ,
484and important start\-up messages the priority
485.IR alert .
486The signature key for the log file will never be logged to syslog or the
487log file itself.
488.TP
489.I "\-l threshold, \-\-set\-log\-severity=threshold"
490Set the threshold for logging events to the log file.
491.TP
492.I "\-m threshold, \-\-set\-mail\-severity=threshold"
493Set the threshold for logging events via e\-mail.
494.TP
495.I "\-e threshold, \-\-set\-export\-severity=threshold"
496Set the threshold for forwarding events via TCP to a log server.
497.TP
498.I "\-x threshold, \-\-set\-extern\-severity=threshold"
499Set the threshold for calling external logging programs/scripts (if any are
500defined in the configuration file).
501.TP
502.I "\-p threshold, \-\-set\-print\-severity=threshold"
503Set the threshold for logging events to stdout.
504If
505.B samhain
506runs as a daemon, this is redirected to /dev/console.
507.TP
508.I "\-\-set\-prelude\-severity=threshold"
509Set the threshold for logging events to the Prelude IDS.
510.TP
511.I "\-\-set\-database\-severity=threshold"
512Set the threshold for logging events to the MySQL/PostgreSQL/Oracle
513database.
514
515
516
517.SH SIGNALS
518.TP
519.I SIGUSR1
520Switch on/off maximum verbosity for console output.
521.TP
522.I SIGUSR2
523Suspend/continue the process, and
524(on suspend) send a message
525to the server. This message has the same priority as timestamps.
526This signal
527allows to run
528.I samhain -t init -e none
529on the client
530to regenerate the database, with download of the configuration file
531from the server, while the daemon is suspended (normally you would get
532errors because of concurrent access to the server by two processes from
533the
534.IR "same host" ")."
535.TP
536.I SIGHUP
537Reread the configuration file.
538.TP
539.I SIGTERM
540Terminate.
541.TP
542.I SIGQUIT
543Terminate after processing all pending requests from clients.
544.TP
545.I SIGABRT
546Unlock the log file, pause for three seconds, then proceed,
547eventually re-locking the log file and starting a fresh audit trail
548on next access.
549.TP
550.I SIGTTOU
551Force a file check (only client/standalone, and only in daemon mode).
552
553
554.SH DATABASE
555The database (default name
556.IR samhain_file )
557is a binary file, which can be created or updated using the
558.B \-t
559.I init
560or the
561.B \-t
562.I update
563option.
564If you use
565.B \-t
566.IR init ,
567you need to
568.I remove
569the old database first,
570otherwise the new version will be
571.I appended
572to the old one.
573The file may be (clear text) signed by PGP/GnuPG.
574.br
575It is recommended to use GnuPG with the options
576.B gpg
577.I -a --clearsign --not-dash-escaped
578.br
579.B samhain
580will check the signature, if compiled with support for that.
581.PP
582At startup
583.B samhain
584will compute the checksum of the database, and verify it for
585each further access. This checksum is not stored on disk (i.e. is lost
586after program termination), as there is no secure way to store it.
587
588.SH LOG FILE
589.PP
590Each entry in the log file has the format
591.BR "Severity : [Timestamp] Message" ,
592where the timestamp may be obtained from a time server rather than from
593the system clock, if
594.B samhain
595has been compiled with support for this.
596Each entry is followed by a
597.IR signature ,
598which is computed as
599.BR "Hash(Entry Key_N)" ,
600and
601.B  Key_N
602is computed as
603.BR "Hash(Key_N\-1)" ,
604i.e. only knowledge of the first signature key in this chain allows to
605verify the integrity of the log file. This first key is autogenerated
606and e\-mailed to the designated recipient.
607.PP
608The default name of the log file is
609.IR samhain_log .
610To prevent multiple instances of
611.B samhain
612from writing to the same log file, the log file is locked by creating a
613.IR "lock file" ,
614which is normally deleted at program termination.
615The default name of the
616.I "lock file"
617is
618.IR samhain.lock .
619If
620.B samhain
621is terminated abnormally, i.e. with kill \-9,
622a stale lock file might remain, but usually
623.B samhain
624will be able to recognize that and remove the stale lock file
625on the next startup.
626.PP
627.SH EMAIL
628.PP
629E\-mails are sent (using built-in SMTP code)
630to one recipient only.
631The subject line contains timestamp
632and hostname, which are repeated in the message body.
633The body of the mail contains a line with a
634.I signature
635similar to that in the log file, computed from the message and a
636key. The key is iterated by a hash chain, and the initial
637key is revealed in the first email sent.
638Obviously, you have to believe that this first e\-mail is
639authentical ...
640.PP
641.SH CLIENT/SERVER USAGE
642.PP
643To monitor several machines, and collecting data by a central log server,
644.B samhain
645may be compiled as a client/server application. The log server
646.RB ( yule )
647will accept connection
648requests from registered clients only. With each client, the server will first
649engage in a challenge/response protocol for
650.I authentication
651of the client and
652.I establishing
653a
654.IR "session key" .
655.PP
656This protocol requires on the client side a
657.IR "password" ,
658and on the server side a
659.IR "verifier"
660that is computed from the
661.IR "password" .
662.PP
663To
664.I register
665a client, simply do the following:
666.br
667First, with the included utility program
668.B samhain_setpwd
669re\-set the compiled\-in default password of the
670client executable to your preferred
671value (with no option, a short usage help is printed).
672To allow for non-printable chars, the new value
673must be given as a 16\-digit hexadecimal string
674(only 0123456789ABCDEF in string), corresponding to an 8-byte password.
675.br
676Second, after re\-setting the password in the client executable,
677you can use the server's convenience function
678.B yule
679.B \-P
680.I password
681that will take as input the (16\-digit hex) password,
682compute the corresponding verifier, and outputs a default configuration file
683entry to register the client.
684.br
685Third, in the configuration file for the server, under the [Clients] section,
686enter
687the suggested registration entry of the form
688.IR "Client=hostname@salt@verifier" ,
689where
690.I hostname
691must be the (fully qualified) hostname of the machine on
692which the client will run.
693.B "Don't forget to reload the server configuration thereafter."
694.PP
695If a connection attempt is made, the server will lookup the entry for
696the connecting host, and use the corresponding value for the
697.I verifier
698to engage in the session key exchange. Failure to verify the client's
699response(s) will result in aborting the connection.
700.PP
701.SH STEALTH
702.PP
703.B samhain
704may be compiled with support for a
705.I stealth
706mode of operation, meaning that
707the program can be run without any obvious trace of its presence
708on disk. The supplied facilities are simple - they are more
709sophisticated than just running the program under a different name,
710and might thwart efforts using 'standard' Unix commands,
711but they will not resist a search using dedicated utilities.
712.PP
713In this mode, the runtime executable will hold no
714printable strings, and the configuration file is expected to be
715a postscript file with
716.I uncompressed
717image data, wherein
718the configuration data are hidden by steganography.
719To create such a file from an existing image, you may use e.g.
720the program
721.BR convert (1),
722which is part of the
723.BR ImageMagick (1)
724package, such as:
725.B "convert +compress"
726.IR "ima.jpg ima.ps" .
727.PP
728To hide/extract the configuration data within/from the postscript file,
729a utility program
730.B samhain_stealth
731is provided.
732Use it without options to get help.
733.PP
734Database and log file may be e.g. existing image files, to which
735data are appended, xor'ed with some constant to mask them as binary data.
736.PP
737The user is responsible by herself for re-naming the compiled
738executable(s) to unsuspicious names, and choosing (at compile time)
739likewise unsuspicious names for config file, database, and log (+lock) file.
740.PP
741.SH SECURITY
742.PP
743For security reasons,
744.B samhain
745will not write log or data files in a directory, remove the lock file,
746or read the configuration file, if any element
747in the path is owned or writeable by an untrusted user (including
748group-writeable files with untrusted users in the group, and world-writeable
749files).
750.br
751.I root
752and the
753.I effective
754user are always trusted. You can add more users in the configuration file.
755.PP
756Using a
757.I "numerical host address"
758in the e\-mail address is more secure than
759using the hostname (does not require
760DNS lookup).
761.PP
762If you use a
763.I precompiled
764.B samhain
765executable (e.g. from a
766binary distribution), in principle a prospective intruder could easily
767obtain a copy of the executable and analyze it in advance. This will
768enable her/him to generate fake audit trails and/or generate
769a trojan for this particular binary distribution.
770.br
771For this reason, it is possible for the user to add more key material into
772the binary executable. This is done with the command:
773.PP
774.BI "samhain " \-\-add\-key=key@/path/to/executable
775.PP
776This will read the file
777.I /path/to/executable, add the key
778.I key,
779which should not contain a '@' (because it has a special meaning, separating
780key from path), overwrite any key previously set by this command, and
781write the new binary to the location
782.I /path/to/executable.out
783(i.e. with .out appended). You should then copy the new binary to the location
784of the old one (i.e. overwrite the old one).
785.PP
786.B Note that using a precompiled samhain executable from a binary
787.B package distribution is not recommended unless you add in key material as
788.B described here.
789
790.PP
791.SH NOTES
792.PP
793For initializing the key(s),
794.I "/dev/random"
795is used, if available. This is a 
796device supplying cryptographically strong
797(non-deterministic) random noise. Because it is slow,
798.B samhain
799might appear to hang at startup. Doing some random things
800(performing rain dances, spilling coffee, hunting the mouse) might speed up
801things. If you do not have
802.IR "/dev/random" ,
803lots of statistics from
804.BR vmstat (8)
805and the like will be pooled and mixed by a hash function.
806.PP
807Some hosts might check whether the sender of the mail is valid.
808Use only
809.I "login names"
810for the sender.
811.br
812For sending mails, you may need to set a relay host for the sender domain
813in the configuration file.
814.PP
815.SH BUGS
816.PP
817Whoever has the original signature key may change the log file and send fake
818e\-mails. The signature keys are e\-mailed at program startup
819with a one\-time pad encryption.
820This should be safe against an eavesdropper on the network,
821but not against someone with read access to the binary,
822.I if
823she has caught
824the e\-mail.
825.PP
826.SH FILES
827.PP
828.I /etc/samhainrc
829.br         
830.I /usr/local/man/man8/samhain.8
831.br         
832.I /usr/local/man/man5/samhainrc.5
833.br         
834.I /var/log/samhain_log
835.br         
836.I /var/lib/samhain/samhain_file
837.br         
838.I /var/lib/samhain/samhain.html
839.br         
840.I /var/run/samhain.pid
841
842.SH SEE ALSO
843.PP
844.BR samhainrc (5)
845
846.SH AUTHOR
847.PP
848Rainer Wichmann (http://la\-samhna.de)
849.SH BUG REPORTS
850.PP
851If you find a bug in
852.BR samhain ,
853please send electronic mail to
854.IR support@la\-samhna.de .
855Please include your operating system and its revision, the version of
856.BR samhain ,
857what C compiler you used to compile it, your 'configure' options, and
858any information that you deem helpful.
859.PP
860.SH COPYING PERMISSIONS
861.PP
862Copyright (\(co) 1999, 2004 Rainer Wichmann
863.PP
864Permission is granted to make and distribute verbatim copies of
865this manual page provided the copyright notice and this permission
866notice are preserved on all copies.
867.ig
868Permission is granted to process this file through troff and print the
869results, provided the printed document carries copying permission
870notice identical to this one except for the removal of this paragraph
871(this paragraph not being relevant to the printed manual page).
872..
873.PP
874Permission is granted to copy and distribute modified versions of this
875manual page under the conditions for verbatim copying, provided that
876the entire resulting derived work is distributed under the terms of a
877permission notice identical to this one.
878
879
880
Note: See TracBrowser for help on using the repository browser.