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

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

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb