Annotation of wikisrc/guide/veriexec.mdwn, revision 1.4

1.1       jdf         1: # NetBSD Veriexec subsystem
                      2: 
                      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.
                      6: 
                      7: ## How it works
                      8: 
                      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.
                     14: 
                     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.
                     21: 
                     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.
                     27: 
                     28: ## Signatures file
                     29: 
                     30: An entry in the Veriexec signatures file looks like this:
                     31: 
                     32:     /path/to/file algorithm fingerprint flags
                     33: 
                     34: With
                     35: 
1.2       jdf        36:  * `/path/to/file` is the absolute (!) path to the monitored file.
1.1       jdf        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.
                     41: 
                     42: ### Generating fingerprints
                     43: 
                     44: You can generate ASCII fingerprints for each algorithm using the following
                     45: tools:
                     46: 
                     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`
                     53: 
                     54: For example, to generate a MD5 fingerprint for `/bin/ls`:
                     55: 
                     56:     % cksum -a md5 < /bin/ls
                     57:     a8b525da46e758778564308ed9b1e493
                     58: 
                     59: And to generate a SHA512 fingerprint for `/bin/ps`:
                     60: 
                     61:     % cksum -a sha512 < /bin/ps
                     62:     381d4ad64fd47800897446a2026eca42151e03adeae158db5a34d12c529559113d928a9fef9a7c4615d257688d1da4645db004081030d7f080bb7198067eb890
                     63: 
                     64: #### veriexecgen
                     65: 
                     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`.
                     71: 
                     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!).
                     75: 
                     76: ### veriexecctl
                     77: 
                     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.
                     82: 
                     83: ### Flags
                     84: 
                     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.
                     88: 
                     89: The access types you can use are `DIRECT`, `INDIRECT`, and `FILE`.
                     90: 
                     91: #### DIRECT
                     92: 
                     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:
                     96: 
                     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
                    100: 
                    101: #### INDIRECT
                    102: 
                    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:
                    107: 
                    108:     #!/bin/sh
                    109: 
                    110: And you run it as:
                    111: 
                    112:     $ ./script.sh
                    113: 
                    114: Then `/bin/sh` will be executed indirectly -- it will be invoked to interpret
                    115: the script.
                    116: 
                    117: #### FILE
                    118: 
                    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.
                    122: 
                    123: ### Examples
                    124: 
                    125: Some examples for Veriexec signature file entries:
                    126: 
                    127:     /bin/ls         MD5 dc2e14dc84bdefff4bf9777958c1b20b DIRECT
                    128:     /usr/bin/perl   MD5 914aa8aa47ebd79ccd7909a09ed61f81 INDIRECT
                    129:     /etc/pf.conf    MD5 950e1dd6fcb3f27df1bf6accf7029f7d FILE
                    130: 
                    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:
                    134: 
                    135:     /usr/bin/perl MD5 914aa8aa47ebd79ccd7909a09ed61f81 DIRECT, INDIRECT
                    136: 
                    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:
                    141: 
                    142:     /usr/src/build.sh MD5 e80dbb4c047ecc1d84053174c1e9264a DIRECT, FILE
                    143: 
                    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:
                    146: 
                    147: [[!table data="""
                    148: `Alias` | `Expansion`
                    149: `PROGRAM`|`DIRECT`
                    150: `INTERPRETER`|`INDIRECT`
                    151: `SCRIPT`|`DIRECT, FILE`
                    152: `LIBRARY`|`FILE`
                    153: """]]
                    154: 
                    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`:
                    158: 
                    159:     veriexec=YES
                    160: 
                    161: ## Strict levels
                    162: 
                    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.
                    166: 
                    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.
                    172: 
                    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.
                    177: 
1.3       jdf       178:  * *strict level 2*, the *IPS mode* (Intrusion Prevention System Mode): This
1.1       jdf       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).
                    184: 
                    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.
                    191: 
                    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:
                    197: 
                    198:     kern.veriexec.strict=1
                    199: 
                    200: Or you can also increase while the system is running (though this undermines
                    201: some of the security Veriexec provides):
                    202: 
                    203:     sysctl -w kern.veriexec.strict=1
                    204: 
                    205: ## Veriexec and layered file systems
                    206: 
                    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.
                    211: 
                    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.
                    217: 
                    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:
                    225: 
                    226:     kern.securelevel=2
                    227: 
                    228: ## Kernel configuration
                    229: 
                    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:
                    234: 
                    235:     pseudo-device veriexec
                    236: 
                    237: Then, you need to enable the hashing algorithms you wish to support:
                    238: 
                    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
                    245: 
                    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.
                    249: 
                    250: If you do not have the Veriexec device `/dev/veriexec`, you can create it
                    251: manually by running the following command:
                    252: 
                    253:     # cd /dev
1.4     ! jdf       254:     # sh MAKEDEV veriexec
1.1       jdf       255: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb