/ 0]-secadm-(English).md
0]-secadm-(English).md
1 # secadm 2 3 * Authors: Shawn Webb <shawn.webb@hardenedbsd.org>, Brian Salcedo <brian.salcedo@hardenedbsd.org> 4 * Copyright (c) 2014, 2015 Shawn webb <shawn.webb@hardenedbsd.org> 5 * License: 2-Clause BSD License 6 7 https://git.hardenedbsd.org/hardenedbsd/secadm 8 9 ## Introduction 10 11 secadm is a project to replace the mac_bsdextended(4)/ugidfw(8) 12 integration the HardenedBSD project has done for ASLR, SEGVGUARD, and 13 PTrace hardening. The secadm project will be implemented as a custom 14 ports entry in the HardenedBSD/freebsd-ports repo. The port will 15 consist of three parts: a kernel module that integrates with the MAC 16 framework, a shared library that communicates between kernel and 17 userland, and an application that consumes the shared library. 18 19 The MAC module will work on a per-jail basis. It will communicate 20 with userland via a sysctl node. The MAC module should hook into the 21 execve() call to set per-process security/hardening flags, such as 22 toggling ASLR or SEGVGUARD. Each jail manages its own rules. Rules 23 applied in one jail do not interact or impact other jails. 24 25 The shared library will be named libsecadm and will simply act as a 26 communication layer between userland applications and the sysctl. 27 The shared library will perform the same sanitization and sanity 28 checking on all rule changes, including the removal of rules, that the 29 MAC module performs. 30 31 The userland application will be named secadm. It will consume libsecadm 32 and libucl. Rules will be written in json to allow for a 33 configuration file format that is readable and parseable by both 34 humans and machines. Using the json format will also allow for 35 additional flexibility and dynamic content. One can imagine secadm 36 deployed in a security appliance where the rulesets are created and 37 updated via a web service API. 38 39 secadm supports toggling ASLR, mmap(MAP_32BIT), SEGVGUARD, SHLIBRANDOM, 40 PAGEEXEC, and MPROTECT restrictions. As of version 0.2, secadm also 41 introduces a new Integriforce feature. Integriforce ensures executable 42 file integrity prior to execution. 43 44 ## About Version 0.3.0 45 46 Version 0.3.0 is a complete rewrite of secadm. You'll notice that 47 commands like `secadm set` and `secadm list` no longer work. They have 48 been replaced by `secadm load /path/to/file` and `secadm show` 49 respectively. Additionally, individual rules can be added and deleted 50 with the `secadm add` and `secadm del` commands. Rules can be enabled 51 and disabled with the `secadm enable` and `secadm disable` commands. 52 53 The flags that can be passed to `secadm add pax` are: 54 55 * A, a: Enable, disable ASLR 56 * B, b: Enable, disable mmap(MAP_32BIT) protection 57 * L, l: Enable, disable SHLIBRANDOM 58 * M, m: Enable, disable MPROTECT 59 * P, p: Enable, disable PAGEEXEC 60 * S, s: Enable, disable SEGVGUARD 61 * O, o: Enable, disable hbsdcontrol based FS-EA rules overriding 62 63 By default, `secadm show` will show the active ruleset in abbreviated 64 format. secadm now integrates with libxo to provide ruleset output in 65 JSON, UCL, or XML formats. Specify a different format by using the -f 66 option to `secadm show`. For example, `secadm show -f ucl`. 67 68 ## Order of rule evaluation 69 70 When the kernel is compiled with the PAX_CONTROL_EXTATTR kernel option, the 71 order of the evaluation is secadm then hbsdcontrol. This ensures that 72 the hbsdcontrol's settings always take precedence. To make secadm's 73 rules take precedence, use the O flag for that rule (prefer_acl is the 74 long option). 75 76 ## Requirements 77 78 * HardenedBSD version 1200055 or greater: 79 - `sysctl hardening.version` should show 1200055 80 * HardenedBSD kernel compiled with options PAX_CONTROL_ACL 81 * textproc/libucl 82 * textproc/libxo 83 84 ## Installation And Usage 85 86 ``` 87 # make 88 # make depend all install 89 ``` 90 91 To list which per-applicatin features your version of secadm supports: 92 93 ``` 94 # secadm list features 95 ``` 96 97 To load the secadm kernel module: 98 99 ``` 100 # kldload secadm 101 ``` 102 103 Copy the sample ruleset to the right spot: 104 105 ``` 106 # cp etc/secadm-desktop.rules.example /usr/local/etc/secadm.rules 107 ``` 108 109 Edit your rules: 110 111 ``` 112 # vi /usr/local/etc/secadm.rules 113 ``` 114 115 Activate them. Please note that setting a new ruleset will flush your 116 previously-loaded rules. 117 118 ``` 119 # secadm load /usr/local/etc/secadm.rules 120 ``` 121 122 To verify that your ruleset loaded successfully: 123 124 ``` 125 # secadm list 126 ``` 127 128 To flush rules: 129 130 ``` 131 # secadm flush 132 ``` 133 134 Installing to a Jail 135 ------------------------ 136 The libsecadm shared library and secadm userland application must both be 137 installed into, or be accessible by, each jail individually in order to 138 enforce security policies inside of the jail. 139 140 Note: if jails are setup to use a read-only basejail, manual installation 141 of libsecadm.0.so into the basejail's /usr/lib directory is required. 142 143 Writing Application Rules 144 ========================= 145 146 secadm currently supports toggling ASLR, SEGVGUARD, mprotect(exec) 147 hardening, and on certain HardenedBSD builds, PAGEEXEC hardening. In 148 the etc directory, you will find secadm.rules.sample, which shows 149 how to write rules. 150 You can use the prefer_acl keyword, to ensure secadm's rule takes 151 in effect over the file system extended attributes based settings. 152 153 secadm uses libucl for parsing its config file. As it stands right 154 now, the order of the rules do not matter, but that could change with 155 time as we add new features. The sample config file is in a relaxed 156 JSON format, though libucl supports different syntaxes. Please refer 157 to libucl's documentation for help in learning the different possible 158 syntaxes. 159 160 ``` 161 secadm { 162 pax { 163 path: "/bin/ls", 164 aslr: false, 165 segvguard: false 166 }, 167 pax { 168 path: "/bin/pwd", 169 mprotect: true, 170 pageexec: true, 171 prefer_acl: true 172 } 173 } 174 ``` 175 176 ## Integriforce 177 178 secadm version 0.2 supports a new feature, called Integriforce. This 179 feature provides executable file integrity enforcement. If a rule 180 exists for a given file, that file's hash as defined in the rule is 181 matched against the hash of the file. If the hashes don't match, 182 execution may be disallowed, depending on the configuration settings. 183 Integriforce is an optional, but powerful, feature. Integriforce 184 currently supports only SHA1 or SHA256. 185 186 NOTE: Files that are under Integriforce management cannot be modified 187 or deleted. The ruleset will need to be flushed prior to 188 modifying or deleting the file. 189 190 ### Configuring Integriforce 191 192 In the root object of the configuration file, secadm will look for an 193 integriforce object. In the integriforce object, add a files array. In 194 the files array, place an array of objects, where each object contains 195 the following options: 196 197 1. mode (string, default "hard"): If set, this must equal either 198 "soft" or "hard". Soft mode means execution is allowed if hashes don't 199 match, but a warning message is printed. Hard mode prints an error 200 messages and disallows execution. 201 1. files (array of objects): Each object must contain the following 202 fields: 203 1. path (string): The path to the executable. 204 1. hash (string): The hash (sha1 or sha256) of the executable. 205 1. type (string): Either "sha1" or "sha256". 206 1. mode (optional, string, default to inherit): The enforcing 207 mode for this file. 208 209 Example config: 210 211 ``` 212 secadm { 213 integriforce { 214 path: "/bin/ls", 215 hash: "873e49767e36f80a8814f41c90c98d888c83eeb4fe2fcab155b5ecb6cc6b67f6", 216 type: "sha256", 217 mode: "hard" 218 } 219 } 220 ``` 221 222 ### Strict Application Allow Listing 223 224 When Integriforce rules have been added, `secadm` can be placed in 225 strict application allow (whitelist) mode. `secadm` will prohibit the 226 execution of applications and the loading of shared libraries not 227 having a corresponding entry in the Integriforce configuration. 228 229 To enable strict application allow list mode: 230 231 ``` 232 # secadm set -W 233 ``` 234 235 To disable strict application allow list mode: 236 237 ``` 238 # secadm set -w 239 ``` 240 241 To enable strict application allow list mode in the `secadm` 242 configuration file: 243 244 ``` 245 secadm { 246 whitelist_mode: true 247 } 248 ``` 249 250 Adding secadm itself and the shared libraries it depends on to the 251 Integriforce configuration is highly recommended. Otherwise, the 252 secadm configuration cannot be changed without first rebooting the 253 system. 254 255 ## Trusted Path Execution (TPE) 256 257 Trusted Path Execution prevents users from directly executing binaries 258 in untrusted directories. A trusted directory is defined as a 259 directory that is writable only by root and owned by root. The current 260 TPE implementation does not handle the indirect execution of scripts. 261 262 TPE options that can be set: 263 264 1. `enable`: 265 * Required. Type: Boolean 266 * Description: Enable TPE protections. 267 1. `all`: 268 * Optional. Type: Boolean 269 * Description: Enable TPE for all users. 270 1. `invert`: 271 * Optional. Type: Boolean 272 * Description: Invert the Group ID (GID) logic. 273 1. `gid`: 274 * Optional. Type: Integer 275 * Description: Group ID for which TPE is applied. 276 277 The enable TPE via the command-line: 278 279 ``` 280 # secadm tpe -TA 281 ``` 282 283 Configuring TPE in the `secadm` configuation file: 284 285 ``` 286 secadm { 287 tpe { 288 enable: true, 289 all: true, 290 invert: false, 291 gid: 1000 292 } 293 } 294 ``` 295 296 ## Note About ABI and API Stability 297 298 Both the userland and kernel ABI and API are under heavy development. 299 Though care has been taken to keep future changes and features in 300 mind, the API and ABI are not stable and may change from release to 301 release. If you plan to develop third-party applications that consume 302 libsecadm, please do so at your own risk. If you feel you need added 303 features or a change to an existing feature, please file a bug report 304 at secadm's issue tracker at HardenedBSD's self-hosted GitLab 305 instance.