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

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: 
        !            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.
        !            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: 
        !           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).
        !           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
        !           254:     # sh MAKEDEV veriexec 
        !           255: 

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