1 2CONTENT 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 35INSTALL: 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 87PGP 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 118CLIENT/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 169STEALTH: 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 225USAGE 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 242CAVEATS: 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 280START 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 289CONFIGURE 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 469TESTING: 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 486