source: trunk/man/samhain.8 @ 169

Last change on this file since 169 was 169, checked in by katerina, 14 years ago

Fixes for tickes #93 to #104 (yes, big commit, bad, bad,...).

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