Annotation of wikisrc/guide/veriexec.mdwn, revision 1.1
1.1 ! jdf 1: # NetBSD Veriexec subsystem
! 3: [veriexec(8)](http://netbsd.gw.com/cgi-bin/man-cgi?veriexec+8+NetBSD-current)
! 4: is a file integrity subsystem in NetBSD (introduced in 3.0). It is kernel
! 5: based, hence can provide some protection even in the case of a root compromise.
! 7: ## How it works
! 9: First of all (usually at boot time), Veriexec loads a specification file, also
! 10: called the *signatures file*, to the kernel. This file contains information
! 11: about files Veriexec should monitor, as well as their digital fingerprint
! 12: (along with the hashing algorithm used to produce this fingerprint), and
! 13: various flags that will be discussed later.
! 15: Then, whenever an application tries to open a file, there is a
! 16: [kauth(9)](http://netbsd.gw.com/cgi-bin/man-cgi?kauth+9+NetBSD-current) check
! 17: before actually doing so if the application is permitted to do so. Veriexec
! 18: hooks in here and checks whether the file has the fingerprint as recorded in
! 19: the signature file. If not, it acts depending on its mode, e.g., it could deny
! 20: file access if the fingerprints mismatch.
! 22: To secure your system with veriexec, you need a kernel with the option
! 23: `veriexec` enabled (as it is in the default kernel), and you need support for
! 24: the algorithms you want to use (by default, all are activated). Then, you
! 25: decide which files you want to monitor, generate a signatures file and make it
! 26: load at boot.
! 28: ## Signatures file
! 30: An entry in the Veriexec signatures file looks like this:
! 32: /path/to/file algorithm fingerprint flags
! 34: With
! 36: * `/path/to`file` is the absolute (!) path to the monitored file.
! 37: * `algorithm` is the used algorithm. It is one of `MD5`, `SHA1`, `SHA256`,
! 38: `SHA384`, `SHA512`, `RMD160`.
! 39: * `fingerprint` is the signature of the file.
! 40: * `flags` describe the monitoring type of the file, as described below.
! 42: ### Generating fingerprints
! 44: You can generate ASCII fingerprints for each algorithm using the following
! 45: tools:
! 47: * **MD5** -- `/usr/bin/cksum -a md5`
! 48: * **SHA1** -- `/usr/bin/cksum -a sha1`
! 49: * **SHA256** -- `/usr/bin/cksum -a sha256`
! 50: * **SHA384** -- `/usr/bin/cksum -a sha384`
! 51: * **SHA512** -- `/usr/bin/cksum -a sha512`
! 52: * **RMD160** -- `/usr/bin/cksum -a rmd160`
! 54: For example, to generate a MD5 fingerprint for `/bin/ls`:
! 56: % cksum -a md5 < /bin/ls
! 57: a8b525da46e758778564308ed9b1e493
! 59: And to generate a SHA512 fingerprint for `/bin/ps`:
! 61: % cksum -a sha512 < /bin/ps
! 62: 381d4ad64fd47800897446a2026eca42151e03adeae158db5a34d12c529559113d928a9fef9a7c4615d257688d1da4645db004081030d7f080bb7198067eb890
! 64: #### veriexecgen
! 66: [veriexecgen(8)](http://netbsd.gw.com/cgi-bin/man-cgi?veriexecgen+8+NetBSD-current)
! 67: is a tool which automatically creates fingerprints for files or directories.
! 68: By default, it will create SHA256 fingerprints for `/bin`, `/sbin`, `/usr/bin`,
! 69: `/usr/sbin`, `/lib`, `/usr/lib`, `/libexec` and `/usr/libexec` and save them to
! 70: `/etc/signatures`.
! 72: You can also specify other algorithms and directories to be searched, e.g., you
! 73: might want to include fingerprints of the packages you installed (though you
! 74: have to be careful to recreate fingerprints on the next package update!).
! 76: ### veriexecctl
! 78: For controlling the database inside the kernel, you have the tool
! 79: [veriexecctl(8)](http://netbsd.gw.com/cgi-bin/man-cgi?veriexecctl+8+NetBSD-current).
! 80: It can be used for dumping the whole database (`dump`), flushing it (`flush`),
! 81: i.e., deleting all entries in the kernel's table, query an entry, etc.
! 83: ### Flags
! 85: Each entry may be associated with zero or more flags. Currently, these flags
! 86: indicate how the file the entry is describing should be accessed. Note that
! 87: this access type is enforced only in strict level 2 (IPS mode) and above.
! 89: The access types you can use are `DIRECT`, `INDIRECT`, and `FILE`.
! 91: #### DIRECT
! 93: `DIRECT` access means that the file is executed directly, and not invoked as an
! 94: interpreter for some script, or opened with an editor. Usually, most programs
! 95: you use will be accessed using this mode:
! 97: $ ls /tmp # `ls` is the executed file
! 98: $ cp ~/foo /tmp/bar # `cp` is the executed file
! 99: $ rm ~/foo # `rm` is the executed file
! 101: #### INDIRECT
! 103: `INDIRECT` access means that the file is executed indirectly, and is invoked to
! 104: interpret a script. This happens usually when scripts have a shebang (`\#!`)
! 105: magic as their first line. For example, if you have a script with the following
! 106: as its first line:
! 108: #!/bin/sh
! 110: And you run it as:
! 112: $ ./script.sh
! 114: Then `/bin/sh` will be executed indirectly -- it will be invoked to interpret
! 115: the script.
! 117: #### FILE
! 119: `FILE` entries refer to everything which is not (or should not) be an
! 120: executable. This includes shared libraries, configuration files, etc.
! 121: Everything you want to have monitored.
! 123: ### Examples
! 125: Some examples for Veriexec signature file entries:
! 127: /bin/ls MD5 dc2e14dc84bdefff4bf9777958c1b20b DIRECT
! 128: /usr/bin/perl MD5 914aa8aa47ebd79ccd7909a09ed61f81 INDIRECT
! 129: /etc/pf.conf MD5 950e1dd6fcb3f27df1bf6accf7029f7d FILE
! 131: Veriexec allows you to specify more than one way to access a file in an entry.
! 132: For example, even though `/usr/bin/perl` is mostly used as an interpreter, it
! 133: may be desired to be able to execute it directly, too:
! 135: /usr/bin/perl MD5 914aa8aa47ebd79ccd7909a09ed61f81 DIRECT, INDIRECT
! 137: Shell scripts using `\#!` magic to be executable also require two access types:
! 138: We need them to be `DIRECT` so we can execute them, and we need them to be
! 139: `FILE` so that the kernel can feed their contents to the interpreter they
! 140: define:
! 142: /usr/src/build.sh MD5 e80dbb4c047ecc1d84053174c1e9264a DIRECT, FILE
! 144: To make it easier to create signature files, and to make the signature files
! 145: themselves more readable, Veriexec allows you to use the following aliases:
! 147: [[!table data="""
! 148: `Alias` | `Expansion`
! 149: `PROGRAM`|`DIRECT`
! 150: `INTERPRETER`|`INDIRECT`
! 151: `SCRIPT`|`DIRECT, FILE`
! 152: `LIBRARY`|`FILE`
! 153: """]]
! 155: Sample scripts for generating fingerprints are available in
! 156: `/usr/share/examples/veriexecctl`. After you've generated a signatures file,
! 157: you should save it as `/etc/signatures`, and enable Veriexec in `rc.conf`:
! 159: veriexec=YES
! 161: ## Strict levels
! 163: Since different people might want to use Veriexec for different purposes, we
! 164: also define four strict levels, ranging 0-3, and named `learning`, `IDS`,
! 165: `IPS`, and `lockdown` modes.
! 167: * *strict level 0* is the *learning mode*. In this level, Veriexec will act
! 168: passively and simply warn about any anomalies. Combined with verbose level
! 169: 1, running the system in this mode can help you fine-tune the signatures
! 170: file. This is also the only strict level in which you can load new entries
! 171: to the kernel.
! 173: * *strict level 1* is the *IDS mode* (Intrusion Detection System Mode). Now,
! 174: Veriexec will deny access to files with a fingerprint mismatch. This mode
! 175: suits mostly to users who simply want to prevent access to files which
! 176: might've been maliciously modified by an attacker.
! 178: * *strict level 2*, the *IPS mode* (Intrusion Protection System Mode): This
! 179: level takes a step towards trying to protect the integrity of monitored
! 180: files. In addition to preventing access to files with a fingerprint
! 181: mismatch, it will also deny write access and prevent the removal of
! 182: monitored files, and enforce the way monitored files are accessed (as the
! 183: signatures file specifies).
! 185: * *strict level 3*, named *Lockdown mode* is the most restricted mode.
! 186: Lockdown mode can be used in highly critical situations such as custom made
! 187: special-purpose machines, or as a last line of defense after an attacker
! 188: compromised the system and we want to prevent traces from being removed, so
! 189: we can perform post-mortem analysis. It will prevent the creation of new
! 190: files, and deny access to files not monitored by Veriexec.
! 192: It's recommended to first run Veriexec in strict level 0 and verbose level 1 to
! 193: fine-tune your signatures file and getting used to Veriexec, ensuring that
! 194: desired applications run correctly, and only then raise the strict level (and
! 195: lower the verbosity level). You can use `/etc/sysctl.conf` to auto raise the
! 196: strict level to the desired level after a reboot:
! 198: kern.veriexec.strict=1
! 200: Or you can also increase while the system is running (though this undermines
! 201: some of the security Veriexec provides):
! 203: sysctl -w kern.veriexec.strict=1
! 205: ## Veriexec and layered file systems
! 207: Veriexec can be used on NFS file systems on the client side and on layered file
! 208: systems such as nullfs. The files residing on these file systems need only be
! 209: specified in the `/etc/signatures` file and that the file systems be mounted
! 210: prior to the fingerprints being loaded.
! 212: If you are going to use layered file systems, you must ensure that you include
! 213: the fingerprint for files you want protected at every layer. If you fail to do
! 214: this, someone could overwrite a file protected by Veriexec by using a different
! 215: layer in a layered file system stack. This limitation may be removed in later
! 216: versions of NetBSD.
! 218: It's recommended that if you are not going to use layered file systems nor NFS,
! 219: then these features should be disabled in they kernel configuration. If you
! 220: need to use layered file systems, you have to follow the instructions in the
! 221: previous paragraph and ensure that the files you want protected have
! 222: fingerprints at all layers. You should also raise securelevel to 2 after all
! 223: mounts are done to prevent new layers from being mounted, which could
! 224: compromise Veriexec's protection:
! 226: kern.securelevel=2
! 228: ## Kernel configuration
! 230: To use Veriexec, aside from creating a signatures file, you need a kernel with
! 231: Veriexec enabled. It is already enabled in the default (*GENERIC*) kernel, but
! 232: if you built your own one, you have to uncomment the following line in the
! 233: configuration:
! 235: pseudo-device veriexec
! 237: Then, you need to enable the hashing algorithms you wish to support:
! 239: options VERIFIED_EXEC_FP_MD5
! 240: options VERIFIED_EXEC_FP_SHA1
! 241: options VERIFIED_EXEC_FP_RMD160
! 242: options VERIFIED_EXEC_FP_SHA512
! 243: options VERIFIED_EXEC_FP_SHA384
! 244: options VERIFIED_EXEC_FP_SHA256
! 246: Depending on your operating system version and platform, these may already be
! 247: enabled. Once done, rebuild and reinstall your kernel, see
! 248: [[Compiling the kernel|guide/kernel]] for further instructions.
! 250: If you do not have the Veriexec device `/dev/veriexec`, you can create it
! 251: manually by running the following command:
! 253: # cd /dev
! 254: # sh MAKEDEV veriexec
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb