Annotation of wikisrc/guide/veriexec.mdwn, revision 1.3
1.1 jdf 1: # NetBSD Veriexec subsystem
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
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.
42: ### Generating fingerprints
44: You can generate ASCII fingerprints for each algorithm using the following
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
59: And to generate a SHA512 fingerprint for `/bin/ps`:
61: % cksum -a sha512 < /bin/ps
64: #### veriexecgen
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
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
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:
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
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`
151: `SCRIPT`|`DIRECT, FILE`
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`:
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.
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).
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:
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:
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
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