source: branches/samhain-2_2-branch/man/samhain.8@ 410

Last change on this file since 410 was 27, checked in by rainer, 19 years ago

Support for server-to-server relay and more user policies

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