1 |
|
---|
2 | CONTENT OF THIS DOCUMENT
|
---|
3 | ------------------------
|
---|
4 |
|
---|
5 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
---|
6 | +++ +++
|
---|
7 | +++ NOTE: The distribution package contains a much more detailed MANUAL +++
|
---|
8 | +++ +++
|
---|
9 | +++ ---- See the docs/ subdirectory ---- +++
|
---|
10 | +++ +++
|
---|
11 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
---|
12 |
|
---|
13 | - INSTALL basic install procedure
|
---|
14 |
|
---|
15 | - PGP SIGNATURES signing database and config file
|
---|
16 |
|
---|
17 | - CLIENT/SERVER how to install and use with client/server mode
|
---|
18 | for distributed host monitoring
|
---|
19 |
|
---|
20 | - STEALTH how to install and use with stealth mode enabled
|
---|
21 |
|
---|
22 | - USAGE some usage examples
|
---|
23 |
|
---|
24 | - CAVEATS what the name says
|
---|
25 |
|
---|
26 | - START AT BOOT TIME how to start the daemon during the boot sequence
|
---|
27 |
|
---|
28 | - CONFIGURE OPTIONS overview of supported options, and defaults
|
---|
29 |
|
---|
30 | - TESTING test suite (also useful to see EXAMPLES)
|
---|
31 |
|
---|
32 |
|
---|
33 |
|
---|
34 |
|
---|
35 | INSTALL:
|
---|
36 | -------
|
---|
37 |
|
---|
38 | Unpack the source with:
|
---|
39 |
|
---|
40 | gunzip -c samhain-current.tar.gz | tar xvf -
|
---|
41 |
|
---|
42 | This will drop two files in your current directory:
|
---|
43 |
|
---|
44 | samhain-{version}.tar.gz
|
---|
45 | samhain-{version}.tar.gz.asc
|
---|
46 |
|
---|
47 | To check authenticity and integrity of the source code, verify
|
---|
48 | the PGP signature on samhain-{version}.tar.gz
|
---|
49 | (public PGP key for Rainer Wichmann at http://wwwkeys.pgp.net/):
|
---|
50 |
|
---|
51 | gpg --verify samhain-{version}.tar.gz.asc samhain-{version}.tar.gz
|
---|
52 |
|
---|
53 | Then unpack samhain-{version}.tar.gz:
|
---|
54 |
|
---|
55 | gunzip -c samhain-{version}.tar.gz | tar xvf -
|
---|
56 | cd samhain-{version}
|
---|
57 |
|
---|
58 | If you have an incarnation of 'dialog' (xdialog, dialog, lxdialog)
|
---|
59 | installed, you can use the GUI install tool:
|
---|
60 |
|
---|
61 | ./Install.sh
|
---|
62 |
|
---|
63 | Otherwise use the commands:
|
---|
64 |
|
---|
65 | ./configure [options]
|
---|
66 | make
|
---|
67 | su root
|
---|
68 | make install
|
---|
69 |
|
---|
70 | At least the following executable will be built:
|
---|
71 |
|
---|
72 | +++ samhain +++ the monitoring agent, without any
|
---|
73 | client/server support (i.e. local use only)
|
---|
74 |
|
---|
75 | Additional executables will be built if you compile in client/server
|
---|
76 | and/or stealth mode (see below).
|
---|
77 |
|
---|
78 | The 'make install' target will strip the executable(s), i.e.
|
---|
79 | discard symbols.
|
---|
80 |
|
---|
81 | PATHS:
|
---|
82 | -----
|
---|
83 | For configuring the install paths/locations,
|
---|
84 | see the MANUAL.
|
---|
85 |
|
---|
86 |
|
---|
87 | PGP SIGNATURES:
|
---|
88 | --------------
|
---|
89 | By default, samhain will report on the checksums of the database
|
---|
90 | and configuration files on startup.
|
---|
91 |
|
---|
92 | You can always (clear)sign the database (once initialized)
|
---|
93 | with GnuPG, as well as the configuration file
|
---|
94 | (recommended: gpg -a --clearsign --not-dash-escaped FILE).
|
---|
95 |
|
---|
96 | However, to have samhain check these signatures, rather than ignoring
|
---|
97 | them, you need GnuPG and you must compile samhain with the option
|
---|
98 |
|
---|
99 | ./configure --with-gpg=PATH
|
---|
100 |
|
---|
101 | where PATH is the path to the gpg/pgp binary.
|
---|
102 |
|
---|
103 | Samhain will invoke gpg only after checking that
|
---|
104 | only trusted users (by default: root and the effective user)
|
---|
105 | have write access to any element in the path.
|
---|
106 |
|
---|
107 | The public key for verification must be in the keyring of the
|
---|
108 | effective user (usually root)
|
---|
109 |
|
---|
110 | For more security, it is possible to compile in the checksum
|
---|
111 | of the GnuPG executable, and/or the key fingerprint. See
|
---|
112 | the MANUAL for more details.
|
---|
113 |
|
---|
114 | The public key will be searched in the gpg home directory
|
---|
115 | (~/.gnupg/) of the effective user (usually root).
|
---|
116 | The key identification and fingerprint will be reported.
|
---|
117 |
|
---|
118 | CLIENT/SERVER:
|
---|
119 | -------------
|
---|
120 |
|
---|
121 | samhain supports logging to a central server via TCP/IP.
|
---|
122 | To enable this option, use the ./configure option
|
---|
123 |
|
---|
124 | ./configure --enable-network=client|server [more options]
|
---|
125 |
|
---|
126 | NOTE: client and server are __distict__ applications, and must be
|
---|
127 | built seperately. By default, installation names and paths are
|
---|
128 | different. Do not blame us if you abuse './configure' options to
|
---|
129 | cause name clashes, if you install both on the same host.
|
---|
130 |
|
---|
131 | The following executables are built:
|
---|
132 |
|
---|
133 | +++ samhain (client) +++ the monitoring agent,
|
---|
134 | with client code included
|
---|
135 | if --enable-network=client
|
---|
136 |
|
---|
137 | +++ yule (server) +++ the log server (no monitoring, just report
|
---|
138 | collecting !!!)
|
---|
139 | if --enable-network=server
|
---|
140 |
|
---|
141 | +++ samhain_setpwd +++ a utility program to set the password of
|
---|
142 | a monitoring agent (see man page samhain.8).
|
---|
143 | Use it without options to get help.
|
---|
144 |
|
---|
145 |
|
---|
146 | To set up a monitoring agent, do the following:
|
---|
147 |
|
---|
148 | -- select a (16-digit hexadecimal) password. To generate
|
---|
149 | a random password, you can use:
|
---|
150 |
|
---|
151 | ./yule -G
|
---|
152 |
|
---|
153 | -- use 'samhain_setpwd samhain <suffix> <password>'
|
---|
154 | to generate an agent 'samhain.suffix' with the selected password
|
---|
155 | (you can rename the agent afterwards, of course)
|
---|
156 |
|
---|
157 | -- use 'yule -P password' to compute an entry to register the agent
|
---|
158 |
|
---|
159 | -- in the servers's configuration file, insert the computed entry
|
---|
160 | (replace HOSTNAME with the host, on which the agent will run)
|
---|
161 | in the section called [Clients]
|
---|
162 |
|
---|
163 | By default, client/server authentication
|
---|
164 | is done with the SRP (Secure Remote Password) protocol.
|
---|
165 |
|
---|
166 | It is also possible to store configuration and database files
|
---|
167 | on the server. See the manual for details.
|
---|
168 |
|
---|
169 | STEALTH:
|
---|
170 | -------
|
---|
171 |
|
---|
172 | samhain supports a 'stealth' mode of operation, meaning that
|
---|
173 | the program can be run without any obvious trace of its presence
|
---|
174 | on disk. The supplied facilities are more sophisticated than
|
---|
175 | just running the program under a different name,
|
---|
176 | and might thwart efforts using 'standard' Unix commands,
|
---|
177 | but they will not resist a search using dedicated utilities.
|
---|
178 | To enable this mode, use the ./configure option
|
---|
179 |
|
---|
180 | ./configure --enable-stealth=XOR_VAL [more options]
|
---|
181 |
|
---|
182 | XOR_VAL must be a decimal number in the range 0, 128..255
|
---|
183 | (using 0 will have no effect).
|
---|
184 |
|
---|
185 | The runtime executable will contain no printable strings revealing
|
---|
186 | its nature or purpose (strings are xor'ed with XOR_VAL at compile
|
---|
187 | time, and decoded at runtime).
|
---|
188 |
|
---|
189 | The configuration file is expected to be
|
---|
190 | a postscript file with _uncompressed_ image data, wherein
|
---|
191 | the configuration data are hidden by steganography.
|
---|
192 | To create a suitable image file from an existing image,
|
---|
193 | you may use e.g. the ImageMagick program 'convert', such as:
|
---|
194 |
|
---|
195 | convert +compress ima.jpg ima.ps
|
---|
196 |
|
---|
197 | The following additional executable will be built:
|
---|
198 |
|
---|
199 | +++ samhain_stealth +++ steganography utility program to hide/extract
|
---|
200 | the configuration file data in/from a
|
---|
201 | postscript file with
|
---|
202 | _uncompressed_ image data.
|
---|
203 | Use it without options to get help.
|
---|
204 |
|
---|
205 | Database and log file entries are xor'ed with XOR_VAL to 'mask'
|
---|
206 | printable strings as binary data. No steganography is supported
|
---|
207 | for them, as this would require image files of unreasonable large
|
---|
208 | size.
|
---|
209 | However, if the database/log file is an existing image (say, a .jpg
|
---|
210 | file), the data will be appended to the end of the image data.
|
---|
211 | The image will display normally, and on examination of the file,
|
---|
212 | the add-on data will look like binary (image) data at first sight.
|
---|
213 | The built-in utility to verify and print log file entries
|
---|
214 | will handle this situation transparently.
|
---|
215 |
|
---|
216 | To re-name samhain to something unsuspicious, use the configure option
|
---|
217 |
|
---|
218 | ./configure --enable-install-name=NAME
|
---|
219 |
|
---|
220 | 'make install' will then re-name samhain upon installation. Also,
|
---|
221 | database, log file, and pid file will have 'samhain' replaced by
|
---|
222 | NAME.
|
---|
223 |
|
---|
224 |
|
---|
225 | USAGE EXAMPLES:
|
---|
226 | --------------
|
---|
227 |
|
---|
228 | Review the default configuration file that comes with the
|
---|
229 | source distribution. Read the man page (samhain.8).
|
---|
230 |
|
---|
231 | initialize database: samhain -t init
|
---|
232 |
|
---|
233 | check files: samhain -t check
|
---|
234 |
|
---|
235 | run as daemon: samhain -t check -D
|
---|
236 |
|
---|
237 | report to log server: samhain -t check -D -e warn
|
---|
238 |
|
---|
239 | start the log server: yule -S
|
---|
240 |
|
---|
241 |
|
---|
242 | CAVEATS:
|
---|
243 | -------
|
---|
244 | Permissions:
|
---|
245 | -----------
|
---|
246 | samhain needs root permissions to check some system files.
|
---|
247 | The log server does not require root permissions, unless
|
---|
248 | you use a privileged port (port number below 1024).
|
---|
249 | If you use --enable-udp to listen on the syslog socket, you need
|
---|
250 | to start the log server with root permissions (it will drop them
|
---|
251 | after binding to the port).
|
---|
252 |
|
---|
253 | Trust:
|
---|
254 | -----
|
---|
255 | samhain checks the path to critical files (database, configuration)
|
---|
256 | for write access by untrusted users. By default, only root and
|
---|
257 | the effective user are trusted. More UIDs can be added as a
|
---|
258 | compile options (some systems habe 'bin' as owner of the root
|
---|
259 | directory).
|
---|
260 |
|
---|
261 | Integrity:
|
---|
262 | ---------
|
---|
263 | On startup, samhain will report on signatures or checksums of
|
---|
264 | database and configuration files. You better check these reports.
|
---|
265 |
|
---|
266 | Both startup and exit will be reported. If you are using samhain
|
---|
267 | as daemon and start it at boot time, you may want to check that
|
---|
268 | startup/exit corresponds with scheduled reboots.
|
---|
269 |
|
---|
270 | If the path to the samhain binary is defined in the configuration
|
---|
271 | file, samhain will checksum the binary at startup and compare
|
---|
272 | at program termination. This will minimize the time available
|
---|
273 | for an intruder to modify the binary.
|
---|
274 |
|
---|
275 | Mail address:
|
---|
276 | ------------
|
---|
277 | For offsite mail, you may have to set a mail relay host
|
---|
278 | in the configuration file.
|
---|
279 |
|
---|
280 | START AT BOOT TIME:
|
---|
281 | ------------------
|
---|
282 | the easy way (supported on Linux, FreeBSD, HP-UX, AIX):
|
---|
283 |
|
---|
284 | su root
|
---|
285 | make install-boot
|
---|
286 |
|
---|
287 |
|
---|
288 |
|
---|
289 | CONFIGURE OPTIONS:
|
---|
290 | -----------------
|
---|
291 |
|
---|
292 | -------------------
|
---|
293 | -- basic options --
|
---|
294 | -------------------
|
---|
295 |
|
---|
296 | --enable-network Compile with client/server support.
|
---|
297 |
|
---|
298 | --enable-udp Enable the server to listen on
|
---|
299 | port 514/udp (syslog).
|
---|
300 |
|
---|
301 | --enable-srp Use SRP protocol to authenticate to
|
---|
302 | log server.
|
---|
303 |
|
---|
304 | --with-gpg=PATH Use GnuPG to verify database/config.
|
---|
305 | The public key of the effective
|
---|
306 | user (in ~/.gnupg/pubring.gpg)
|
---|
307 | will be used.
|
---|
308 |
|
---|
309 | --enable-login-watch Watch for login/logout events.
|
---|
310 |
|
---|
311 | --enable-stealth=XOR_VAL Enable stealth mode, and set XOR_VAL.
|
---|
312 | XOR_VAL must be decimal in
|
---|
313 | 0..32 or 127..255
|
---|
314 | and will be used to 'mask' literal
|
---|
315 | strings as binary data.
|
---|
316 | (0 has no effect).
|
---|
317 |
|
---|
318 | --enable-micro-stealth=XOR_VAL
|
---|
319 | As --with-stealth, but without
|
---|
320 | steganographic hidden configuration
|
---|
321 | file.
|
---|
322 |
|
---|
323 | --enable-nocl=PW Enable command line parsing ONLY if
|
---|
324 | PW is the first argument on the command
|
---|
325 | line. If PW is "" (empty string),
|
---|
326 | command line parsing is completely
|
---|
327 | disabled.
|
---|
328 |
|
---|
329 | --enable-base=BASE Set base for one-time pads. Must be
|
---|
330 | ONE string (no space) made of TWO
|
---|
331 | comma-separated integers in the range
|
---|
332 | -2147483648...2147483647.
|
---|
333 | (The default is compile time.)
|
---|
334 | Binaries compiled with different
|
---|
335 | values cannot verify the audit trail(s)
|
---|
336 | of each other.
|
---|
337 | THIS IS IMPORTANT IF YOU COMPILE
|
---|
338 | MULTIPLE TIMES, E.G. ON DIFFERENT
|
---|
339 | HOSTS.
|
---|
340 |
|
---|
341 |
|
---|
342 | -------------------
|
---|
343 | -- paths --
|
---|
344 | -------------------
|
---|
345 |
|
---|
346 | ${install_name} is "samhain" by default
|
---|
347 | (see --with-install-name=NAME )
|
---|
348 |
|
---|
349 | configuration: /etc/${install_name}rc
|
---|
350 | state data: /var/lib/${install_name}
|
---|
351 | log file: /var/log/${install_name}_log
|
---|
352 | lock/pid file: /var/run/${install_name}.pid
|
---|
353 |
|
---|
354 | mandir: /usr/local/man
|
---|
355 | bindir: /usr/local/sbin/
|
---|
356 |
|
---|
357 |
|
---|
358 | --exec-prefix=EPREFIX Set sbindir prefix (default
|
---|
359 | is /usr/local, ie. binaries
|
---|
360 | go to /usr/local/sbin)
|
---|
361 |
|
---|
362 | --prefix=PREFIX install directory
|
---|
363 | (default is NONE)
|
---|
364 |
|
---|
365 | IF PREFIX = USR; then
|
---|
366 |
|
---|
367 | configuration: /etc/${install_name}rc
|
---|
368 | state data: /var/lib/${install_name}
|
---|
369 | log file: /var/log/${install_name}_log
|
---|
370 | lock/pid file: /var/run/${install_name}.pid
|
---|
371 |
|
---|
372 | mandir: /usr/share/man
|
---|
373 | bindir: /usr/sbin/
|
---|
374 |
|
---|
375 | IF PREFIX = OPT; then
|
---|
376 |
|
---|
377 | configuration: /etc/opt/${install_name}rc
|
---|
378 | state data: /var/opt/${install_name}/${install_name}
|
---|
379 | log file: /var/opt/${install_name}/${install_name}_log
|
---|
380 | lock/pid file: /var/opt/${install_name}/${install_name}.pid
|
---|
381 |
|
---|
382 | mandir: /opt/${install_name}/man
|
---|
383 | bindir: /opt/${install_name}/bin/
|
---|
384 |
|
---|
385 | IF PREFIX = (something else); then
|
---|
386 |
|
---|
387 | If EPREFIX is not set, it will be set to PREFIX.
|
---|
388 | configuration: PREFIX/etc/${install_name}rc
|
---|
389 | state data: PREFIX/var/lib/${install_name}
|
---|
390 | log file: PREFIX/var/log/${install_name}_log
|
---|
391 | lock/pid file: PREFIX/var/run/${install_name}.pid
|
---|
392 |
|
---|
393 | mandir: PREFIX/share/man
|
---|
394 | bindir: PREFIX/sbin/
|
---|
395 |
|
---|
396 |
|
---|
397 |
|
---|
398 | --with-config-file=FILE Set path of configuration file
|
---|
399 | (default is PREFIX/etc/samhainrc)
|
---|
400 |
|
---|
401 | --with-data-file=FILE Set path of data file
|
---|
402 | (PREFIX/var/lib/samhain/samhain_file)
|
---|
403 | --with-html-file=FILE Set path of server status html file
|
---|
404 | (PREFIX/var/lib/samhain/samhain.html)
|
---|
405 |
|
---|
406 | --with-log-file=FILE Set path of log file
|
---|
407 | (PREFIX/var/log/samhain_log)
|
---|
408 | --with-pid-file=FILE Set path of lock file
|
---|
409 | (PREFIX/var/run/samhain.pid)
|
---|
410 |
|
---|
411 | -------------------
|
---|
412 | -- other --
|
---|
413 | -------------------
|
---|
414 |
|
---|
415 |
|
---|
416 | --with-checksum=CHECKSUM Compile in TIGER checksum of the
|
---|
417 | gpg/pgp binary.
|
---|
418 | CHECKSUM must be the full
|
---|
419 | line output by samhain or GnuPG when
|
---|
420 | computing the checksum.
|
---|
421 |
|
---|
422 | --with-fp=FINGERPRINT Compile in public key fingerprint.
|
---|
423 | FINGERPRINT must be without spaces.
|
---|
424 | Only useful in combination with
|
---|
425 | '--with-gpg'.
|
---|
426 | If used, samhain will check the
|
---|
427 | fingerprint, but still report on the
|
---|
428 | used public key.
|
---|
429 |
|
---|
430 | --enable-identity=USER Set user when dropping root privileges
|
---|
431 | (default is the user "nobody").
|
---|
432 | Only needed if there is no user
|
---|
433 | 'nobody' on your system
|
---|
434 | (check /etc/passwd)
|
---|
435 |
|
---|
436 | --with-port=PORT Set port number for TCP/IP
|
---|
437 | (default is 49777).
|
---|
438 | Only needed if this port is already
|
---|
439 | used by some other application.
|
---|
440 |
|
---|
441 | --with-logserver=HOST Set host address for log server
|
---|
442 | (default is NULL).
|
---|
443 | You can set this in the configuration
|
---|
444 | file as well.
|
---|
445 |
|
---|
446 | --with-timeserver=HOST Set host address for time server
|
---|
447 | (default is NULL - use own clock).
|
---|
448 | You can set this in the configuration
|
---|
449 | file as well.
|
---|
450 |
|
---|
451 | --with-sender=SENDER Set sender for e-mail
|
---|
452 | (default is daemon).
|
---|
453 |
|
---|
454 | --enable-xml-log Use XML format for log file.
|
---|
455 |
|
---|
456 | --enable-debug Enable extended debugging
|
---|
457 |
|
---|
458 | --enable-ptrace Use anti-debugging code.
|
---|
459 |
|
---|
460 | --with-trusted=UID Comma-separated list of UID's of
|
---|
461 | users that are always trusted
|
---|
462 | (default is 0 = root).
|
---|
463 | You will need this only if the
|
---|
464 | path to the config file has directories
|
---|
465 | owned neither by 'root' nor by the
|
---|
466 | (effective) user of the program.
|
---|
467 |
|
---|
468 |
|
---|
469 | TESTING:
|
---|
470 | -------
|
---|
471 | For testing compilation etc., you may use the test suite:
|
---|
472 |
|
---|
473 | ./test/test.sh n [hostname]
|
---|
474 |
|
---|
475 | The argument 'n' is the number of the test to run. Some tests require
|
---|
476 | that the (fully qualified) hostname be given as second argument.
|
---|
477 |
|
---|
478 | Without options, you will get a short help/usage message, listing
|
---|
479 | each test, its purpose, and the name of the configuration file used.
|
---|
480 | You may want to review the respective configuration file before
|
---|
481 | running a test.
|
---|
482 |
|
---|
483 | Also listed are the scripts used for each test. If you have problems
|
---|
484 | getting samhain to run, you may use these scripts as examples.
|
---|
485 |
|
---|