[1] | 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 |
|
---|