source: trunk/man/samhain.8@ 85

Last change on this file since 85 was 76, checked in by rainer, 18 years ago

Fix for ticket #38 (csv escaping) and #39 (building on cygwin). Also optimize a bit.

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