source: trunk/man/samhain.8 @ 481

Last change on this file since 481 was 481, checked in by katerina, 6 years ago

Enhancements and fixes for tickets #374, #375, #376, #377, #378, and #379.

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